@tamsensedev/runner 0.13.0 → 0.18.0

package/library/skills/safe-database-changes/references/postgres-ddl.md

@@ -1,199 +1,199 @@
-# PostgreSQL: lock-aware schema changes
-
-Read this when a migration targets PostgreSQL and touches a table that may be large or busy in production. Everything here is for writing the migration; run it only against a throwaway database (see the hard rules in SKILL.md).
-
-## Why a "fast" change can still cause an outage
-
-Every DDL statement takes a lock. `ACCESS EXCLUSIVE` blocks reads and writes. Even a change that takes milliseconds must first wait for every running transaction on the table to finish, and while it waits, every new query on that table queues behind it:
-
-```
-Session 1: SELECT count(*) FROM orders;         -- long query, holds a read lock
-Session 2: ALTER TABLE orders ADD COLUMN ...;    -- waits for session 1
-Session 3: SELECT * FROM orders WHERE id = 1;    -- now blocked behind session 2
-```
-
-So: set a short `lock_timeout` on DDL, and prefer the non-blocking forms below.
-
-## Lock reference
-
-Fast (catalog-only, brief lock):
-
-| Operation | Lock | Notes |
-|---|---|---|
-| `ADD COLUMN` nullable, no default | ACCESS EXCLUSIVE, brief | No rewrite |
-| `ADD COLUMN ... DEFAULT <constant>` (PG 11+) | ACCESS EXCLUSIVE, brief | Constant default stored in the catalog |
-| `DROP COLUMN` | ACCESS EXCLUSIVE, brief | Data stays on disk until rewritten; code must stop using it first |
-| `SET DEFAULT` / `DROP DEFAULT` | ACCESS EXCLUSIVE, brief | Existing rows untouched |
-| `RENAME COLUMN` / `RENAME TO` | ACCESS EXCLUSIVE, brief | Fast, but breaks running code: use expand and contract |
-| `CREATE INDEX CONCURRENTLY` | SHARE UPDATE EXCLUSIVE | Reads and writes continue; slower; cannot run in a transaction |
-| `DROP INDEX CONCURRENTLY` | SHARE UPDATE EXCLUSIVE | Cannot run in a transaction |
-| `ADD CONSTRAINT ... NOT VALID` | brief | Checks new rows only (FK, CHECK) |
-| `VALIDATE CONSTRAINT` | SHARE UPDATE EXCLUSIVE | Scans rows but allows reads and writes |
-
-Slow or blocking:
-
-| Operation | Lock | Why |
-|---|---|---|
-| `ADD COLUMN ... DEFAULT <volatile>` (`now()`, `gen_random_uuid()`) | ACCESS EXCLUSIVE | Rewrites every row |
-| `ALTER COLUMN TYPE` (most changes) | ACCESS EXCLUSIVE | Rewrites the table and its indexes |
-| `SET NOT NULL` without a validated CHECK | ACCESS EXCLUSIVE | Full scan under the lock |
-| `ADD CONSTRAINT` FK / CHECK, validated immediately | SHARE ROW EXCLUSIVE or stronger | Scans all rows, blocks writes |
-| `ADD CONSTRAINT UNIQUE` / `PRIMARY KEY` directly | ACCESS EXCLUSIVE | Builds the index under the lock |
-| `CREATE INDEX` without CONCURRENTLY | SHARE | Blocks writes for the whole build |
-| `VACUUM FULL`, `CLUSTER` | ACCESS EXCLUSIVE | Rewrite the table |
-
-Type changes that do not rewrite: `varchar(n)` to a larger `varchar(m)` or to `text`, and `numeric(p,s)` to a larger precision with the same scale. `int` to `bigint` rewrites. If you rely on a change being catalog-only, say so in the report.
-
-## Safe patterns
-
-Add a column with a computed default: add it nullable, backfill in batches, then set the default and the constraint.
-
-```sql
-ALTER TABLE orders ADD COLUMN placed_at timestamptz;          -- instant
--- backfill in batches (references/backfills.md)
-ALTER TABLE orders ALTER COLUMN placed_at SET DEFAULT now();  -- new rows only
-```
-
-Add NOT NULL to an existing column (PG 12+): a validated CHECK lets `SET NOT NULL` skip the scan.
-
-```sql
-ALTER TABLE orders ADD CONSTRAINT orders_status_not_null
-  CHECK (status IS NOT NULL) NOT VALID;                       -- brief
-ALTER TABLE orders VALIDATE CONSTRAINT orders_status_not_null; -- scans, no write block
-ALTER TABLE orders ALTER COLUMN status SET NOT NULL;          -- uses the CHECK, no scan
-ALTER TABLE orders DROP CONSTRAINT orders_status_not_null;
-```
-
-Add a foreign key:
-
-```sql
-ALTER TABLE orders ADD CONSTRAINT orders_user_fk
-  FOREIGN KEY (user_id) REFERENCES users (id) NOT VALID;
-ALTER TABLE orders VALIDATE CONSTRAINT orders_user_fk;
-CREATE INDEX CONCURRENTLY orders_user_id_idx ON orders (user_id);  -- separate migration
-```
-
-Add an index, and check it afterwards: a failed concurrent build leaves an INVALID index behind that slows writes.
-
-```sql
-CREATE INDEX CONCURRENTLY IF NOT EXISTS orders_created_at_idx ON orders (created_at);
-
-SELECT indexrelid::regclass AS index, indisvalid
-FROM pg_index WHERE indrelid = 'orders'::regclass AND NOT indisvalid;
--- if listed: DROP INDEX CONCURRENTLY orders_created_at_idx; then build again
-```
-
-Add a unique constraint without holding a long lock:
-
-```sql
-CREATE UNIQUE INDEX CONCURRENTLY orders_tracking_uniq_idx ON orders (tracking_number);
-ALTER TABLE orders ADD CONSTRAINT orders_tracking_uniq
-  UNIQUE USING INDEX orders_tracking_uniq_idx;                -- instant
-```
-
-Change a column type on a big table: new column, dual writes in code, batched backfill, switch reads, drop the old column later (expand and contract). Do not `ALTER COLUMN TYPE` in place on a large table.
-
-Rename a column with no downtime: same pattern. A plain `RENAME COLUMN` is fast but breaks every running instance that still uses the old name.
-
-Drop a column: first ship code that no longer reads or writes it (for ORMs, remove it from the model; some ORMs select every mapped column), then drop it in a later migration. `DROP COLUMN` does not erase the data from disk; if the column held sensitive data, mention that a table rewrite is needed to really remove it.
-
-Replace a primary key: build a CHECK NOT NULL (NOT VALID, then VALIDATE) and a unique index concurrently on the new key column first, then swap with `ADD CONSTRAINT ... PRIMARY KEY USING INDEX` in a short transaction. Treat this as a high-risk change and spell out the plan in the report.
-
-## Timeouts and retries
-
-Set a lock timeout on every DDL statement so a blocked migration fails fast instead of freezing the table:
-
-```sql
-SET lock_timeout = '5s';
-SET statement_timeout = '30s';   -- not for CONCURRENTLY builds or VALIDATE on big tables
-ALTER TABLE orders ADD COLUMN tracking_number text;
-RESET lock_timeout;
-RESET statement_timeout;
-```
-
-High-traffic systems use a shorter lock timeout (50 to 500 ms) with many retries; most apps are fine with a few seconds and a few retries. Many migration tools let you put `SET lock_timeout` at the top of the migration file. If the project's runner retries failed migrations, say so; otherwise describe in the report that the deploy may need a retry when the lock is not acquired.
-
-A retry loop inside the database, for runners that cannot retry themselves:
-
-```sql
-DO $$
-DECLARE attempt int := 1;
-BEGIN
-  LOOP
-    BEGIN
-      SET LOCAL lock_timeout = '3s';
-      ALTER TABLE orders ADD COLUMN tracking_number text;
-      EXIT;
-    EXCEPTION WHEN lock_not_available THEN
-      IF attempt >= 5 THEN RAISE; END IF;
-      attempt := attempt + 1;
-      PERFORM pg_sleep(2 * attempt);
-    END;
-  END LOOP;
-END $$;
-```
-
-Under heavy write load, retries done by the application (one transaction per attempt) are kinder to replicas than this in-database loop.
-
-## Transactions
-
-- One transaction around several fast statements gives all-or-nothing, but every lock is held until COMMIT. Do not put a slow statement in the same transaction as an ACCESS EXCLUSIVE one.
-- `CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY` and `REINDEX CONCURRENTLY` cannot run inside a transaction block. Many migration tools wrap each file in a transaction; see [migration-tools.md](migration-tools.md) for how to opt out, and give such statements their own migration.
-- Keep data backfills out of schema transactions.
-
-## Checks before and after
-
-Run these on the throwaway database, seeded with realistic rows, to see whether the migration would fail on real data. In the report, suggest the "before" checks for the production deploy if the data could break the migration.
-
-```sql
--- NULLs before SET NOT NULL
-SELECT count(*) FROM orders WHERE status IS NULL;
-
--- duplicates before UNIQUE
-SELECT tracking_number, count(*) FROM orders
-WHERE tracking_number IS NOT NULL
-GROUP BY tracking_number HAVING count(*) > 1 LIMIT 20;
-
--- orphans before a foreign key
-SELECT o.id, o.user_id FROM orders o
-LEFT JOIN users u ON u.id = o.user_id
-WHERE o.user_id IS NOT NULL AND u.id IS NULL LIMIT 20;
-
--- size, to judge lock and rewrite risk
-SELECT pg_size_pretty(pg_total_relation_size('orders')) AS total_size,
-       reltuples::bigint AS estimated_rows
-FROM pg_class WHERE relname = 'orders';
-
--- after: columns, constraints, indexes as intended
-SELECT column_name, data_type, is_nullable, column_default
-FROM information_schema.columns WHERE table_name = 'orders';
-SELECT conname, pg_get_constraintdef(oid) FROM pg_constraint
-WHERE conrelid = 'orders'::regclass;
-SELECT indexrelid::regclass, indisvalid, pg_get_indexdef(indexrelid)
-FROM pg_index WHERE indrelid = 'orders'::regclass;
-```
-
-`EXPLAIN ANALYZE` executes the statement, including UPDATE and DELETE. Use it only on the throwaway database, or inside `BEGIN; ... ROLLBACK;` there.
-
-## Rollback
-
-| Change | Rollback |
-|---|---|
-| ADD COLUMN, ADD CONSTRAINT, CREATE INDEX | DROP it |
-| RENAME | Rename back |
-| SET DEFAULT | Restore the old default or DROP DEFAULT |
-| DROP COLUMN or TABLE, lossy type change, DELETE, TRUNCATE | Not reversible without a backup: say so in the report |
-
-Prefer forward fixes in production: a new migration that undoes the change.
-
-## Pitfalls
-
-- Testing only on an empty table: a migration that takes 1 ms there can lock a 10M-row table for minutes.
-- Forgetting CONCURRENTLY, or using it inside a transaction.
-- No lock timeout, so one long query freezes the table behind the DDL.
-- One huge UPDATE for a backfill: long locks, table bloat, replica lag.
-- Leaving an INVALID index after a failed concurrent build.
-- Dropping a column before the code that uses it is gone.
-- Assuming a type change is catalog-only without checking.
-
-Adapted from timescale/pg-aiguide `skills/postgres-database-migration` (Apache-2.0, commit 187be00d317a51210c132010d947f4546ffb5eef, Copyright 2025 Timescale, Inc., d/b/a Tiger Data) and affaan-m/ECC `skills/database-migrations` (MIT, commit 30b68924ae9729159f44326aa3134b1d9d67c0e2, Copyright (c) 2026 Affaan Mustafa). Changed: condensed and reworded; fork-based testing replaced by throwaway-database checks; vendor links removed; PG 18 NOT NULL syntax and timestamp type-change claims dropped as unverified; examples rewritten.
+# PostgreSQL: lock-aware schema changes
+
+Read this when a migration targets PostgreSQL and touches a table that may be large or busy in production. Everything here is for writing the migration; run it only against a throwaway database (see the hard rules in SKILL.md).
+
+## Why a "fast" change can still cause an outage
+
+Every DDL statement takes a lock. `ACCESS EXCLUSIVE` blocks reads and writes. Even a change that takes milliseconds must first wait for every running transaction on the table to finish, and while it waits, every new query on that table queues behind it:
+
+```
+Session 1: SELECT count(*) FROM orders;         -- long query, holds a read lock
+Session 2: ALTER TABLE orders ADD COLUMN ...;    -- waits for session 1
+Session 3: SELECT * FROM orders WHERE id = 1;    -- now blocked behind session 2
+```
+
+So: set a short `lock_timeout` on DDL, and prefer the non-blocking forms below.
+
+## Lock reference
+
+Fast (catalog-only, brief lock):
+
+| Operation | Lock | Notes |
+|---|---|---|
+| `ADD COLUMN` nullable, no default | ACCESS EXCLUSIVE, brief | No rewrite |
+| `ADD COLUMN ... DEFAULT <constant>` (PG 11+) | ACCESS EXCLUSIVE, brief | Constant default stored in the catalog |
+| `DROP COLUMN` | ACCESS EXCLUSIVE, brief | Data stays on disk until rewritten; code must stop using it first |
+| `SET DEFAULT` / `DROP DEFAULT` | ACCESS EXCLUSIVE, brief | Existing rows untouched |
+| `RENAME COLUMN` / `RENAME TO` | ACCESS EXCLUSIVE, brief | Fast, but breaks running code: use expand and contract |
+| `CREATE INDEX CONCURRENTLY` | SHARE UPDATE EXCLUSIVE | Reads and writes continue; slower; cannot run in a transaction |
+| `DROP INDEX CONCURRENTLY` | SHARE UPDATE EXCLUSIVE | Cannot run in a transaction |
+| `ADD CONSTRAINT ... NOT VALID` | brief | Checks new rows only (FK, CHECK) |
+| `VALIDATE CONSTRAINT` | SHARE UPDATE EXCLUSIVE | Scans rows but allows reads and writes |
+
+Slow or blocking:
+
+| Operation | Lock | Why |
+|---|---|---|
+| `ADD COLUMN ... DEFAULT <volatile>` (`now()`, `gen_random_uuid()`) | ACCESS EXCLUSIVE | Rewrites every row |
+| `ALTER COLUMN TYPE` (most changes) | ACCESS EXCLUSIVE | Rewrites the table and its indexes |
+| `SET NOT NULL` without a validated CHECK | ACCESS EXCLUSIVE | Full scan under the lock |
+| `ADD CONSTRAINT` FK / CHECK, validated immediately | SHARE ROW EXCLUSIVE or stronger | Scans all rows, blocks writes |
+| `ADD CONSTRAINT UNIQUE` / `PRIMARY KEY` directly | ACCESS EXCLUSIVE | Builds the index under the lock |
+| `CREATE INDEX` without CONCURRENTLY | SHARE | Blocks writes for the whole build |
+| `VACUUM FULL`, `CLUSTER` | ACCESS EXCLUSIVE | Rewrite the table |
+
+Type changes that do not rewrite: `varchar(n)` to a larger `varchar(m)` or to `text`, and `numeric(p,s)` to a larger precision with the same scale. `int` to `bigint` rewrites. If you rely on a change being catalog-only, say so in the report.
+
+## Safe patterns
+
+Add a column with a computed default: add it nullable, backfill in batches, then set the default and the constraint.
+
+```sql
+ALTER TABLE orders ADD COLUMN placed_at timestamptz;          -- instant
+-- backfill in batches (references/backfills.md)
+ALTER TABLE orders ALTER COLUMN placed_at SET DEFAULT now();  -- new rows only
+```
+
+Add NOT NULL to an existing column (PG 12+): a validated CHECK lets `SET NOT NULL` skip the scan.
+
+```sql
+ALTER TABLE orders ADD CONSTRAINT orders_status_not_null
+  CHECK (status IS NOT NULL) NOT VALID;                       -- brief
+ALTER TABLE orders VALIDATE CONSTRAINT orders_status_not_null; -- scans, no write block
+ALTER TABLE orders ALTER COLUMN status SET NOT NULL;          -- uses the CHECK, no scan
+ALTER TABLE orders DROP CONSTRAINT orders_status_not_null;
+```
+
+Add a foreign key:
+
+```sql
+ALTER TABLE orders ADD CONSTRAINT orders_user_fk
+  FOREIGN KEY (user_id) REFERENCES users (id) NOT VALID;
+ALTER TABLE orders VALIDATE CONSTRAINT orders_user_fk;
+CREATE INDEX CONCURRENTLY orders_user_id_idx ON orders (user_id);  -- separate migration
+```
+
+Add an index, and check it afterwards: a failed concurrent build leaves an INVALID index behind that slows writes.
+
+```sql
+CREATE INDEX CONCURRENTLY IF NOT EXISTS orders_created_at_idx ON orders (created_at);
+
+SELECT indexrelid::regclass AS index, indisvalid
+FROM pg_index WHERE indrelid = 'orders'::regclass AND NOT indisvalid;
+-- if listed: DROP INDEX CONCURRENTLY orders_created_at_idx; then build again
+```
+
+Add a unique constraint without holding a long lock:
+
+```sql
+CREATE UNIQUE INDEX CONCURRENTLY orders_tracking_uniq_idx ON orders (tracking_number);
+ALTER TABLE orders ADD CONSTRAINT orders_tracking_uniq
+  UNIQUE USING INDEX orders_tracking_uniq_idx;                -- instant
+```
+
+Change a column type on a big table: new column, dual writes in code, batched backfill, switch reads, drop the old column later (expand and contract). Do not `ALTER COLUMN TYPE` in place on a large table.
+
+Rename a column with no downtime: same pattern. A plain `RENAME COLUMN` is fast but breaks every running instance that still uses the old name.
+
+Drop a column: first ship code that no longer reads or writes it (for ORMs, remove it from the model; some ORMs select every mapped column), then drop it in a later migration. `DROP COLUMN` does not erase the data from disk; if the column held sensitive data, mention that a table rewrite is needed to really remove it.
+
+Replace a primary key: build a CHECK NOT NULL (NOT VALID, then VALIDATE) and a unique index concurrently on the new key column first, then swap with `ADD CONSTRAINT ... PRIMARY KEY USING INDEX` in a short transaction. Treat this as a high-risk change and spell out the plan in the report.
+
+## Timeouts and retries
+
+Set a lock timeout on every DDL statement so a blocked migration fails fast instead of freezing the table:
+
+```sql
+SET lock_timeout = '5s';
+SET statement_timeout = '30s';   -- not for CONCURRENTLY builds or VALIDATE on big tables
+ALTER TABLE orders ADD COLUMN tracking_number text;
+RESET lock_timeout;
+RESET statement_timeout;
+```
+
+High-traffic systems use a shorter lock timeout (50 to 500 ms) with many retries; most apps are fine with a few seconds and a few retries. Many migration tools let you put `SET lock_timeout` at the top of the migration file. If the project's runner retries failed migrations, say so; otherwise describe in the report that the deploy may need a retry when the lock is not acquired.
+
+A retry loop inside the database, for runners that cannot retry themselves:
+
+```sql
+DO $$
+DECLARE attempt int := 1;
+BEGIN
+  LOOP
+    BEGIN
+      SET LOCAL lock_timeout = '3s';
+      ALTER TABLE orders ADD COLUMN tracking_number text;
+      EXIT;
+    EXCEPTION WHEN lock_not_available THEN
+      IF attempt >= 5 THEN RAISE; END IF;
+      attempt := attempt + 1;
+      PERFORM pg_sleep(2 * attempt);
+    END;
+  END LOOP;
+END $$;
+```
+
+Under heavy write load, retries done by the application (one transaction per attempt) are kinder to replicas than this in-database loop.
+
+## Transactions
+
+- One transaction around several fast statements gives all-or-nothing, but every lock is held until COMMIT. Do not put a slow statement in the same transaction as an ACCESS EXCLUSIVE one.
+- `CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY` and `REINDEX CONCURRENTLY` cannot run inside a transaction block. Many migration tools wrap each file in a transaction; see [migration-tools.md](migration-tools.md) for how to opt out, and give such statements their own migration.
+- Keep data backfills out of schema transactions.
+
+## Checks before and after
+
+Run these on the throwaway database, seeded with realistic rows, to see whether the migration would fail on real data. In the report, suggest the "before" checks for the production deploy if the data could break the migration.
+
+```sql
+-- NULLs before SET NOT NULL
+SELECT count(*) FROM orders WHERE status IS NULL;
+
+-- duplicates before UNIQUE
+SELECT tracking_number, count(*) FROM orders
+WHERE tracking_number IS NOT NULL
+GROUP BY tracking_number HAVING count(*) > 1 LIMIT 20;
+
+-- orphans before a foreign key
+SELECT o.id, o.user_id FROM orders o
+LEFT JOIN users u ON u.id = o.user_id
+WHERE o.user_id IS NOT NULL AND u.id IS NULL LIMIT 20;
+
+-- size, to judge lock and rewrite risk
+SELECT pg_size_pretty(pg_total_relation_size('orders')) AS total_size,
+       reltuples::bigint AS estimated_rows
+FROM pg_class WHERE relname = 'orders';
+
+-- after: columns, constraints, indexes as intended
+SELECT column_name, data_type, is_nullable, column_default
+FROM information_schema.columns WHERE table_name = 'orders';
+SELECT conname, pg_get_constraintdef(oid) FROM pg_constraint
+WHERE conrelid = 'orders'::regclass;
+SELECT indexrelid::regclass, indisvalid, pg_get_indexdef(indexrelid)
+FROM pg_index WHERE indrelid = 'orders'::regclass;
+```
+
+`EXPLAIN ANALYZE` executes the statement, including UPDATE and DELETE. Use it only on the throwaway database, or inside `BEGIN; ... ROLLBACK;` there.
+
+## Rollback
+
+| Change | Rollback |
+|---|---|
+| ADD COLUMN, ADD CONSTRAINT, CREATE INDEX | DROP it |
+| RENAME | Rename back |
+| SET DEFAULT | Restore the old default or DROP DEFAULT |
+| DROP COLUMN or TABLE, lossy type change, DELETE, TRUNCATE | Not reversible without a backup: say so in the report |
+
+Prefer forward fixes in production: a new migration that undoes the change.
+
+## Pitfalls
+
+- Testing only on an empty table: a migration that takes 1 ms there can lock a 10M-row table for minutes.
+- Forgetting CONCURRENTLY, or using it inside a transaction.
+- No lock timeout, so one long query freezes the table behind the DDL.
+- One huge UPDATE for a backfill: long locks, table bloat, replica lag.
+- Leaving an INVALID index after a failed concurrent build.
+- Dropping a column before the code that uses it is gone.
+- Assuming a type change is catalog-only without checking.
+
+Adapted from timescale/pg-aiguide `skills/postgres-database-migration` (Apache-2.0, commit 187be00d317a51210c132010d947f4546ffb5eef, Copyright 2025 Timescale, Inc., d/b/a Tiger Data) and affaan-m/ECC `skills/database-migrations` (MIT, commit 30b68924ae9729159f44326aa3134b1d9d67c0e2, Copyright (c) 2026 Affaan Mustafa). Changed: condensed and reworded; fork-based testing replaced by throwaway-database checks; vendor links removed; PG 18 NOT NULL syntax and timestamp type-change claims dropped as unverified; examples rewritten.