From 6f3cd0367c73049a04ad918b5de9bdac4b5b253d Mon Sep 17 00:00:00 2001 From: Juan Pablo Vega Date: Thu, 18 Jun 2026 16:13:14 +0200 Subject: [PATCH] [docs] Add comments / instructions about the new database migrations trees --- api/AGENTS.md | 16 ++++++++++++++ .../postgres/migrations/core/README.md | 7 ++++++ .../tracing/{README copy.md => README.md} | 6 +++++ .../postgres/migrations/core/README.md | 22 +++++++++++++++++++ .../postgres/migrations/tracing/README.md | 7 ++++++ 5 files changed, 58 insertions(+) rename api/ee/databases/postgres/migrations/tracing/{README copy.md => README.md} (83%) diff --git a/api/AGENTS.md b/api/AGENTS.md index ee4137993d..868fd5efaa 100644 --- a/api/AGENTS.md +++ b/api/AGENTS.md @@ -76,6 +76,22 @@ Example to copy: - `api/oss/src/core/workflows/` - `api/oss/src/dbs/postgres/workflows/` +### Database schema migrations (which alembic chain) + +New tables/columns are alembic revisions. The legacy `core/` and `tracing/` chains are +**parked** (frozen at `park00000000`) — never add revisions there. Author against the +active chains: + +- **Shared schema** (the default — runs in both OSS and EE): add the revision **once** in + `oss/databases/postgres/migrations/core_oss/` (or `tracing_oss/`). EE ships and runs the + `oss/` tree, so do **not** copy it into the EE tree. +- **EE-only schema** (genuinely edition-divergent): `ee/databases/postgres/migrations/core_ee/` + (or `tracing_ee/`). + +Full model (version tables, fresh-install/upgrade/OSS→EE-switch flows, FK and replay-skew +rules): `docs/designs/oss-ee-convergence/migration-chains-and-edition-switch.md`. The +parked `core/README.md` covers alembic mechanics. + ### Layering and dependency direction Required direction: diff --git a/api/ee/databases/postgres/migrations/core/README.md b/api/ee/databases/postgres/migrations/core/README.md index 8d8552e3c3..bfe55c3dc5 100644 --- a/api/ee/databases/postgres/migrations/core/README.md +++ b/api/ee/databases/postgres/migrations/core/README.md @@ -1,5 +1,12 @@ # Migrations with Alembic +> [!IMPORTANT] +> **This `core/` chain is PARKED (frozen legacy history).** Do **not** add new revisions +> here — it ends at `park00000000` and never advances. Shared schema changes go in +> `oss/databases/postgres/migrations/core_oss/` (EE ships and runs the `oss/` tree); +> EE-only schema goes in `core_ee/`. Full rules: +> `docs/designs/oss-ee-convergence/migration-chains-and-edition-switch.md`. + Generic single-database configuration with an async dbapi. ## Autogenerate Migrations diff --git a/api/ee/databases/postgres/migrations/tracing/README copy.md b/api/ee/databases/postgres/migrations/tracing/README.md similarity index 83% rename from api/ee/databases/postgres/migrations/tracing/README copy.md rename to api/ee/databases/postgres/migrations/tracing/README.md index 8d8552e3c3..b3171484eb 100644 --- a/api/ee/databases/postgres/migrations/tracing/README copy.md +++ b/api/ee/databases/postgres/migrations/tracing/README.md @@ -1,5 +1,11 @@ # Migrations with Alembic +> [!IMPORTANT] +> **This `tracing/` chain is PARKED (frozen legacy history).** Do **not** add new +> revisions here — it ends at `park00000000` and never advances. Author new tracing +> migrations in `tracing_oss/` (shared, runs in both editions) or `tracing_ee/` (EE-only). +> See `docs/designs/oss-ee-convergence/migration-chains-and-edition-switch.md`. + Generic single-database configuration with an async dbapi. ## Autogenerate Migrations diff --git a/api/oss/databases/postgres/migrations/core/README.md b/api/oss/databases/postgres/migrations/core/README.md index 68c7c04c9e..c60ffe9f2e 100644 --- a/api/oss/databases/postgres/migrations/core/README.md +++ b/api/oss/databases/postgres/migrations/core/README.md @@ -1,5 +1,27 @@ # Migrations with Alembic +> [!IMPORTANT] +> **This `core/` chain is PARKED (frozen legacy history).** Do **not** add new revisions +> here — it ends at `park00000000_park_legacy_chain.py` and never advances. The same +> applies to the parked `tracing/` chain. +> +> Author new migrations in the active chains instead: +> +> | Scope | Chain (author here) | Root | Version table | Runs in | +> |-------|---------------------|------|---------------|---------| +> | shared core schema | `core_oss/` (under `oss/`) | `oss000000000` | `alembic_version_oss` | **OSS and EE** (EE ships the `oss/` tree) | +> | EE-only core schema | `core_ee/` (under `ee/`) | `ee0000000000` | `alembic_version_ee` | EE only | +> | shared tracing schema | `tracing_oss/` | `oss000000000` | `alembic_version_oss` | OSS and EE | +> | EE-only tracing schema | `tracing_ee/` | `ee0000000000` | `alembic_version_ee` | EE only | +> +> Define-once-use-both migrations (most schema changes) go in `core_oss` (or +> `tracing_oss`) — author them **once**, never copy into the EE tree. Only genuinely +> EE-divergent schema goes in `core_ee`/`tracing_ee`. Full rules and the OSS→EE edition +> switch: `docs/designs/oss-ee-convergence/migration-chains-and-edition-switch.md`. +> +> The commands below still describe the alembic mechanics, but swap the `-w .../core` +> working directory for `.../core_oss` (or the right active chain) when creating revisions. + Generic single-database configuration with an async dbapi. ## Autogenerate Migrations diff --git a/api/oss/databases/postgres/migrations/tracing/README.md b/api/oss/databases/postgres/migrations/tracing/README.md index de879886a9..8364c1159f 100644 --- a/api/oss/databases/postgres/migrations/tracing/README.md +++ b/api/oss/databases/postgres/migrations/tracing/README.md @@ -1,5 +1,12 @@ # Migrations with Alembic +> [!IMPORTANT] +> **This `tracing/` chain is PARKED (frozen legacy history).** Do **not** add new +> revisions here — it ends at `park00000000` and never advances. Author new tracing +> migrations in `tracing_oss/` (shared, runs in both editions) or `tracing_ee/` (EE-only). +> See the parked `core/README.md` banner and +> `docs/designs/oss-ee-convergence/migration-chains-and-edition-switch.md`. + Generic single-database configuration with an async dbapi. ## Autogenerate Migrations