Read the Docs and PostgreSQL: Schema Migration Rollback Behavior

Question

Database State Management during Upgrades
Read the Docs utilizes the Django migration system to manage its PostgreSQL schema. During instance upgrades, migrations are applied to the database to ensure compatibility with the new release. However, the current architecture does not provide an automated mechanism to revert these changes if a deployment fails or if a specific migration introduces instability.

Transactional Integrity and Recovery
When a schema change is applied, the system relies on manual intervention via management commands to return to a previous state. There is an unresolved design consideration regarding whether migration steps should be wrapped in transactions to allow for automatic rollbacks upon failure, particularly for environments integrated with automated build triggers.

Current behavior requires manual execution of migration reverts.
Partial migration states may persist if an error occurs during the upgrade process.

Does the current stable v2.0 series support transactional migration wrappers to prevent partial schema updates? If not, what is the recommended strategy for ensuring schema consistency without relying on full database restores?

Tasadduq Burney · Answer

Transactional Migration Support

The Read the Docs (RTD) v2.0 series utilizes the Django migration framework. Because it targets PostgreSQL, transactional migration wrappers are supported and enabled by default. Django wraps each migration in a transaction, meaning if a migration fails midway, PostgreSQL rolls back the changes to the state prior to that specific migration's start.

When Partial Schema Updates Occur

Despite default transactional behavior, partial schema updates can still persist in the following scenarios:

Non-Atomic Migrations: Any migration explicitly marked with atomic = False bypasses the transaction wrapper.
Unsupported Operations: Certain PostgreSQL operations cannot be executed within a transaction block (e.g., CREATE INDEX CONCURRENTLY). These must be run with atomic = False, leaving the database in a partial state if they fail.
Multi-Migration Failures: If a deployment applies five migrations and the fifth one fails, the first four remain committed. The system does not automatically roll back the entire deployment batch.

Recommended Strategy for Schema Consistency

To ensure consistency without relying on full database restores, implement the following workflow:

Verify Migration Atomicity: Audit custom migrations for atomic = False. If a migration must be non-atomic, ensure it is idempotent so it can be safely re-run.
Targeted Reverts: Use the Django management command to roll back to a known stable migration state:
```
python manage.py migrate <app_name> <migration_name>
```
Note: This requires the migration to have a defined reverse operation.
Pre-Deployment Validation: Run migrations against a restored copy of the production database in a staging environment to catch failures before they hit the live instance.
Point-in-Time Recovery (PITR): For critical failures where manual reverts are impossible (e.g., missing reverse operations), utilize PostgreSQL WAL archiving for PITR rather than a full cold restore.

Verification Steps

To verify the current state of your schema after a failed upgrade, run:

python manage.py showmigrations

Check for migrations that are marked as applied ([X]) but may have failed partially due to atomic = False settings.

Read the Docs and PostgreSQL: Schema Migration Rollback Behavior

Database State Management during Upgrades

Transactional Integrity and Recovery

1 answer

Transactional Migration Support

When Partial Schema Updates Occur

Recommended Strategy for Schema Consistency

Verification Steps

Your perspective belongs here.

0 question comments