This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/main by this push:
new a5dc289 Add a documentation section about schema changes and
migrations
a5dc289 is described below
commit a5dc289e9e6576013c24b0cd6884912edc0dae39
Author: Sean B. Palmer <[email protected]>
AuthorDate: Mon Jan 12 16:00:09 2026 +0000
Add a documentation section about schema changes and migrations
---
atr/docs/database.md | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/atr/docs/database.md b/atr/docs/database.md
index 4c6f74a..a4fc288 100644
--- a/atr/docs/database.md
+++ b/atr/docs/database.md
@@ -11,6 +11,7 @@
* [Introduction](#introduction)
* [Core models](#core-models)
* [Other features](#other-features)
+* [Schema changes and migrations](#schema-changes-and-migrations)
## Introduction
@@ -61,3 +62,17 @@ Projects have many computed properties that provide access
to release policy set
Database constraints ensure data integrity. The
[`Task`](/ref/atr/models/sql.py:Task) model includes a check constraint that
validates the status transitions. A task must start in `QUEUED` state, can only
transition to `ACTIVE` when `started` and `pid` are set, and can only reach
`COMPLETED` or `FAILED` when the `completed` timestamp is set. These
constraints prevent invalid state transitions at the database level.
Unique constraints ensure that certain combinations of fields are unique. The
`Release` model has a unique constraint on `(project_name, version)` to prevent
creating duplicate releases for the same project version. The `Revision` model
has two unique constraints: one on `(release_name, seq)` and another on
`(release_name, number)`, ensuring that revision numbers are unique within a
release.
+
+## Schema changes and migrations
+
+We often have to make changes to the database model in ATR, whether that be to
add a whole new model or just to rename or change some existing properties. No
matter the change, this involves creating a database migration. We use Alembic
to perform migrations, and this allows migrations to be _bidirectional_: we can
downgrade as well as upgrade. This can be very helpful when, for example, a
migration didn't apply properly or is no longer needed due to having found a
different solution.
+
+To change the database, do not edit the SQLite directly. Instead, change the
model file in [`atr/models/sql.py`](/ref/atr/models/sql.py). If you're running
ATR locally, you should see from its logs that the server is now broken due to
having a mismatching database. That's fine! This is the point where you now
create the migration. To do so, run:
+
+```shell
+uv run --frozen alembic revision -m "Description of changes" --autogenerate
+```
+
+Obviously, change `"Description of changes"` to an actual description of the
changes that you made. Keep it short, around 50-60 characters. Then when you
restart the server you should find that the migration is automatically applied.
You should be careful, however, before restarting the server. Not all
migrations apply successfully when autogenerated. Always review the
automatically produced migrations in `migrations/versions` first, and ensure
that they are correct before proceeding. On [...]
+
+It can be helpful to make a backup of the entire SQLite database before
performing the migration, especially if the migration is particularly complex.
This can help if, for example, the downgrade is broken, otherwise you may find
yourself in a state from which there is no easy recovery. _Always_ ensure that
migrations are working locally before pushing them to GitHub, because we apply
changes from GitHub directly to our deployed containers. Note that sometimes
the deployed containers con [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
