mirror of
https://github.com/affaan-m/ECC.git
synced 2026-11-17 13:32:18 +00:00
fix(skills): correct PostgreSQL ADD COLUMN migration guidance
This commit is contained in:
1 parent
d2ef268059
commit
3d99184af7
2 files changed
+77
-7
No files matched your search
@@ -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;
|
||||
Reference in new issue
Block a user