diff --git a/migrations/1781000000001_reconcile-cards-columns.js b/migrations/1781000000001_reconcile-cards-columns.js new file mode 100644 index 0000000..30ebfb7 --- /dev/null +++ b/migrations/1781000000001_reconcile-cards-columns.js @@ -0,0 +1,82 @@ +/** + * Reconcile cards columns missed by initial-schema backfill (B1 of + * reconcile-historical-add-scripts convoy). + * + * Folds the effects of `scripts/add-card-columns.js` into the migration + * history. That historical script ran against every long-lived environment + * pre-migration-tool and added two columns to the `cards` table that the + * initial-schema backfill (`1779853647564_initial-schema.js`) did NOT + * capture in its bootstrap `CREATE TABLE cards`: + * + * - cards.quantity INTEGER DEFAULT 0 + * - cards.favorited BOOLEAN DEFAULT false + * + * Both columns are flagged as "Unused" in docs/SCHEMA_MAP.md § "Known + * schema smells" #3 (the live quantity/favorited semantics live on + * `user_cards` and `user_favorites`). They are reproduced here verbatim + * so a brand-new Neon branch onboarded by `npm run setup-db` ends up + * structurally equivalent to prod. The follow-up `drop-dead-cards-columns` + * convoy will retire these columns once a query-trace audit confirms zero + * readers — see .convoys/reconcile-historical-add-scripts.md § Follow-ups. + * + * Idempotency (D2): every statement uses `ADD COLUMN IF NOT EXISTS`, so + * this migration is safe to run against: + * + * (a) A fresh Neon branch where initial-schema just ran → columns do + * not exist → ALTER adds them. + * (b) A long-lived env where `scripts/add-card-columns.js` ran + * pre-migration-tool → columns already exist → ALTER is a no-op + * (only the `pgmigrations` row insert is recorded). + * (c) Re-application of this migration → ALTER is a no-op as in (b). + * + * Note on overlap with sibling migrations on the `cards` table: + * - `1781440700404_add-scryfall-bulk-columns.js` (PR #32, post-architect + * plan) adds 13 unrelated Scryfall bulk-data columns to `cards` + * (oracle_id, illustration_id, color_identity, keywords, legalities, + * flavor_text, artist, released_at, layout, edhrec_rank, reserved, + * reprint, finishes). Verified to not include quantity/favorited; + * no scope reduction required. + * - `add-updated-at-column.js` (script #7 in the convoy inventory) is + * already fully captured by initial-schema's `updated_at` column on + * `cards` (line 67), so it is intentionally NOT folded here. + * + * Down-migration is a hard stub. These are reconciliation migrations: the + * prod schema state is the source of truth, and rolling back would create + * fresh-vs-prod inconsistency. If the columns ever need to be dropped, the + * follow-up `drop-dead-cards-columns` convoy will write a new dated + * migration with its own real `down()` — do NOT remove this stub. + * + * @type {import('node-pg-migrate').ColumnDefinitions | undefined} + */ +export const shorthands = undefined; + +/** + * @param {import('node-pg-migrate').MigrationBuilder} pgm + * @returns {void} + */ +export const up = (pgm) => { + pgm.sql(` + ALTER TABLE cards + ADD COLUMN IF NOT EXISTS quantity INTEGER DEFAULT 0 + `); + + pgm.sql(` + ALTER TABLE cards + ADD COLUMN IF NOT EXISTS favorited BOOLEAN DEFAULT false + `); +}; + +/** + * Down-migration is a hard stub. See top-of-file docstring for rationale. + * + * @returns {void} + */ +export const down = () => { + throw new Error( + '[migration:1781000000001_reconcile-cards-columns] Refusing to drop reconciled cards columns. ' + + 'This migration folds historical scripts/add-card-columns.js into the migration history; ' + + 'rolling it back would create fresh-vs-prod schema inconsistency. If cards.quantity / ' + + 'cards.favorited need to be retired, ship a new dated migration via the queued ' + + '`drop-dead-cards-columns` convoy (see .convoys/reconcile-historical-add-scripts.md § Follow-ups).' + ); +};