migraguard 0.8.3 → 0.8.4

package/README.md

@@ -124,7 +124,8 @@ CREATE TABLE IF NOT EXISTS schema_migrations (
     checksum    VARCHAR(64)  NOT NULL,
     status      VARCHAR(16)  NOT NULL DEFAULT 'applied',  -- applied / failed / skipped
     applied_at  TIMESTAMPTZ  NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    resolved_at TIMESTAMPTZ                               -- resolution timestamp for skipped
+    resolved_at TIMESTAMPTZ,                              -- resolution timestamp for skipped
+    tag         VARCHAR(256)                              -- caller-supplied tag (e.g. commit hash, release tag)
 );
 ```
 

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: migraguard CLI
-  version: 0.8.3
+  version: 0.8.4
   description: >-
     PostgreSQL-first schema-aware deployment control — idempotent SQL migrations
     with CI-enforced integrity checks, expand/contract migration orchestration,
@@ -112,6 +112,11 @@ commandSets:
               type: boolean
               default: false
 
+          - name: tag
+            description: Tag to record with applied migrations (e.g. commit hash, release tag).
+            schema:
+              type: string
+
         exits:
           '0':
             description: All pending migrations applied successfully.
@@ -536,6 +541,12 @@ commandSets:
               type: string
               enum: [running, completed, failed]
 
+        options:
+          - name: tag
+            description: Tag to record (e.g. commit hash, release tag).
+            schema:
+              type: string
+
         exits:
           '0':
             description: Phase state transition recorded.
@@ -584,6 +595,12 @@ commandSets:
               type: string
               enum: [expand, backfill, switch, contract]
 
+        options:
+          - name: tag
+            description: Tag to record (e.g. commit hash, release tag).
+            schema:
+              type: string
+
         exits:
           '0':
             description: Phase applied successfully.

package/dist/cli.js

@@ -136,7 +136,8 @@ CREATE TABLE IF NOT EXISTS schema_migrations (
     resolved_at     TIMESTAMP(6) NULL,
     migration_class VARCHAR(16)  DEFAULT 'safe',
     phase           VARCHAR(16)  NULL,
-    group_name      VARCHAR(256) NULL
+    group_name      VARCHAR(256) NULL,
+    tag             VARCHAR(256) NULL
 ) ENGINE=InnoDB;
 `;
 var MigraguardDbMysql = class {
@@ -172,6 +173,13 @@ var MigraguardDbMysql = class {
   }
   async ensureTable() {
     await this.exec(CREATE_TABLE_SQL);
+    const rows = await this.queryRows(
+      `SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS
+       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'schema_migrations' AND COLUMN_NAME = 'tag'`
+    );
+    if (rows.length === 0) {
+      await this.exec(`ALTER TABLE schema_migrations ADD COLUMN tag VARCHAR(256) NULL`);
+    }
   }
   async acquireAdvisoryLock() {
     await this.exec(`SELECT GET_LOCK(?, -1)`, [ADVISORY_LOCK_KEY]);
@@ -182,7 +190,7 @@ var MigraguardDbMysql = class {
   async getAllRecords() {
     const rows = await this.queryRows(
       `SELECT file_name, checksum, status, applied_at, resolved_at,
-              migration_class, phase, group_name
+              migration_class, phase, group_name, tag
        FROM schema_migrations
        ORDER BY applied_at ASC`
     );
@@ -191,7 +199,7 @@ var MigraguardDbMysql = class {
   async getRecordsForFile(fileName) {
     const rows = await this.queryRows(
       `SELECT file_name, checksum, status, applied_at, resolved_at,
-              migration_class, phase, group_name
+              migration_class, phase, group_name, tag
        FROM schema_migrations
        WHERE file_name = ?
        ORDER BY applied_at ASC`,
@@ -203,17 +211,18 @@ var MigraguardDbMysql = class {
     const migrationClass = options?.migrationClass ?? "safe";
     const phase = options?.phase ?? null;
     const groupName = options?.groupName ?? null;
+    const tag = options?.tag ?? null;
     if (status === "skipped") {
       await this.exec(
-        `INSERT INTO schema_migrations (file_name, checksum, status, resolved_at, migration_class, phase, group_name)
-         VALUES (?, ?, ?, CURRENT_TIMESTAMP(6), ?, ?, ?)`,
-        [fileName, checksum, status, migrationClass, phase, groupName]
+        `INSERT INTO schema_migrations (file_name, checksum, status, resolved_at, migration_class, phase, group_name, tag)
+         VALUES (?, ?, ?, CURRENT_TIMESTAMP(6), ?, ?, ?, ?)`,
+        [fileName, checksum, status, migrationClass, phase, groupName, tag]
       );
     } else {
       await this.exec(
-        `INSERT INTO schema_migrations (file_name, checksum, status, migration_class, phase, group_name)
-         VALUES (?, ?, ?, ?, ?, ?)`,
-        [fileName, checksum, status, migrationClass, phase, groupName]
+        `INSERT INTO schema_migrations (file_name, checksum, status, migration_class, phase, group_name, tag)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        [fileName, checksum, status, migrationClass, phase, groupName, tag]
       );
     }
   }
@@ -238,7 +247,8 @@ function mapRow(row) {
     resolvedAt: row["resolved_at"] ? row["resolved_at"] instanceof Date ? row["resolved_at"] : new Date(row["resolved_at"]) : null,
     migrationClass: row["migration_class"] ?? "safe",
     phase: row["phase"] ?? null,
-    groupName: row["group_name"] ?? null
+    groupName: row["group_name"] ?? null,
+    tag: row["tag"] ?? null
   };
 }
 
@@ -253,7 +263,8 @@ CREATE TABLE IF NOT EXISTS schema_migrations (
     resolved_at     TEXT,
     migration_class TEXT    DEFAULT 'safe',
     phase           TEXT,
-    group_name      TEXT
+    group_name      TEXT,
+    tag             TEXT
 );
 `;
 var MigraguardDbSqlite = class {
@@ -284,6 +295,11 @@ var MigraguardDbSqlite = class {
   }
   async ensureTable() {
     this.db().exec(CREATE_TABLE_SQL2);
+    const cols = this.db().prepare(`PRAGMA table_info(schema_migrations)`).all();
+    const hasTag = cols.some((c) => c["name"] === "tag");
+    if (!hasTag) {
+      this.db().exec(`ALTER TABLE schema_migrations ADD COLUMN tag TEXT`);
+    }
   }
   async acquireAdvisoryLock() {
   }
@@ -292,7 +308,7 @@ var MigraguardDbSqlite = class {
   async getAllRecords() {
     const rows = this.db().prepare(
       `SELECT file_name, checksum, status, applied_at, resolved_at,
-              migration_class, phase, group_name
+              migration_class, phase, group_name, tag
        FROM schema_migrations
        ORDER BY applied_at ASC`
     ).all();
@@ -301,7 +317,7 @@ var MigraguardDbSqlite = class {
   async getRecordsForFile(fileName) {
     const rows = this.db().prepare(
       `SELECT file_name, checksum, status, applied_at, resolved_at,
-              migration_class, phase, group_name
+              migration_class, phase, group_name, tag
        FROM schema_migrations
        WHERE file_name = ?
        ORDER BY applied_at ASC`
@@ -312,16 +328,17 @@ var MigraguardDbSqlite = class {
     const migrationClass = options?.migrationClass ?? "safe";
     const phase = options?.phase ?? null;
     const groupName = options?.groupName ?? null;
+    const tag = options?.tag ?? null;
     if (status === "skipped") {
       this.db().prepare(
-        `INSERT INTO schema_migrations (file_name, checksum, status, resolved_at, migration_class, phase, group_name)
-         VALUES (?, ?, ?, datetime('now'), ?, ?, ?)`
-      ).run(fileName, checksum, status, migrationClass, phase, groupName);
+        `INSERT INTO schema_migrations (file_name, checksum, status, resolved_at, migration_class, phase, group_name, tag)
+         VALUES (?, ?, ?, datetime('now'), ?, ?, ?, ?)`
+      ).run(fileName, checksum, status, migrationClass, phase, groupName, tag);
     } else {
       this.db().prepare(
-        `INSERT INTO schema_migrations (file_name, checksum, status, migration_class, phase, group_name)
-         VALUES (?, ?, ?, ?, ?, ?)`
-      ).run(fileName, checksum, status, migrationClass, phase, groupName);
+        `INSERT INTO schema_migrations (file_name, checksum, status, migration_class, phase, group_name, tag)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      ).run(fileName, checksum, status, migrationClass, phase, groupName, tag);
     }
   }
   db() {
@@ -338,7 +355,8 @@ function mapRow2(row) {
     resolvedAt: row["resolved_at"] ? new Date(row["resolved_at"]) : null,
     migrationClass: row["migration_class"] ?? "safe",
     phase: row["phase"] ?? null,
-    groupName: row["group_name"] ?? null
+    groupName: row["group_name"] ?? null,
+    tag: row["tag"] ?? null
   };
 }
 
@@ -359,7 +377,8 @@ var ALTER_TABLE_SQL = `
 ALTER TABLE schema_migrations
   ADD COLUMN IF NOT EXISTS migration_class VARCHAR(16) DEFAULT 'safe',
   ADD COLUMN IF NOT EXISTS phase VARCHAR(16),
-  ADD COLUMN IF NOT EXISTS group_name VARCHAR(256);
+  ADD COLUMN IF NOT EXISTS group_name VARCHAR(256),
+  ADD COLUMN IF NOT EXISTS tag VARCHAR(256);
 `;
 function createDb(config) {
   switch (config.dialect) {
@@ -401,7 +420,7 @@ var MigraguardDb = class {
   async getAllRecords() {
     const result = await this.client.query(
       `SELECT file_name, checksum, status, applied_at, resolved_at,
-              migration_class, phase, group_name
+              migration_class, phase, group_name, tag
        FROM schema_migrations
        ORDER BY applied_at ASC`
     );
@@ -410,7 +429,7 @@ var MigraguardDb = class {
   async getRecordsForFile(fileName) {
     const result = await this.client.query(
       `SELECT file_name, checksum, status, applied_at, resolved_at,
-              migration_class, phase, group_name
+              migration_class, phase, group_name, tag
        FROM schema_migrations
        WHERE file_name = $1
        ORDER BY applied_at ASC`,
@@ -422,17 +441,18 @@ var MigraguardDb = class {
     const migrationClass = options?.migrationClass ?? "safe";
     const phase = options?.phase ?? null;
     const groupName = options?.groupName ?? null;
+    const tag = options?.tag ?? null;
     if (status === "skipped") {
       await this.client.query(
-        `INSERT INTO schema_migrations (file_name, checksum, status, resolved_at, migration_class, phase, group_name)
-         VALUES ($1, $2, $3, CURRENT_TIMESTAMP, $4, $5, $6)`,
-        [fileName, checksum, status, migrationClass, phase, groupName]
+        `INSERT INTO schema_migrations (file_name, checksum, status, resolved_at, migration_class, phase, group_name, tag)
+         VALUES ($1, $2, $3, CURRENT_TIMESTAMP, $4, $5, $6, $7)`,
+        [fileName, checksum, status, migrationClass, phase, groupName, tag]
       );
     } else {
       await this.client.query(
-        `INSERT INTO schema_migrations (file_name, checksum, status, migration_class, phase, group_name)
-         VALUES ($1, $2, $3, $4, $5, $6)`,
-        [fileName, checksum, status, migrationClass, phase, groupName]
+        `INSERT INTO schema_migrations (file_name, checksum, status, migration_class, phase, group_name, tag)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+        [fileName, checksum, status, migrationClass, phase, groupName, tag]
       );
     }
   }
@@ -449,7 +469,8 @@ function mapRow3(row) {
     resolvedAt: row["resolved_at"] ?? null,
     migrationClass: row["migration_class"] ?? "safe",
     phase: row["phase"] ?? null,
-    groupName: row["group_name"] ?? null
+    groupName: row["group_name"] ?? null,
+    tag: row["tag"] ?? null
   };
 }
 
@@ -1787,7 +1808,7 @@ async function commandApply(config, options) {
     await db.ensureTable();
     await db.acquireAdvisoryLock();
     if (options?.fromBaseline) {
-      await applyFromBaseline(config, db, metadata, result);
+      await applyFromBaseline(config, db, metadata, result, options?.tag);
     }
     const files = await scanMigrations(config);
     if (files.length === 0 && !options?.fromBaseline) {
@@ -1857,7 +1878,7 @@ async function commandApply(config, options) {
       const latestRecord = getLatestRecord(fileRecords);
       const currentChecksum = await checksumFile(file.filePath);
       const isEditable = dag && leafSet ? leafSet.has(file.fileName) : file.fileName === latestFileName;
-      const insertOpts = file.migrationClass === "expand_contract" ? { migrationClass: "expand_contract", phase: file.phase, groupName: file.groupName } : void 0;
+      const insertOpts = file.migrationClass === "expand_contract" ? { migrationClass: "expand_contract", phase: file.phase, groupName: file.groupName, tag: options?.tag } : options?.tag ? { tag: options.tag } : void 0;
       const applyResult = await processFile(
         config,
         db,
@@ -1986,7 +2007,7 @@ async function processFile(config, db, filePath, fileName, fileRecords, latestRe
     return "error";
   }
 }
-async function applyFromBaseline(config, db, metadata, result) {
+async function applyFromBaseline(config, db, metadata, result, tag) {
   const schemaPath = resolveFromConfig(config, config.schemaFile);
   if (!existsSync(schemaPath)) {
     result.errors.push("No schema.sql found. Cannot apply from baseline.");
@@ -2002,9 +2023,10 @@ async function applyFromBaseline(config, db, metadata, result) {
   }
   console.log(chalk.green("  \u2713 baseline schema applied"));
   if (metadata.baselines) {
+    const insertOpts = tag ? { tag } : void 0;
     for (const baseline of metadata.baselines) {
       for (const inc of baseline.includes) {
-        await db.insertRecord(inc.file, inc.checksum, "applied");
+        await db.insertRecord(inc.file, inc.checksum, "applied", insertOpts);
         result.applied.push(inc.file);
       }
     }
@@ -2090,7 +2112,8 @@ async function commandAdvance(config, options) {
     await db.insertRecord(fileName, "", dbStatus, {
       migrationClass: "expand_contract",
       phase,
-      groupName: group
+      groupName: group,
+      tag: options.tag
     });
     const updatedRecords = await db.getAllRecords();
     const newState = deriveGroupState(updatedRecords, group).state;
@@ -2216,7 +2239,8 @@ async function commandApplyPhase(config, options) {
       await db.insertRecord(file.fileName, checksum, "applied", {
         migrationClass: "expand_contract",
         phase,
-        groupName: group
+        groupName: group,
+        tag: options.tag
       });
       console.log(chalk.green(`Applied phase "${phase}" for "${group}"`));
       return { success: true, group, phase };
@@ -2224,7 +2248,8 @@ async function commandApplyPhase(config, options) {
       await db.insertRecord(file.fileName, checksum, "failed", {
         migrationClass: "expand_contract",
         phase,
-        groupName: group
+        groupName: group,
+        tag: options.tag
       });
       const msg = `Failed to apply phase "${phase}" for "${group}": ${psqlResult.stderr}`;
       console.error(chalk.red(msg));
@@ -5405,11 +5430,12 @@ program.command("new <name>").description("Create a new migration SQL file with
   const config = await loadConfig();
   await commandNew(config, name, { expandContract: opts.expandContract });
 }));
-program.command("apply").description("Apply pending migrations via psql").option("--with-drift-check", "Check schema drift before apply and update dump after").option("--from-baseline", "Apply schema.sql first, then remaining migrations").action((opts) => run(async () => {
+program.command("apply").description("Apply pending migrations via psql").option("--with-drift-check", "Check schema drift before apply and update dump after").option("--from-baseline", "Apply schema.sql first, then remaining migrations").option("--tag <text>", "Tag to record with applied migrations (e.g. commit hash, release tag)").action((opts) => run(async () => {
   const config = await loadConfig();
   const result = await commandApply(config, {
     withDriftCheck: opts.withDriftCheck,
-    fromBaseline: opts.fromBaseline
+    fromBaseline: opts.fromBaseline,
+    tag: opts.tag
   });
   if (result.errors.length > 0) process.exit(1);
 }));
@@ -5462,7 +5488,7 @@ program.command("baseline").description("Squash applied migrations into schema.s
   const result = await commandBaseline(config, { keepSince: opts.keepSince });
   if (!result.success) process.exit(1);
 }));
-program.command("advance <group> <phase> <status>").description("Record a phase state transition (for external executor)").action((group, phase, status) => run(async () => {
+program.command("advance <group> <phase> <status>").description("Record a phase state transition (for external executor)").option("--tag <text>", "Tag to record (e.g. commit hash, release tag)").action((group, phase, status, opts) => run(async () => {
   const config = await loadConfig();
   const validPhases = ["expand", "backfill", "switch", "contract"];
   const validStatuses = ["running", "completed", "failed"];
@@ -5471,17 +5497,19 @@ program.command("advance <group> <phase> <status>").description("Record a phase
   const result = await commandAdvance(config, {
     group,
     phase,
-    status
+    status,
+    tag: opts.tag
   });
   if (!result.success) process.exit(1);
 }));
-program.command("apply-phase <group> <phase>").description("Apply a specific phase of a migration group via psql").action((group, phase) => run(async () => {
+program.command("apply-phase <group> <phase>").description("Apply a specific phase of a migration group via psql").option("--tag <text>", "Tag to record (e.g. commit hash, release tag)").action((group, phase, opts) => run(async () => {
   const config = await loadConfig();
   const validPhases = ["expand", "backfill", "switch", "contract"];
   if (!validPhases.includes(phase)) throw new Error(`Invalid phase: ${phase}`);
   const result = await commandApplyPhase(config, {
     group,
-    phase
+    phase,
+    tag: opts.tag
   });
   if (!result.success) process.exit(1);
 }));