Skip to content

[docs] Add comments / instructions about the new database migrations #4733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
junaway wants to merge 1 commit into
base: main
Choose a base branch
from
+58 −0
Draft

[docs] Add comments / instructions about the new database migrations #4733

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions api/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +91 to +93

### Layering and dependency direction

Required direction:
Expand Down
7 changes: 7 additions & 0 deletions api/ee/databases/postgres/migrations/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Comment on lines +4 to +8
Comment on lines +4 to +8

Generic single-database configuration with an async dbapi.

## Autogenerate Migrations
Expand Down
6 changes: 6 additions & 0 deletions ...ostgres/migrations/tracing/README copy.md → ...ses/postgres/migrations/tracing/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
22 changes: 22 additions & 0 deletions api/oss/databases/postgres/migrations/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +22 to +23
Comment on lines +22 to +23

Generic single-database configuration with an async dbapi.

## Autogenerate Migrations
Expand Down
7 changes: 7 additions & 0 deletions api/oss/databases/postgres/migrations/tracing/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Comment on lines +4 to +8
Comment on lines +4 to +8

Generic single-database configuration with an async dbapi.

## Autogenerate Migrations
Expand Down
Loading