Przejdź do treści
Biblioteka skilli
Dane i analityka · Przegląd i audyt

postgres-safe-migrations

/postgres-safe-migrations

Sprawdza migracje schematu dla żywej aplikacji: dodawanie kolumn i indeksów, zmiany ograniczeń bez blokowania tabel i zerwania działającego kodu.

Repozytorium
free-sample ↗
Licencja
MIT
Ostatnia zmiana repozytorium
31.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 31.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

Sprawdza migracje schematu dla żywej aplikacji: dodawanie kolumn i indeksów, zmiany ograniczeń bez blokowania tabel i zerwania działającego kodu.

Wyzwalacze z opisu

add a column/index
Oryginalny opis (EN)

Use when writing or reviewing a Postgres schema migration for a live app — adding columns, indexes, constraints, renames or drops without locking tables or breaking running code. Triggers on any new migration file, schema change, or "add a column/index" request.

Jak działa

  1. Step 1: Classify every statement
  2. Step 2: Always set a lock timeout
  3. Step 3: Renames use expand and contract
  4. Step 4: Backfill in batches
  5. Step 5: Index example
  6. Review checklist
  7. Done when
Sekcje z nagłówków SKILL.md, w oryginale · 79 linii, 578 słów
Podgląd SKILL.md
---
name: postgres-safe-migrations
description: Use when writing or reviewing a Postgres schema migration for a live app — adding columns, indexes, constraints, renames or drops without locking tables or breaking running code. Triggers on any new migration file, schema change, or "add a column/index" request.
---

# Safe Postgres migrations for a live app

A migration is safe when it never holds a lock that blocks normal reads and writes for more than a moment, and when the old and new versions of the app can both run against the schema while a deploy rolls out.

## Step 1: Classify every statement

Before writing the migration, sort each change into one row below and follow its recipe.

| Change | Risk | Safe recipe |
| --- | --- | --- |
| Add nullable column | Low | Plain `ADD COLUMN` |
| Add column with a constant default | Low on Postgres 11+ | Plain `ADD COLUMN ... DEFAULT x` |
| Add NOT NULL column | High | Add nullable → backfill in batches → add `CHECK ... NOT VALID` → `VALIDATE` → `SET NOT NULL` |
| Add index | High (blocks writes) | `CREATE INDEX CONCURRENTLY`, in its own migration with no transaction |
| Add foreign key | High | `ADD CONSTRAINT ... NOT VALID`, then `VALIDATE CONSTRAINT` in a later step |
| Rename column or table | Breaks running code | Expand and contract (Step 3) |
| Drop column | Breaks running code | Remove from code first, deploy, then drop |
| Change column type | High (rewrites table) | New column + backfill + switch reads, never `ALTER TYPE` on a big table |

## Step 2: Always set a lock timeout

Every migration starts with a short lock timeout, so it fails fast instead of queueing behind a long query and blocking every request behind it.

```sql
SET lock_timeout = '3s';
SET statement_timeout = '60s';
```

If it fails on the timeout, retry later. Never raise the timeout to "make it work".

## Step 3: Renames use expand and contract

Never rename in one step. Running app instances still use the old name during deploy.

1. **Expand:** add the new column; write to both columns in code.
2. **Backfill:** copy old to new in batches (Step 4).
3. **Switch reads** to the new column; deploy.
4. **Contract:** stop writing the old column; deploy; then drop it in a later migration.

## Step 4: Backfill in batches

One giant `UPDATE` locks rows for its whole run and bloats the table. Batch by primary key:

```sql
UPDATE projects
SET status_v2 = status
WHERE id IN (
  SELECT id FROM projects
  WHERE status_v2 IS NULL
  ORDER BY id
  LIMIT 5000
);
-- repeat until 0 rows updated; run from a script, not inside the migration
```

## Step 5: Index example

```sql
-- migration file must disable its transaction (most tools: a flag or comment)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_issues_project_created
  ON issues (project_id, created_at DESC);
```

If a concurrent build fails, it leaves an `INVALID` index. Drop it with `DROP INDEX CONCURRENTLY` and retry.

## Review checklist

- [ ] `lock_timeout` set at the top
- [ ] No `CREATE INDEX` without `CONCURRENTLY` on an existing table
- [ ] No new `NOT NULL` or foreign key validated in the same step it's added
- [ ] No rename, drop or type change that running code still depends on
- [ ] Backfills are batched and run outside the migration
- [ ] A down migration exists, or the PR says why it can't

## Done when

Every statement maps to a row in Step 1, follows its recipe, and the checklist passes.

Wersje

W bazie nie ma innych skilli o nazwie postgres-safe-migrations.

Migawka bazy z 13.11.2026 · wersja paczki 7208171224f1 (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

  • 96postgres-safe-migration
    Pisze bezpieczne migracje PostgreSQL dla tabel z danymi, zmian kolumn, indeksów i ograniczeń.
  • 100safe-migration
    Pisze lub przegląda migrację bazy danych, która wdraża się bez blokowania tabel, bez psucia działającego kodu i bez utraty danych.
  • 87postgres-database-migration
    Planuje i testuje migracje schematu PostgreSQL na produkcyjnych danych: dodawanie kolumn, zmianę typów, indeksy i ograniczenia bez przestojów.
  • 100postgres-schema
    Projektuje lub sprawdza tabele PostgreSQL: typy kolumn, ograniczenia chroniące dane i indeksy, których potrzebują zapytania.
  • 90checking-schema-drops
    Wyszukuje kolumny i tabele usuwane lub zmieniane przez migracje, gdy kod nadal używa starej nazwy, czytając tylko pliki, bez bazy.
  • 100generate-migration
    Generuje lub przegląda migracje bazy Django dla Sentry, w tym migracje danych, dodawanie i usuwanie kolumn i tabel, indeksy oraz rozwiązywanie konfliktów migracji.

Uwagi i zgłoszenia

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