migraguard 0.5.2 → 0.5.3

package/README.md

@@ -19,7 +19,7 @@ Execution is deliberately simple: plain SQL files executed via `psql`. migraguar
 - **Tamper detection in CI (offline)** — Only the tail file (linear) or leaf nodes (DAG) are editable. `check` rejects changes to any other file without DB connection
 - **Regression detection** — If a hotfixed file reverts to an old checksum, `apply` raises an error immediately
 - **Failure blocking with explicit resolve** — A `failed` migration blocks all progress until a human explicitly judges and resolves it
-- **Drift gate + Idempotency proof** — two [verification mechanisms](#verification-two-distinct-mechanisms): `apply --with-drift-check` detects schema divergence before applying; `verify` proves migrations are safely re-executable on a shadow DB
+- **Drift gate + Idempotency proof** — two [verification mechanisms](#verification-two-distinct-mechanisms): `apply --with-drift-check` detects local schema divergence before applying; `diff` verifies post-deploy schema consistency; `verify` proves migrations are safely re-executable on a shadow DB
 - **Mutual exclusion** — `apply` uses PostgreSQL advisory locks to prevent concurrent execution
 - **One release at a time** — the next migration cannot be added until the current release is deployed to all environments, ensuring the latest file is always hotfix-ready
 
@@ -65,6 +65,23 @@ migraguard separates file integrity and application state into two layers.
 
 metadata.json represents "which files should exist"; schema_migrations represents "what has been applied." This separation enables correct staged rollout from a single repository to multiple environments (staging, production).
 
+### Source of Truth: migrations (SSoT) vs schema.sql
+
+migraguard treats **migration SQL files** as the **Single Source of Truth (SSoT)** for schema evolution.
+They capture not only the end state, but also the *intent, ordering, and operational safety tactics* required for production changes.
+
+`schema.sql` is a **derived artifact**:
+- Generated from a real database via `dump` (pg_dump), and updated locally by `apply --with-drift-check`
+- Used as an **expected-state snapshot** for drift detection (`diff`) and human review
+- Not intended to be hand-edited or treated as the authoritative desired state
+
+This design supports migraguard's incident-prevention model:
+- Offline CI integrity checks (`check`) can reason about history and editability rules without a DB
+- Regression detection can catch "hotfix reversion" back to a previous checksum
+- Drift is treated as a deployment blocker unless explicitly resolved through the normal workflow
+
+> If you prefer a "desired state" workflow where the schema definition itself is the SSoT and migrations are generated from it, consider tools like Atlas. migraguard is optimized for teams writing DDL directly with operational guardrails.
+
 ### Checksum Normalization
 
 Checksums are computed on **normalized SQL** (SHA-256): comments are stripped (`-- ...` and `/* ... */` including nested), whitespace is collapsed, string literals are preserved as-is. Adding comments, adjusting indentation, or inserting blank lines does not change the checksum; only actual SQL statement changes are detected. `-- migraguard:depends-on` directives are also comments and do not affect the checksum.
@@ -90,10 +107,11 @@ The table is **fully INSERT-only** — no UPDATEs. Every application attempt (in
 
 | Mechanism | Purpose | When to use |
 |-----------|---------|-------------|
-| `apply --with-drift-check` | **Drift gate**: detect unauthorized schema changes before apply, auto-update dump after | CI pipeline on merge to release branches |
+| `apply --with-drift-check` | **Local drift gate**: detect unauthorized schema changes before apply, auto-update dump after | Local development before commit |
+| `diff` | **Post-deploy verification**: confirm DB schema matches expected `schema.sql` after apply | CI pipeline on merge to release branches (run after `apply`) |
 | `verify` | **Idempotency proof**: apply migrations twice on a shadow DB, confirm no errors and no schema change | Before releases or in CI as a final safety net |
 
-`apply --with-drift-check` guards against drift; `verify` proves re-executability. Both are stronger than lint rules — they operate on actual DB state. See [docs/state-model.md](docs/state-model.md) for detailed flows.
+`apply --with-drift-check` guards against drift in local development; `diff` verifies schema consistency after deployment; `verify` proves re-executability. All are stronger than lint rules — they operate on actual DB state. See [docs/state-model.md](docs/state-model.md) for detailed flows.
 
 ## Workflow
 
@@ -117,8 +135,8 @@ CI (PR):
   migraguard verify (optional)       → idempotency proof on shadow DB
 
 Deploy:
-  merge to db_dev → CI: apply --with-drift-check → staging
-  merge to db_pro → CI: apply --with-drift-check → production
+  merge to db_dev → CI: apply → diff → staging
+  merge to db_pro → CI: apply → diff → production
 ```
 
 **Key rule**: Do not add the next migration file until the current release is deployed to all environments. This ensures the latest file can always be modified and re-applied for hotfixes.
@@ -150,7 +168,7 @@ See [docs/state-model.md](docs/state-model.md) for detailed apply, check, resolv
 | `new <name>` | Generate a new migration SQL file |
 | `squash` | Merge pending files into one for release |
 | `apply` | Execute pending migrations via `psql` |
-| `apply --with-drift-check` | Drift check → apply → dump update |
+| `apply --with-drift-check` | Local: drift check → apply → dump update |
 | `resolve <file>` | Mark a failed migration as skipped (explicit judgment) |
 | `status` | Display migration status per file |
 | `editable` | List currently editable files (tail / leaf) |
@@ -207,7 +225,13 @@ jobs:
           node-version: '20'
       - run: npm ci
       - run: npx migraguard check
-      - run: npx migraguard apply --with-drift-check
+      - run: npx migraguard apply
+        env:
+          PGHOST: ${{ secrets.DB_HOST }}
+          PGDATABASE: ${{ secrets.DB_NAME }}
+          PGUSER: ${{ secrets.DB_USER }}
+          PGPASSWORD: ${{ secrets.DB_PASSWORD }}
+      - run: npx migraguard diff
         env:
           PGHOST: ${{ secrets.DB_HOST }}
           PGDATABASE: ${{ secrets.DB_NAME }}
@@ -219,6 +243,7 @@ jobs:
 
 ```json
 {
+  "model": "dag",
   "migrationsDirs": ["db/migrations"],
   "schemaFile": "db/schema.sql",
   "metadataFile": "db/.migraguard/metadata.json",
@@ -251,6 +276,12 @@ jobs:
 }
 ```
 
+### Model Configuration
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `model` | _(unset = linear)_ | Set to `"dag"` to enable DAG mode. When set in config, takes precedence over `metadata.json` |
+
 ### Naming Configuration
 
 | Key | Default | Description |
@@ -422,7 +453,7 @@ migraguard embeds operational policies into the tool and prevents incidents via
 |------|-----------|---------|-------|--------|------------------|
 | **Tamper detection** | checksum + CI gate (offline) | checksum (at apply time) | Merkle hash (atlas.sum) | Merkle tree (sqitch.plan) | none |
 | **Regression detection** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Drift detection** | ✅ apply --with-drift-check | ❌ | ✅ schema diff | ❌ | ⚠️ |
+| **Drift detection** | ✅ apply --with-drift-check (local) / diff (CI) | ❌ | ✅ schema diff | ❌ | ⚠️ |
 | **Idempotency verification** | ✅ verify (double-apply) | ❌ | ❌ | ❌ | ❌ |
 | **Parallel releases** | ✅ DAG | ❌ | ❌ | ⚠️ | ❌ |
 | **Offline CI gate** | ✅ check | ❌ | ✅ atlas.sum | ❌ | ❌ |

package/dist/cli.js

@@ -112,6 +112,7 @@ function buildConfig(raw, configDir) {
   };
   return {
     configDir,
+    ...raw.model ? { model: raw.model } : {},
     migrationsDirs: resolveMigrationsDirs(raw),
     schemaFile: raw.schemaFile ?? "db/schema.sql",
     metadataFile: raw.metadataFile ?? "db/.migraguard/metadata.json",
@@ -342,8 +343,8 @@ function addEntry(metadata, entry) {
     migrations: [...metadata.migrations, entry]
   };
 }
-function isDagMode(metadata) {
-  return metadata.model === "dag";
+function isDagMode(metadata, config) {
+  return config?.model === "dag" || metadata.model === "dag";
 }
 function isPreModelSince(metadata, fileName) {
   if (!metadata.model || !metadata.modelSince) return true;
@@ -863,7 +864,7 @@ async function commandCheck(config) {
   const errors = [];
   const metadata = await loadMetadata(config);
   const files = await scanMigrations(config);
-  const dag = isDagMode(metadata);
+  const dag = isDagMode(metadata, config);
   const metadataMap = new Map(metadata.migrations.map((m) => [m.file, m.checksum]));
   const recordedFiles = files.filter((f) => metadataMap.has(f.fileName));
   const newFiles = files.filter((f) => !metadataMap.has(f.fileName));
@@ -973,7 +974,7 @@ async function commandSquash(config) {
     console.log(chalk6.yellow("No new migration files to squash."));
     return;
   }
-  if (isDagMode(metadata)) {
+  if (isDagMode(metadata, config)) {
     await dagSquash(config, newFiles, metadata);
   } else {
     if (newFiles.length === 1) {
@@ -2198,7 +2199,7 @@ async function commandEditable(config) {
     return { editableFiles: [], entries: [] };
   }
   const metadata = await loadMetadata(config);
-  const dag = isDagMode(metadata);
+  const dag = isDagMode(metadata, config);
   const metadataFileSet = new Set(metadata.migrations.map((m) => m.file));
   const newFiles = files.filter((f) => !metadataFileSet.has(f.fileName));
   const entries = [];
@@ -2391,7 +2392,7 @@ async function commandApply(config, options) {
     }
   }
   const metadata = await loadMetadata(config);
-  const dag = isDagMode(metadata);
+  const dag = isDagMode(metadata, config);
   let graph = null;
   let leafSet = null;
   if (dag) {