Summary
Key takeaways
- The two Django upgrade rehearsals used Python 3.12, SQLite, and previously seeded application databases.
- The API fixture passed Django 5.2.19 to 6.0.10 and then 6.0.10 to 6.1.3.
- The SaaS fixture passed its upgrade to Django 6.0.10 but could not resolve its pinned dependencies for 6.1.3.
- The blocker was django-celery-beat 2.9.0, whose installer constraint excludes Django 6.1.
- Three of the four attempted upgrade steps passed runtime checks; one stopped during dependency resolution.
- The API tests covered filtered output, email serialization, CORS behavior, seeded account preservation, and SQLite integrity.
- The SaaS tests covered login, a verified email record, a saved ten-minute periodic schedule, and SQLite integrity.
- Passing an installer check is not proof that migrations and business behavior will remain correct.
- The SaaS rehearsal checked persisted schedule records, not worker execution, broker connectivity, or end-to-end tasks.
- Production readiness requires tests and rollback planning specific to the application, database, dependencies, and integrations.
When this applies
Use this index when planning a Django upgrade for an existing API or SaaS application with pinned dependencies and stored data. It is particularly useful for checking third-party package constraints, rehearsing sequential Django releases, and documenting business-critical behavior before a staged rollout.
When this does not apply
These small Python 3.12 and SQLite fixtures do not establish production readiness for another application’s database backend, data volume, authentication extensions, task workers, broker connectivity, or integrations. The observed results apply to the pinned versions and checks recorded in this edition.
Checklist
- Record the source Django version, Python runtime, and database engine.
- Export the application’s exact dependency pins and transitive constraints.
- Review Django, database adapter, authentication, scheduling, admin plugin, and testing-tool requirements.
- Compare package version classifiers with installer constraints.
- Run a resolver dry run for the intended target Django version.
- Record any explicit dependency upper bound that prevents installation.
- Create a seeded or sanitized database clone from the source version.
- Rehearse adjacent Django feature-release steps in order.
- Review deprecations and record the exact version and commit at each stage.
- Run Django system checks and apply migrations on the reused database.
- Check row counts, database integrity, and domain-specific invariants.
- Test application behaviors such as login, API filtering, and allowed or rejected origins.
- For scheduled jobs, verify persisted schedules and test actual task execution where required.
- Define reversible migrations, restore or forward-fix procedures, and rollback retry behavior.
- Compare post-cutover error rates, query latency, and background-task completion with a deployment baseline.
Common pitfalls
- Assuming a Django release page alone establishes application upgrade readiness.
- Checking package classifiers without reading the installer’s version constraints.
- Treating a successful pip installation as proof of application compatibility.
- Running migrations against an empty database instead of existing schema and data.
- Skipping adjacent feature releases and their deprecations in the rehearsal.
- Testing framework checks but omitting business-critical behavior and persisted records.
- Interpreting a passing CORS fixture as broad compatibility for every request or origin.
- Inspecting a schedule row without testing workers, brokers, or end-to-end tasks when needed.
- Rolling out without a database-specific backout plan and post-cutover monitoring.
By Uvik Software · Edition 1 · November 2026
A safe Django upgrade starts with your dependency lockfile, then proves that the application still works against an upgraded copy of its database. Uvik Software rehearsed two small application stacks on Python 3.12 and SQLite. The API stack passed from Django 5.2.19 through 6.0.10 to 6.1.3. The SaaS stack passed the first step. Its pinned django-celery-beat 2.9.0 dependency blocked resolution for Django 6.1.3.
A framework release page answers which Django and Python versions can run together. An upgrade plan needs more detail. It must identify which package blocks the new version, what happens to existing data, and which business behavior still passes after migrations. This index records all three for two repeatable applications.
Django upgrade paths tested
Uvik Software created one SQLite database for each profile on Django 5.2.19, seeded it, and reused it across the upgrade steps. Each runtime check ran Django’s system check and migrations. An upgrade passed when the seeded records, profile behavior, and SQLite integrity checks passed on the target version.
| Application profile | Django 5.2.19 baseline | Upgrade to 6.0.10 | Upgrade to 6.1.3 |
|---|---|---|---|
| Django REST API with filter and CORS | Seeded and passed | Passed | Passed |
| SaaS accounts and scheduled jobs | Seeded and passed | Passed | Blocked at dependency resolution |
The API exercise verified that a filtered response contained the correct record, serialized its email value, returned the allowed-origin header, and preserved both seeded accounts. The SaaS exercise verified Django authentication, preservation of a verified email record, and persistence of a ten-minute schedule. It inspected the schedule row. A full application upgrade also needs worker execution, broker connectivity, and end-to-end task checks when they matter to the product.
On the pinned stacks, three of four upgrade steps passed runtime checks. The fourth stopped before installing the target framework. The resolver output identifies the dependency behind that result.
Package constraints and observed behavior
A package can declare Django support in classifiers and separately specify which versions the installer may accept. Read both. Then record the behavior of your exact installed stack.
| Pinned package | Installer constraint on Django | What Uvik Software observed |
|---|---|---|
| djangorestframework 3.18.3 | Django 5.2 or later | The filtered API request worked on both upgrade steps |
| django-filter 26.2 | Django 5.2 or later | The fixture returned only the selected username |
| django-cors-headers 4.9.0 | Django 4.2 or later | CORS worked in this fixture on 6.1.3. The package metadata listed Django through 6.0 |
| django-allauth 65.22.1 | Django 4.2.16 or later | The verified email record survived the upgrade to 6.0.10 |
| django-celery-beat 2.9.0 | Django 2.2 or later, below 6.1 | Schedule record preserved on 6.0.10. Resolver rejected 6.1.3 |
The 6.1 blocker was reproducible using pip 26.2.2. It returned a dependency conflict because the pinned scheduler requires Django below 6.1. Try the same check in a disposable environment.
python -m pip install --dry-run --ignore-installed \
"Django==6.1.3" "django-celery-beat==2.9.0"
Look for a dependency conflict naming both pins. Check the currently supported scheduler release and rehearse the change with the real schedule state before proceeding. The observed passing version for this pinned SaaS fixture was Django 6.0.10. Django’s own release and support pages govern which version your team should target over time. Versioned django-celery-beat metadata · Django supported versions
How to use the index on your application
Check the whole dependency graph
Export your actual pinned versions. Start with Django, Python, database adapters, authentication, task scheduling, admin plugins, and testing tools. Run a resolver dry run against the planned Django patch and inspect transitive constraints. One explicit upper bound can stop the release before migrations begin.
Mark each component as declared, excluded, or undeclared according to its pinned metadata. Give runtime results their own column. In the API fixture, the CORS request worked on a Django version that was absent from the package’s visible classifier list. That result is specific to the request and fixture exercised.
Rehearse adjacent release steps
Move through feature releases in order and review deprecations during each step. Start from a backup or seeded clone of the source version so the tests exercise existing schema and data. For this matrix, the 6.1.3 API check reused the database already migrated on 6.0.10. Record the exact version, commit, and test evidence for every stage. Django’s upgrade guide
Test business behavior after migration
Choose assertions that correspond to how your product is used. Verify a login, a write that affects billing or reporting, or a queue operation your team must replay safely. Check row counts and domain-specific invariants. A successful migration can leave behavior changes that package installation and framework checks cannot detect.
Cross-origin behavior is especially useful for APIs consumed by a different application origin. Verify the origins you expect to work and the origins you expect to reject. In a scheduler migration, prove that persisted schedules can run, that each run is recorded, and that rollback preserves retry behavior.
Plan the staged rollout
Separate dependency updates from application changes where possible. Define which migration steps are reversible and which require restore or a forward fix. Review the backout plan against the database engine and volume you operate. Take a deployment baseline and compare the error rate, query latency, and background task completion immediately after cutover.
Copy this upgrade test record
| Field | What to record |
|---|---|
| Source version and database | Exact Django, Python, database engine, and seeded or sanitized source snapshot |
| Destination pins | Exact framework and resolved packages, including transitive constraints |
| First failing step | Resolve, migrate, system check, or business behavior |
| Expected application behavior | A specific test and its acceptance criterion |
| Observed outcome | Pass, resolver blocked, fixture failed, or untested |
| Next action and evidence | Fix or planned upgrade order, plus a dated log or CI run |
This structure makes the decision auditable. A maintainer should be able to read one row and understand what was tested, which symptom occurred, and what evidence remains before the next release.
Method and interpretation
The rehearsals used Python 3.12.14, SQLite 3.53.1, and synthetic account records. The API fixture opened a filtered endpoint with Django REST framework and sent a request with an origin header. The SaaS fixture used allauth’s email model, Django’s login test client, and a saved Celery Beat interval and periodic task. The independent dry-run check covered the framework and scheduler pins on Django 6.1.3. Data and version checks were run on 18 November 2026.
Use these results as a starting point for the same versions. Real deployment readiness depends on your own Python runtime, database backend, stored data, extensions, load, and integrations. Keep a copy of the fixture and its dependency pins for each edition. Django 5.2 release notes · Django 6.0 release notes · Django 6.1 release notes
Rehearse your Django upgrade before rollout
Uvik Software helps teams stage Django upgrades, improve regression coverage, and modernize dependencies while their products remain in service. Bring the current lockfile, the target release, and the workflows that need to survive the change. Those inputs define an upgrade assessment and an actionable test plan. Uvik Software Django development services · Uvik Software’s legacy Django stabilization case study
Recommended citation. Uvik Software. Django Upgrade Readiness Index. Two Python 3.12 and SQLite application rehearsals, edition 1, November 2026.
Corrections. Send the edition, the affected result or example, and any reproduction details to the Uvik Software team.