fix(skills): correct PostgreSQL ADD COLUMN migration guidance

This commit is contained in:
yuhoyuho committed 2026-11-12 00:37:44 +09:00
1 parent d2ef268059
commit 3d99184af7
2 files changed
+77 -7

No files matched your search

+27 -7
View File
@@ -30,8 +30,8 @@ Safe, reversible database schema changes for production systems.
Before applying any migration:
- [ ] Migration has both UP and DOWN (or is explicitly marked irreversible)
- [ ] No full table locks on large tables (use concurrent operations)
- [ ] New columns have defaults or are nullable (never add NOT NULL without default)
- [ ] Lock modes and expected hold times reviewed; use concurrent operations where supported
- [ ] On populated tables, new columns are nullable or have defaults compatible with their constraints
- [ ] Indexes created concurrently (not inline with CREATE TABLE for existing tables)
- [ ] Data backfill is a separate migration from schema change
- [ ] Tested against a copy of production data
@@ -42,17 +42,37 @@ Before applying any migration:
### Adding a Column Safely
```sql
-- GOOD: Nullable column, no lock
-- Nullable column: no table rewrite, but takes ACCESS EXCLUSIVE lock
ALTER TABLE users ADD COLUMN avatar_url TEXT;
-- GOOD: Column with default (Postgres 11+ is instant, no rewrite)
-- PostgreSQL 11+: a non-volatile default avoids a table rewrite
-- Still takes ACCESS EXCLUSIVE lock and may wait for other transactions
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;
-- BAD: NOT NULL without default on existing table (requires full rewrite)
-- BAD on a populated table: existing rows would have NULL in the new column
ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
-- This locks the table and rewrites every row
-- Fails with not_null_violation (SQLSTATE 23502); does not backfill existing rows
```
Avoiding a table rewrite does not mean avoiding locks. These `ADD COLUMN`
operations take an `ACCESS EXCLUSIVE` lock, held until the transaction ends.
Keep the transaction short and use an appropriate `lock_timeout` to bound lock
acquisition waits. A volatile default such as `clock_timestamp()` requires a
table rewrite; the PostgreSQL 11+ fast path applies to non-volatile defaults.
Adding a `NOT NULL` column without a default can succeed on an empty table.
Run the self-checking [reproduction SQL](examples/postgres-add-column.sql) on
PostgreSQL 11+:
```bash
psql -X -v ON_ERROR_STOP=1 -f skills/database-migrations/examples/postgres-add-column.sql
```
It uses a temporary table, rolls back the ALTERs, and drops the fixture, checking
lock acquisition, rewrites, and the expected constraint violation.
Reference: [PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html).
### Adding an Index Without Downtime
```sql
@@ -424,7 +444,7 @@ Day 7: Migration drops old status column
|-------------|-------------|-----------------|
| Manual SQL in production | No audit trail, unrepeatable | Always use migration files |
| Editing deployed migrations | Causes drift between environments | Create new migration instead |
| NOT NULL without default | Locks table, rewrites all rows | Add nullable, backfill, then add constraint |
| Adding NOT NULL column without default to populated table | Fails because existing rows would contain NULL | Add nullable, backfill, then set NOT NULL |
| Inline index on large table | Blocks writes during build | CREATE INDEX CONCURRENTLY |
| Schema + data in one migration | Hard to rollback, long transactions | Separate migrations |
| Dropping column before removing code | Application errors on missing column | Remove code first, drop column next deploy |
@@ -0,0 +1,50 @@
-- PostgreSQL 11+; run with psql -X -v ON_ERROR_STOP=1 -f postgres-add-column.sql
-- Do not use --single-transaction: fixture creation must commit before the lock check.
-- Uses only a temporary table; rolls back ALTERs and drops the fixture.
\set ON_ERROR_STOP on
CREATE TEMP TABLE add_column_demo (id integer);
INSERT INTO add_column_demo VALUES (1), (2);
-- Commit fixture creation before checking the lock acquired by ALTER TABLE.
BEGIN;
DO $$
DECLARE
original_file oid := pg_relation_filenode('add_column_demo');
BEGIN
ALTER TABLE add_column_demo ADD COLUMN avatar_url text;
IF pg_relation_filenode('add_column_demo') <> original_file THEN
RAISE EXCEPTION 'Nullable ADD COLUMN unexpectedly rewrote the table';
END IF;
IF NOT EXISTS (
SELECT 1 FROM pg_locks
WHERE relation = 'add_column_demo'::regclass
AND pid = pg_backend_pid()
AND mode = 'AccessExclusiveLock' AND granted
) THEN
RAISE EXCEPTION 'Expected AccessExclusiveLock after ADD COLUMN';
END IF;
RAISE NOTICE 'PASS: nullable ADD COLUMN takes AccessExclusiveLock without a rewrite';
ALTER TABLE add_column_demo ADD COLUMN is_active boolean NOT NULL DEFAULT true;
IF pg_relation_filenode('add_column_demo') <> original_file
OR EXISTS (SELECT 1 FROM add_column_demo WHERE is_active IS DISTINCT FROM true) THEN
RAISE EXCEPTION 'Expected constant default without a table rewrite';
END IF;
RAISE NOTICE 'PASS: constant default supplies existing rows without a rewrite';
BEGIN
ALTER TABLE add_column_demo ADD COLUMN role text NOT NULL;
RAISE EXCEPTION 'Expected NOT NULL violation on populated table';
EXCEPTION WHEN not_null_violation THEN
RAISE NOTICE 'PASS: NOT NULL without default fails with SQLSTATE 23502';
END;
ALTER TABLE add_column_demo ADD COLUMN sampled_at timestamptz DEFAULT clock_timestamp();
IF pg_relation_filenode('add_column_demo') = original_file THEN
RAISE EXCEPTION 'Expected volatile default to rewrite the table';
END IF;
RAISE NOTICE 'PASS: volatile default rewrites the table';
END $$;
ROLLBACK;
DROP TABLE add_column_demo;