postgres-migrations
/postgres-migrations
Prowadzi pisanie migracji Postgresa w packages/postgres w systemie dwufazowym: zmiany addytywne w migrations/ przed wdrożeniem, destrukcyjne w migrations-removal/ po wdrożeniu.
- Autor
- cardstack ↗
- Repozytorium
- boxel ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Prowadzi pisanie migracji Postgresa w packages/postgres w systemie dwufazowym: zmiany addytywne w migrations/ przed wdrożeniem, destrukcyjne w migrations-removal/ po wdrożeniu.
Oryginalny opis (EN)
How to author Postgres migrations in packages/postgres under the two-phase (additive vs removal) system — additive changes go in migrations/ and run pre-deploy; destructive changes (DROP COLUMN/TABLE, RENAME) go in migrations-removal/ and run post-deploy so they never break the previous code revision mid-rollout. Use whenever creating, editing, moving, or reviewing a migration in packages/postgres, deciding which directory a migration belongs in, or touching the boxel_index / boxel_index_pending index tables. Triggers on adding a DB migration, a DROP/RENAME in a migration, or a review of one.
Jak działa
- Which directory?
- Creating a migration
- Enforcement
- Applying migrations locally / in CI
- Gotchas
Podgląd SKILL.md
---
name: postgres-migrations
allowed-tools: Read, Grep, Bash
description: How to author Postgres migrations in packages/postgres under the two-phase (additive vs removal) system — additive changes go in migrations/ and run pre-deploy; destructive changes (DROP COLUMN/TABLE, RENAME) go in migrations-removal/ and run post-deploy so they never break the previous code revision mid-rollout. Use whenever creating, editing, moving, or reviewing a migration in packages/postgres, deciding which directory a migration belongs in, or touching the boxel_index / boxel_index_pending index tables. Triggers on adding a DB migration, a DROP/RENAME in a migration, or a review of one.
---
# Postgres migrations — the two-phase system
`packages/postgres/` migrations are split into two directories, each with its own
node-pg-migrate tracking table, because a destructive schema change applied
during a rolling deploy breaks the **previous** code revision while it is still
serving (old tasks query a column the migration just dropped).
| Directory | Tracking table | When it runs in a deploy | For |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `migrations/` | `migrations` | **pre**-deploy (`migrate-db` job) | additive, backward-compatible changes |
| `migrations-removal/` | `migrations_removal` | **post**-deploy (`migrate-db-remove` job), gated on the realm-server rollout reaching stability so old tasks have drained | destructive changes |
## Which directory?
Ask: **does the migration's `up()` remove or rename something the currently
deployed code still reads?** If yes → `migrations-removal/`.
- **Additive → `migrations/`**: `addColumn`, `createTable`, new index, backfill,
dual-write. Safe for old code to run against.
- **Destructive → `migrations-removal/`**: `dropColumn` / `dropColumns` /
`dropTable` / `renameColumn` / `renameTable`, and the raw-SQL equivalents
(`pgm.sql('ALTER TABLE ... DROP COLUMN ...')`, `RENAME`). Also anything that
tightens a contract the old code depends on (e.g. adding `NOT NULL` to a
column old code doesn't populate, narrowing a type).
The standard expand/contract pattern spans **two** releases: release N adds the
new shape and stops reading the old one (additive migration + code); release
N+1 drops the old shape (removal migration). Never ship the drop in the same
release that stops reading it unless you are certain no old task will run against
the new schema.
## Creating a migration
```sh
# additive (the common case) — writes to migrations/
pnpm --filter @cardstack/postgres migrate create <name>
# destructive — writes straight to migrations-removal/
pnpm --filter @cardstack/postgres migrate:create-removal <name>
```
Filenames need a real `Date.now()` millisecond timestamp; `pnpm lint:migrations`
rejects any prefix with 6+ consecutive zeros. `migrate create` stamps a valid
one. Never hand-pick a round number.
Migration files are CommonJS (`exports.up` / `exports.down`); both directories
carry a `package.json` pinning `{ "type": "commonjs" }`.
## Enforcement
`packages/postgres/scripts/check-removal-phase.cjs` (CI: "Guard removal-phase
migrations") AST-parses each **newly added** `migrations/` file and fails if its
`up()` drops or renames a column/table. It is scoped to changed files (so drops
already present in `migrations/` are grandfathered) and looks only at `up()` (an
additive migration's `down()` legitimately calls `dropColumn` to reverse
itself). It is heuristic — it will not catch `NOT NULL` tightening, type
narrowing, or destructive SQL built from non-literal strings — so the decision
rule above still applies.
## Applying migrations locally / in CI
`pnpm migrate up|down [count]|create` is transparent — the driver
(`scripts/migrate-local.sh`) runs both phases as one combined sequence
(additive first on `up`; `down [count]` reverts the N most-recent across both
phases, default 1). You do **not** think about the split when applying; only
when authoring a destructive change.
## Gotchas
- **Each production index table has a pending twin that must stay
column-compatible with it**: `boxel_index` ↔ `boxel_index_pending` and
`prerendered_html` ↔ `prerendered_html_pending`. A pass stages its rows in the
pending table and its commit copies every production column out of the
pending row, so a column added to a production table must be added to its
pending twin in the same migration. Changing only one breaks the commit
with `column "..." does not exist`. The pending tables carry two extra columns
(`job_id`, `staging_id`) that production does not.
- **Moving an already-applied migration between directories re-runs it** under
the new tracking table. Only safe if its `up()` is idempotent (`IF EXISTS` /
`ifNotExists`). Moving a not-yet-applied file is always clean.
- **Schema snapshot**: after any migration change run `pnpm make-schema`; the
host validates the committed `packages/host/config/schema/<latest>_schema.sql`
against the newest migration across **both** directories.
- `packages/realm-server/migrations/` is a **separate** migration system (not
this one); don't conflate them.
Wersje
W bazie nie ma innych skilli o nazwie postgres-migrations.
Migawka bazy z 13.11.2026 · wersja paczki 3534a4aa5bc4 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100django-migrations
Prowadzi migracje Django i Postgres w PostHog: indeksy i ograniczenia bez blokad, zmiany schematu w wielu fazach, backfille danych, konflikty migracji, usuwanie modeli i SeparateDatabaseAndState. - 100migration-safety-review
Sprawdza migrację bazy przed wdrożeniem pod kątem blokad tabel, przepisywania wierszy i błędów w działającej aplikacji. - 87postgres-migration
Zmienia schemat Postgresa bez psucia poprzedniego wydania: wzorzec expand i contract dla kolumn, tabel, typów i indeksów. - 100add-migration
Dodaje lub zmienia migrację schematu Postgres: nową tabelę, kolumnę albo indeks, i uruchamia polecenie migracji w projekcie. - 96postgres-safe-migration
Pisze bezpieczne migracje PostgreSQL dla tabel z danymi, zmian kolumn, indeksów i ograniczeń. - 100migration-helper
Pisze bezpieczne migracje schematu i danych z planem wycofania i sprawdzeniem blokad dla Postgres i MySQL.