Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

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.

Repozytorium
boxel ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. Which directory?
  2. Creating a migration
  3. Enforcement
  4. Applying migrations locally / in CI
  5. Gotchas
Sekcje z nagłówków SKILL.md, w oryginale · 87 linii, 623 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.