From 3d99184af705987f16de8be408f69a4889f51fc0 Mon Sep 17 00:00:00 2001 From: yuhoyuho Date: Thu, 12 Nov 2026 00:37:44 +0900 Subject: [PATCH] fix(skills): correct PostgreSQL ADD COLUMN migration guidance --- skills/database-migrations/SKILL.md | 34 ++++++++++--- .../examples/postgres-add-column.sql | 50 +++++++++++++++++++ 2 files changed, 77 insertions(+), 7 deletions(-) create mode 100644 skills/database-migrations/examples/postgres-add-column.sql diff --git a/skills/database-migrations/SKILL.md b/skills/database-migrations/SKILL.md index 92d6d6930..c2d550390 100644 --- a/skills/database-migrations/SKILL.md +++ b/skills/database-migrations/SKILL.md @@ -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 | diff --git a/skills/database-migrations/examples/postgres-add-column.sql b/skills/database-migrations/examples/postgres-add-column.sql new file mode 100644 index 000000000..0904a07dd --- /dev/null +++ b/skills/database-migrations/examples/postgres-add-column.sql @@ -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;