Lesson 20 / 22 · Commentail 1.3.2
An upgrade can change database state, assets and template contracts as well as Python files. Rehearse on a restored copy; never test restoration over your only database.
Preserve a consistent snapshot
Protect the current wheel/dependency versions, settings, overrides, media and secrets. Retain the same SECRET_KEY because existing Commentail links depend on it. Do not attach secrets to a public issue or course archive.
For final cutover pause website writes and the worker. Back up SQLite through its backup API instead of copying a live file without its journal:
import sqlite3
with sqlite3.connect("db.sqlite3") as source:
with sqlite3.connect("backup.sqlite3") as destination:
source.backup(destination)
Run from the database directory with adapted paths and a new destination file. For PostgreSQL, create a custom-format dump and restore into a separate empty database:
pg_dump -Fc --file=site-backup.dump YOUR_DATABASE
pg_restore --exit-on-error --single-transaction --dbname=YOUR_EMPTY_RESTORE_DATABASE site-backup.dump
Configure connection permissions first. pg_dump does not preserve cluster-wide roles or tablespaces; manage them separately. Check command success and archive readability rather than just file existence.
Rehearse the change
Keep mail local in the restored environment to avoid real duplicate messages. Install the reviewed target release and run migrate, check and collectstatic. Verify existing comments, replies, revisions, permissions, Site/Page settings, overrides and old guest links. Check that imports use the installed package rather than an adjacent checkout.
Read the target and every intervening release note. Upgrading 1.3.1 to 1.3.2 adds no migration. Upgrading from 1.3.0 or earlier includes irreversible 0018: stop old writers and workers, retain SECRET_KEY and never run old and new application code against the same database. Large ledgers can require time, locks and transaction space.
Understand rollback
Replacing the wheel does not reverse data transformations. Test restoring the matching old database, package and key before production. Restoring a snapshot discards later writes. Its queue may include messages sent after that snapshot, so keep the worker paused until reviewing jobs.
After an authorized live upgrade, recheck the real domain, mail and proxies, refresh static assets and restart processes. Successful migrations do not establish that the reader flow works.
Related lessons
- 13. Override templates and action pages
- 19. Production nginx, caching and user data
- 21. Troubleshoot a Commentail installation
Choose a sign-in method or comment as a guest below.