Skip to content

Upgrading from 3.3 to 4.0

TL;DR: zero mandatory changes. Everything new is opt-in. Skip straight to I want feature X.

Are there breaking changes?

No. Your 3.3 code keeps compiling, running and passing tests without touching a line. CI smoke test we ship:

# 3.3 → 4.0 smoke test
class A(dorm.Model):
    name = dorm.CharField(max_length=10)

A.objects.create(name="x")
list(A.objects.filter(name__icontains="x"))
A.objects.bulk_create([A(name=f"a{i}") for i in range(10)])

Only visible change: the version jumps 3.3.0 → 4.0.0 (we skip 3.4 — everything planned for 3.4 ships in this release together with 7 additional features).

Upgrade steps

1. Update the package

pip install --upgrade djanorm
# or
uv add 'djanorm>=4.0,<5.0'

2. (Optional) Install new extras

# DuckDB backend for embedded analytics
pip install 'djanorm[duckdb]'

# Sibling packages (dev tooling)
pip install pytest-djanorm djanorm-mypy

3. (Optional) Adopt 4.0 features

Each on demand — follow the recipes in What's new in 4.0.

4. Re-run your suite

pytest
ruff check
mypy        # with djanorm-mypy plugin if you added it

If something breaks, open an issue — nothing should regress.

I want feature X

I want… Read
Ingest millions of rows fast Bulk COPY
Zero-downtime migration on a big table Online migrations
Detect schema drift in CI dorm diff (CLI)
Row-level multi-tenancy Row tenancy
Trees / categories / comment threads Recursive CTE
Embedded OLAP backend DuckDB
PG pub/sub without a broker LISTEN/NOTIFY
Outbox pattern for microservices Outbox
Horizontal sharding Sharding
Idempotency keys (Stripe-style) Idempotency
Circuit breaker Circuit breaker
Read replicas with lag check Lag router
Streaming JSONL/CSV exports Helpers
Query budget (HTTP SLA) Helpers
Geometries / GIS GIS
HStore / native PG ENUM v4.0
Full-text search + trigram v4.0
Enriched OTel traces v4.0
mypy validating filter() kwargs Sibling packages
pytest fixtures transactional_db Sibling packages

4.0 design decisions

Things we deliberately did NOT add:

  • No dorm.contrib.fastapi — the framework-agnostic helpers cover everything. Coupling the wheel to FastAPI would be unnecessary: 99% of the target audience uses it, but the 1% shouldn't pay. Discussion.
  • No forms — the API-first target uses Pydantic. Coming from Django, migration-from-django has the equivalents.
  • No built-in admin — sqladmin or your custom dashboard. dorm export-json-schema provides the input for external tooling.
  • mypy + pytest plugins in sibling packages — the main wheel doesn't drag in dev-only deps. Rationale.

Versioning from 4.0 onward

  • djanorm 4.x — minor bumps every ~2-3 months with opt-in features. No breaking changes.
  • djanorm-mypy and pytest-djanorm — independently versioned. Each declares djanorm>=4.0,<5.0 for cross compatibility.
  • djanorm 5.0 — someday. We'd telegraph break-points with deprecation warnings during the 4.x line first.

Rollback to 3.3

If you need to revert:

pip install 'djanorm==3.3.0'

Your code keeps working if you did not use 4.0 features (dorm.tree, dorm.contrib.tenants_row, AddFieldOnline, HStoreField, EnumField(native=True), DuckDB, etc.).

If your DB has migrations applying AddFieldOnline or CreatePGEnum, those migrations won't run on 3.3 — back up the DB before and restore on 3.3 if necessary.

More