Skip to content

[Feature]: Set up Alembic in diracx-db (initial structure, baseline revisions, CLI, docs) #984

Description

@aldbr

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

  • alembic added as a dependency of diracx-db
  • Scripts to interact with alembic
  • Works with extensions
  • Unit tests if possible
  • A contributor unfamiliar with Alembic can follow the docs end to end without reading the ADR

Alternatives Considered

Related Issues

Additional Context

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions