User Story
As a DiracX administrator,
I want python -m diracx.db upgrade to bring my databases to the schema the running code expects,
So that upgrading never requires me to copy an ALTER TABLE out of a pull-request description.
And, as a DiracX contributor,
I want a how-to page telling me what to do when I add a column,
So that I can write a correct migration without reading the ADR.
As an extension developer,
I want to ship migrations for the tables my extension adds — including tables I attach to a DiracX-owned
database,
So that diracx upgrade on an installation with my extension migrates both DiracX's schema and mine,
and neither one tries to drop the other's tables.
Feature Description
This is the standalone PR that introduces Alembic, agreed in discussion to land before #967 rather
than as part of it. #967 then becomes the first real revision, written by someone following this issue's
documentation — which is the point: it tests the docs.
Implements DX-ADR-003.
Contributor documentation (docs/dev/how-to/change-a-db-schema.md) — part of this issue, not a
follow-up, because the next person to write a migration will work from it.
Note on extensions
Extensions register databases through the diracx.dbs.sql entry point, and they do so in two distinct
ways. The migration design has to handle both, and the second one is what makes this non-trivial.
(a) A brand-new database with its own MetaData. BookkeepingDB (lhcbdiracx),
LollygagDB and MyPilotDB (gubbins) each declare their own DeclarativeBase. Each gets its own
version tree, owned entirely by the extension. Nothing special is needed beyond the discovery mechanism.
(b) Extra tables inside a DiracX-owned database. GubbinsJobDB(JobDB) sets
metadata = JobDBBase.metadata and its GubbinsInfo table inherits JobDBBase, so create_all
produces DiracX's JobDB tables and GubbinsInfo in one pass, in one database, with foreign keys
between them.
That means the JobDB database's alembic_version has to track two heads: DiracX's and the
extension's. Without this, a DiracX-authored --autogenerate sees GubbinsInfo as an unknown table and
proposes DROP TABLE GubbinsInfo.
Definition of Done
Alternatives Considered
Related Issues
Additional Context
User Story
As a DiracX administrator,
I want
python -m diracx.db upgradeto bring my databases to the schema the running code expects,So that upgrading never requires me to copy an
ALTER TABLEout of a pull-request description.And, as a DiracX contributor,
I want a how-to page telling me what to do when I add a column,
So that I can write a correct migration without reading the ADR.
As an extension developer,
I want to ship migrations for the tables my extension adds — including tables I attach to a DiracX-owned
database,
So that
diracx upgradeon an installation with my extension migrates both DiracX's schema and mine,and neither one tries to drop the other's tables.
Feature Description
This is the standalone PR that introduces Alembic, agreed in discussion to land before #967 rather
than as part of it. #967 then becomes the first real revision, written by someone following this issue's
documentation — which is the point: it tests the docs.
Implements DX-ADR-003.
Contributor documentation (
docs/dev/how-to/change-a-db-schema.md) — part of this issue, not afollow-up, because the next person to write a migration will work from it.
Note on extensions
Extensions register databases through the
diracx.dbs.sqlentry point, and they do so in two distinctways. The migration design has to handle both, and the second one is what makes this non-trivial.
(a) A brand-new database with its own
MetaData.BookkeepingDB(lhcbdiracx),LollygagDBandMyPilotDB(gubbins) each declare their ownDeclarativeBase. Each gets its ownversion tree, owned entirely by the extension. Nothing special is needed beyond the discovery mechanism.
(b) Extra tables inside a DiracX-owned database.
GubbinsJobDB(JobDB)setsmetadata = JobDBBase.metadataand itsGubbinsInfotable inheritsJobDBBase, socreate_allproduces DiracX's
JobDBtables andGubbinsInfoin one pass, in one database, with foreign keysbetween them.
That means the
JobDBdatabase'salembic_versionhas to track two heads: DiracX's and theextension's. Without this, a DiracX-authored
--autogenerateseesGubbinsInfoas an unknown table andproposes
DROP TABLE GubbinsInfo.Definition of Done
alembicadded as a dependency ofdiracx-dbAlternatives Considered
Related Issues
Additional Context