@xubylele/schema-forge 1.6.0 → 1.7.0

package/README.md

@@ -13,6 +13,7 @@ A modern CLI tool for database schema management with a clean DSL and automatic
 - **Default Change Detection** - Detects added/removed/modified column defaults and generates ALTER COLUMN SET/DROP DEFAULT
 - **Postgres/Supabase** - Currently supports PostgreSQL and Supabase
 - **Constraint Diffing** - Detects UNIQUE and PRIMARY KEY changes with deterministic constraint names
+- **Live PostgreSQL Introspection** - Extract normalized schema directly from `information_schema`
 
 ## Installation
 
@@ -56,6 +57,17 @@ Run tests:
 npm test
 ```
 
+Run real-db drift integration tests:
+
+```bash
+npm run test:integration:drift
+```
+
+Notes:
+
+- Local explicit run: set `SF_RUN_REAL_DB_TESTS=true` (uses Testcontainers `postgres:16-alpine`, Docker required).
+- CI/service mode: set `SF_USE_CI_POSTGRES=true` and `DATABASE_URL` to reuse an existing Postgres service.
+
 ## Getting Started
 
 Here's a quick walkthrough to get started with SchemaForge:
@@ -205,9 +217,13 @@ schema-forge diff [--safe] [--force]
 
 - `--safe` - Block execution if destructive operations are detected (exits with error)
 - `--force` - Bypass safety checks and proceed with displaying destructive SQL (shows warning)
+- `--url` - PostgreSQL connection URL for live database diff (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
 
 Shows what SQL would be generated if you ran `generate`. Useful for previewing changes. Safety behavior is the same as `generate` command. In CI environments, exits with code 3 if destructive operations are detected unless `--force` is used. See [CI Behavior](#ci-behavior) for more details.
 
+When `--url` (or `DATABASE_URL`) is provided, `diff` compares your target DSL schema against the live PostgreSQL schema introspected from `information_schema`.
+
 ### `schema-forge import`
 
 Reconstruct `schemaforge/schema.sf` from existing PostgreSQL/Supabase SQL migrations.
@@ -234,6 +250,36 @@ Detect destructive or risky schema changes before generating/applying migrations
 schema-forge validate
 ```
 
+Live drift validation:
+
+```bash
+schema-forge validate --url "$DATABASE_URL" --json
+```
+
+Live `--json` output returns a structured `DriftReport`:
+
+```json
+{
+  "missingTables": ["users_archive"],
+  "extraTables": ["audit_log"],
+  "columnDifferences": [
+    {
+      "tableName": "users",
+      "missingInLive": ["nickname"],
+      "extraInLive": ["last_login"]
+    }
+  ],
+  "typeMismatches": [
+    {
+      "tableName": "users",
+      "columnName": "email",
+      "expectedType": "varchar",
+      "actualType": "text"
+    }
+  ]
+}
+```
+
 Validation checks include:
 
 - Dropped tables (`DROP_TABLE`, error)
@@ -247,6 +293,13 @@ Use JSON mode for CI and automation:
 schema-forge validate --json
 ```
 
+Live mode options:
+
+- `--url` - PostgreSQL connection URL for live drift validation (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
+
+In live mode, exit code `2` is used when drift is detected between `state.json` and the live database.
+
 Exit codes (also see [CI Behavior](#ci-behavior)):
 
 - `3` in CI environment if destructive findings detected
@@ -258,6 +311,46 @@ Exit codes:
 - `1` when one or more `error` findings are detected
 - `0` when no `error` findings are detected (warnings alone do not fail)
 
+### `schema-forge doctor`
+
+Check live database drift against your tracked `state.json`.
+
+```bash
+schema-forge doctor --url "$DATABASE_URL"
+```
+
+Use JSON mode for CI and automation:
+
+```bash
+schema-forge doctor --url "$DATABASE_URL" --json
+```
+
+Options:
+
+- `--url` - PostgreSQL connection URL (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
+- `--json` - Output structured drift report JSON
+
+Exit codes:
+
+- `0` when no drift is detected (healthy)
+- `2` when drift is detected between `state.json` and live database schema
+
+### `schema-forge introspect`
+
+Extract normalized schema directly from a live PostgreSQL database.
+
+```bash
+schema-forge introspect --url "$DATABASE_URL" --json
+```
+
+**Options:**
+
+- `--url` - PostgreSQL connection URL (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
+- `--json` - Output normalized schema as JSON
+- `--out <path>` - Write normalized schema JSON to a file
+
 ## CI Behavior
 
 SchemaForge ensures deterministic behavior in Continuous Integration (CI) environments to prevent accidental destructive operations.
@@ -276,8 +369,8 @@ SchemaForge uses specific exit codes for different scenarios:
 | Exit Code | Meaning |
 | --------- | ------- |
 | `0` | Success - no changes or no destructive operations detected |
-| `1` | General error - validation failed, operation declined, missing files, etc. |
-| `2` | Schema validation error - invalid DSL syntax or structure |
+| `1` | Validation/general error - invalid DSL, operation declined, missing files, etc. |
+| `2` | Drift detected between expected state and live database schema |
 | `3` | **CI Destructive** - destructive operations detected in CI environment without `--force` |
 
 ### Destructive Operations in CI
@@ -312,6 +405,19 @@ When `CI=true`, SchemaForge will:
 - ✅ Allow explicit override with `--force` flag
 - ❌ Not accept user input for confirmation
 
+### Drift Integration Tests in CI
+
+For drift reliability checks against a real database, run:
+
+```bash
+npm run test:integration:drift
+```
+
+The integration harness supports two deterministic paths:
+
+- `SF_USE_CI_POSTGRES=true` + `DATABASE_URL`: uses the CI Postgres service directly.
+- No CI Postgres env: spins up an isolated Testcontainers Postgres instance.
+
 ### Using `--safe` in CI
 
 The `--safe` flag is compatible with CI and blocks execution of destructive operations:

package/dist/cli.d.ts

@@ -1,2 +1 @@
-
-export {  }
+#!/usr/bin/env node

package/dist/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -45,11 +46,11 @@ function parseSchema(source) {
     "date"
   ]);
   const validIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
-  function normalizeColumnType4(type) {
+  function normalizeColumnType6(type) {
     return type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
   }
   function isValidColumnType2(type) {
-    const normalizedType = normalizeColumnType4(type);
+    const normalizedType = normalizeColumnType6(type);
     if (validBaseColumnTypes.has(normalizedType)) {
       return true;
     }
@@ -173,7 +174,7 @@ function parseSchema(source) {
       throw new Error(`Line ${lineNum}: Invalid column definition. Expected: <name> <type> [modifiers...]`);
     }
     const colName = tokens[0];
-    const colType = normalizeColumnType4(tokens[1]);
+    const colType = normalizeColumnType6(tokens[1]);
     validateIdentifier(colName, lineNum, "column");
     if (!isValidColumnType2(colType)) {
       throw new Error(`Line ${lineNum}: Invalid column type '${tokens[1]}'. Valid types: ${Array.from(validBaseColumnTypes).join(", ")}, varchar(n), numeric(p,s)`);
@@ -690,6 +691,75 @@ var init_diff = __esm({
   }
 });
 
+// node_modules/@xubylele/schema-forge-core/dist/core/drift-analyzer.js
+function normalizeColumnType2(type) {
+  return type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
+}
+function getSortedNames2(values) {
+  return Array.from(values).sort((left, right) => left.localeCompare(right));
+}
+function analyzeSchemaDrift(state, liveSchema) {
+  const stateTableNames = getSortedNames2(Object.keys(state.tables));
+  const liveTableNames = getSortedNames2(Object.keys(liveSchema.tables));
+  const liveTableNameSet = new Set(liveTableNames);
+  const stateTableNameSet = new Set(stateTableNames);
+  const missingTables = stateTableNames.filter((tableName) => !liveTableNameSet.has(tableName));
+  const extraTables = liveTableNames.filter((tableName) => !stateTableNameSet.has(tableName));
+  const commonTableNames = liveTableNames.filter((tableName) => stateTableNameSet.has(tableName));
+  const columnDifferences = [];
+  const typeMismatches = [];
+  for (const tableName of commonTableNames) {
+    const stateTable = state.tables[tableName];
+    const liveTable = liveSchema.tables[tableName];
+    if (!stateTable || !liveTable) {
+      continue;
+    }
+    const stateColumnNames = getSortedNames2(Object.keys(stateTable.columns));
+    const liveColumnsByName = new Map(liveTable.columns.map((column) => [column.name, column]));
+    const liveColumnNames = getSortedNames2(liveColumnsByName.keys());
+    const stateColumnNameSet = new Set(stateColumnNames);
+    const liveColumnNameSet = new Set(liveColumnNames);
+    const missingInLive = stateColumnNames.filter((columnName) => !liveColumnNameSet.has(columnName));
+    const extraInLive = liveColumnNames.filter((columnName) => !stateColumnNameSet.has(columnName));
+    if (missingInLive.length > 0 || extraInLive.length > 0) {
+      columnDifferences.push({
+        tableName,
+        missingInLive,
+        extraInLive
+      });
+    }
+    const commonColumns = stateColumnNames.filter((columnName) => liveColumnNameSet.has(columnName));
+    for (const columnName of commonColumns) {
+      const stateColumn = stateTable.columns[columnName];
+      const liveColumn = liveColumnsByName.get(columnName);
+      if (!stateColumn || !liveColumn) {
+        continue;
+      }
+      const expectedType = stateColumn.type;
+      const actualType = liveColumn.type;
+      if (normalizeColumnType2(expectedType) !== normalizeColumnType2(actualType)) {
+        typeMismatches.push({
+          tableName,
+          columnName,
+          expectedType,
+          actualType
+        });
+      }
+    }
+  }
+  return {
+    missingTables,
+    extraTables,
+    columnDifferences,
+    typeMismatches
+  };
+}
+var init_drift_analyzer = __esm({
+  "node_modules/@xubylele/schema-forge-core/dist/core/drift-analyzer.js"() {
+    "use strict";
+  }
+});
+
 // node_modules/@xubylele/schema-forge-core/dist/core/validator.js
 function isValidColumnType(type) {
   const normalizedType = type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
@@ -777,15 +847,15 @@ var init_validator = __esm({
 });
 
 // node_modules/@xubylele/schema-forge-core/dist/core/safety/operation-classifier.js
-function normalizeColumnType2(type) {
+function normalizeColumnType3(type) {
   return type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
 }
 function parseVarcharLength(type) {
-  const match = normalizeColumnType2(type).match(/^varchar\((\d+)\)$/);
+  const match = normalizeColumnType3(type).match(/^varchar\((\d+)\)$/);
   return match ? Number(match[1]) : null;
 }
 function parseNumericType(type) {
-  const match = normalizeColumnType2(type).match(/^numeric\((\d+),(\d+)\)$/);
+  const match = normalizeColumnType3(type).match(/^numeric\((\d+),(\d+)\)$/);
   if (!match) {
     return null;
   }
@@ -795,8 +865,8 @@ function parseNumericType(type) {
   };
 }
 function classifyTypeChange(from, to) {
-  const fromType = normalizeColumnType2(from);
-  const toType = normalizeColumnType2(to);
+  const fromType = normalizeColumnType3(from);
+  const toType = normalizeColumnType3(to);
   const uuidInvolved = fromType === "uuid" || toType === "uuid";
   if (uuidInvolved && fromType !== toType) {
     return "DESTRUCTIVE";
@@ -868,15 +938,15 @@ var init_operation_classifier = __esm({
 });
 
 // node_modules/@xubylele/schema-forge-core/dist/core/safety/safety-checker.js
-function normalizeColumnType3(type) {
+function normalizeColumnType4(type) {
   return type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
 }
 function parseVarcharLength2(type) {
-  const match = normalizeColumnType3(type).match(/^varchar\((\d+)\)$/);
+  const match = normalizeColumnType4(type).match(/^varchar\((\d+)\)$/);
   return match ? Number(match[1]) : null;
 }
 function parseNumericType2(type) {
-  const match = normalizeColumnType3(type).match(/^numeric\((\d+),(\d+)\)$/);
+  const match = normalizeColumnType4(type).match(/^numeric\((\d+),(\d+)\)$/);
   if (!match) {
     return null;
   }
@@ -886,8 +956,8 @@ function parseNumericType2(type) {
   };
 }
 function generateTypeChangeMessage(from, to) {
-  const fromType = normalizeColumnType3(from);
-  const toType = normalizeColumnType3(to);
+  const fromType = normalizeColumnType4(from);
+  const toType = normalizeColumnType4(to);
   const uuidInvolved = fromType === "uuid" || toType === "uuid";
   if (uuidInvolved && fromType !== toType) {
     return `Type changed from ${fromType} to ${toType} (likely incompatible cast)`;
@@ -952,8 +1022,8 @@ function checkOperationSafety(operation) {
         code: "ALTER_COLUMN_TYPE",
         table: operation.tableName,
         column: operation.columnName,
-        from: normalizeColumnType3(operation.fromType),
-        to: normalizeColumnType3(operation.toType),
+        from: normalizeColumnType4(operation.fromType),
+        to: normalizeColumnType4(operation.toType),
         message: generateTypeChangeMessage(operation.fromType, operation.toType),
         operationKind: operation.kind
       };
@@ -2156,6 +2226,359 @@ var init_load_migrations = __esm({
   }
 });
 
+// node_modules/@xubylele/schema-forge-core/dist/core/sql/introspect-postgres.js
+function toTableKey(schema, table) {
+  if (schema === DEFAULT_SCHEMA) {
+    return table;
+  }
+  return `${schema}.${table}`;
+}
+function normalizeSchemas(schemas) {
+  const values = schemas ?? [DEFAULT_SCHEMA];
+  const deduped = /* @__PURE__ */ new Set();
+  for (const schema of values) {
+    const trimmed = schema.trim();
+    if (trimmed.length > 0) {
+      deduped.add(trimmed);
+    }
+  }
+  if (deduped.size === 0) {
+    deduped.add(DEFAULT_SCHEMA);
+  }
+  return Array.from(deduped).sort((a, b) => a.localeCompare(b));
+}
+function normalizeColumnType5(row) {
+  const dataType = row.data_type.toLowerCase();
+  const udtName = row.udt_name.toLowerCase();
+  if (dataType === "character varying") {
+    if (row.character_maximum_length !== null) {
+      return `varchar(${row.character_maximum_length})`;
+    }
+    return "varchar";
+  }
+  if (dataType === "timestamp with time zone") {
+    return "timestamptz";
+  }
+  if (dataType === "integer" || udtName === "int4") {
+    return "int";
+  }
+  if (dataType === "bigint" || udtName === "int8") {
+    return "bigint";
+  }
+  if (dataType === "numeric") {
+    if (row.numeric_precision !== null && row.numeric_scale !== null) {
+      return `numeric(${row.numeric_precision},${row.numeric_scale})`;
+    }
+    return "numeric";
+  }
+  if (dataType === "boolean" || udtName === "bool") {
+    return "boolean";
+  }
+  if (dataType === "uuid") {
+    return "uuid";
+  }
+  if (dataType === "text") {
+    return "text";
+  }
+  if (dataType === "date") {
+    return "date";
+  }
+  return dataType;
+}
+function normalizeConstraints(constraintRows, foreignKeyRows) {
+  const constraints = /* @__PURE__ */ new Map();
+  for (const row of constraintRows) {
+    const key = `${row.table_schema}.${row.table_name}.${row.constraint_name}.${row.constraint_type}`;
+    const existing = constraints.get(key);
+    if (existing) {
+      if (row.column_name !== null) {
+        existing.columns.push({
+          name: row.column_name,
+          position: row.ordinal_position ?? Number.MAX_SAFE_INTEGER
+        });
+      }
+      if (!existing.checkClause && row.check_clause) {
+        existing.checkClause = row.check_clause;
+      }
+      continue;
+    }
+    constraints.set(key, {
+      tableSchema: row.table_schema,
+      tableName: row.table_name,
+      name: row.constraint_name,
+      type: row.constraint_type,
+      columns: row.column_name === null ? [] : [{
+        name: row.column_name,
+        position: row.ordinal_position ?? Number.MAX_SAFE_INTEGER
+      }],
+      ...row.check_clause ? { checkClause: row.check_clause } : {}
+    });
+  }
+  const normalized = [];
+  for (const value of constraints.values()) {
+    value.columns.sort((left, right) => {
+      if (left.position !== right.position) {
+        return left.position - right.position;
+      }
+      return left.name.localeCompare(right.name);
+    });
+    normalized.push({
+      tableSchema: value.tableSchema,
+      tableName: value.tableName,
+      name: value.name,
+      type: value.type,
+      columns: value.columns.map((item) => item.name),
+      ...value.checkClause ? { checkClause: value.checkClause } : {}
+    });
+  }
+  const foreignKeys = /* @__PURE__ */ new Map();
+  for (const row of foreignKeyRows) {
+    const key = `${row.table_schema}.${row.table_name}.${row.constraint_name}`;
+    const existing = foreignKeys.get(key);
+    if (existing) {
+      existing.local.push({ name: row.local_column_name, position: row.position });
+      existing.referenced.push({ name: row.referenced_column_name, position: row.position });
+      continue;
+    }
+    foreignKeys.set(key, {
+      tableSchema: row.table_schema,
+      tableName: row.table_name,
+      name: row.constraint_name,
+      local: [{ name: row.local_column_name, position: row.position }],
+      referencedTableSchema: row.referenced_table_schema,
+      referencedTableName: row.referenced_table_name,
+      referenced: [{ name: row.referenced_column_name, position: row.position }]
+    });
+  }
+  for (const value of foreignKeys.values()) {
+    value.local.sort((left, right) => left.position - right.position || left.name.localeCompare(right.name));
+    value.referenced.sort((left, right) => left.position - right.position || left.name.localeCompare(right.name));
+    normalized.push({
+      tableSchema: value.tableSchema,
+      tableName: value.tableName,
+      name: value.name,
+      type: "FOREIGN KEY",
+      columns: value.local.map((item) => item.name),
+      referencedTableSchema: value.referencedTableSchema,
+      referencedTableName: value.referencedTableName,
+      referencedColumns: value.referenced.map((item) => item.name)
+    });
+  }
+  normalized.sort((left, right) => {
+    if (left.tableSchema !== right.tableSchema) {
+      return left.tableSchema.localeCompare(right.tableSchema);
+    }
+    if (left.tableName !== right.tableName) {
+      return left.tableName.localeCompare(right.tableName);
+    }
+    const typeOrderDiff = CONSTRAINT_TYPE_ORDER[left.type] - CONSTRAINT_TYPE_ORDER[right.type];
+    if (typeOrderDiff !== 0) {
+      return typeOrderDiff;
+    }
+    if (left.name !== right.name) {
+      return left.name.localeCompare(right.name);
+    }
+    return left.columns.join(",").localeCompare(right.columns.join(","));
+  });
+  return normalized;
+}
+async function introspectPostgresSchema(options) {
+  const schemaFilter = normalizeSchemas(options.schemas);
+  const [tableRows, columnRows, constraintRows, foreignKeyRows] = await Promise.all([
+    options.query(TABLES_QUERY, [schemaFilter]),
+    options.query(COLUMNS_QUERY, [schemaFilter]),
+    options.query(CONSTRAINTS_QUERY, [schemaFilter]),
+    options.query(FOREIGN_KEYS_QUERY, [schemaFilter])
+  ]);
+  const sortedTables = [...tableRows].sort((left, right) => {
+    if (left.table_schema !== right.table_schema) {
+      return left.table_schema.localeCompare(right.table_schema);
+    }
+    return left.table_name.localeCompare(right.table_name);
+  });
+  const sortedColumns = [...columnRows].sort((left, right) => {
+    if (left.table_schema !== right.table_schema) {
+      return left.table_schema.localeCompare(right.table_schema);
+    }
+    if (left.table_name !== right.table_name) {
+      return left.table_name.localeCompare(right.table_name);
+    }
+    if (left.ordinal_position !== right.ordinal_position) {
+      return left.ordinal_position - right.ordinal_position;
+    }
+    return left.column_name.localeCompare(right.column_name);
+  });
+  const normalizedConstraints = normalizeConstraints(constraintRows, foreignKeyRows);
+  const tableMap = /* @__PURE__ */ new Map();
+  const columnMap = /* @__PURE__ */ new Map();
+  for (const row of sortedTables) {
+    const key = toTableKey(row.table_schema, row.table_name);
+    const table = { name: key, columns: [], primaryKey: null };
+    tableMap.set(key, table);
+    columnMap.set(key, /* @__PURE__ */ new Map());
+  }
+  for (const row of sortedColumns) {
+    const key = toTableKey(row.table_schema, row.table_name);
+    const table = tableMap.get(key);
+    const columnsByName = columnMap.get(key);
+    if (!table || !columnsByName) {
+      continue;
+    }
+    const column = {
+      name: row.column_name,
+      type: normalizeColumnType5(row),
+      nullable: row.is_nullable === "YES"
+    };
+    const normalizedDefault = normalizeDefault(row.column_default);
+    if (normalizedDefault !== null) {
+      column.default = normalizedDefault;
+    }
+    table.columns.push(column);
+    columnsByName.set(column.name, column);
+  }
+  for (const constraint of normalizedConstraints) {
+    const tableKey = toTableKey(constraint.tableSchema, constraint.tableName);
+    const table = tableMap.get(tableKey);
+    const columnsByName = columnMap.get(tableKey);
+    if (!table || !columnsByName) {
+      continue;
+    }
+    if (constraint.type === "PRIMARY KEY") {
+      if (constraint.columns.length === 1) {
+        const column = columnsByName.get(constraint.columns[0]);
+        if (column) {
+          column.primaryKey = true;
+          column.nullable = false;
+          table.primaryKey = column.name;
+        }
+      }
+      continue;
+    }
+    if (constraint.type === "UNIQUE") {
+      if (constraint.columns.length === 1) {
+        const column = columnsByName.get(constraint.columns[0]);
+        if (column) {
+          column.unique = true;
+        }
+      }
+      continue;
+    }
+    if (constraint.type === "FOREIGN KEY") {
+      if (constraint.columns.length === 1 && constraint.referencedColumns && constraint.referencedColumns.length === 1 && constraint.referencedTableName) {
+        const column = columnsByName.get(constraint.columns[0]);
+        if (column) {
+          column.foreignKey = {
+            table: toTableKey(constraint.referencedTableSchema ?? DEFAULT_SCHEMA, constraint.referencedTableName),
+            column: constraint.referencedColumns[0]
+          };
+        }
+      }
+    }
+  }
+  const orderedTableNames = Array.from(tableMap.keys()).sort((left, right) => left.localeCompare(right));
+  const tables = {};
+  for (const tableName of orderedTableNames) {
+    const table = tableMap.get(tableName);
+    if (table) {
+      tables[tableName] = table;
+    }
+  }
+  return { tables };
+}
+var DEFAULT_SCHEMA, CONSTRAINT_TYPE_ORDER, TABLES_QUERY, COLUMNS_QUERY, CONSTRAINTS_QUERY, FOREIGN_KEYS_QUERY;
+var init_introspect_postgres = __esm({
+  "node_modules/@xubylele/schema-forge-core/dist/core/sql/introspect-postgres.js"() {
+    "use strict";
+    init_normalize();
+    DEFAULT_SCHEMA = "public";
+    CONSTRAINT_TYPE_ORDER = {
+      "PRIMARY KEY": 0,
+      UNIQUE: 1,
+      "FOREIGN KEY": 2,
+      CHECK: 3
+    };
+    TABLES_QUERY = `
+SELECT
+  table_schema,
+  table_name
+FROM information_schema.tables
+WHERE table_type = 'BASE TABLE'
+  AND table_schema = ANY($1::text[])
+`;
+    COLUMNS_QUERY = `
+SELECT
+  table_schema,
+  table_name,
+  column_name,
+  ordinal_position,
+  is_nullable,
+  data_type,
+  udt_name,
+  character_maximum_length,
+  numeric_precision,
+  numeric_scale,
+  column_default
+FROM information_schema.columns
+WHERE table_schema = ANY($1::text[])
+`;
+    CONSTRAINTS_QUERY = `
+SELECT
+  tc.table_schema,
+  tc.table_name,
+  tc.constraint_name,
+  tc.constraint_type,
+  kcu.column_name,
+  kcu.ordinal_position,
+  cc.check_clause
+FROM information_schema.table_constraints tc
+LEFT JOIN information_schema.key_column_usage kcu
+  ON tc.constraint_catalog = kcu.constraint_catalog
+  AND tc.constraint_schema = kcu.constraint_schema
+  AND tc.constraint_name = kcu.constraint_name
+  AND tc.table_schema = kcu.table_schema
+  AND tc.table_name = kcu.table_name
+LEFT JOIN information_schema.check_constraints cc
+  ON tc.constraint_catalog = cc.constraint_catalog
+  AND tc.constraint_schema = cc.constraint_schema
+  AND tc.constraint_name = cc.constraint_name
+WHERE tc.table_schema = ANY($1::text[])
+  AND tc.constraint_type IN ('PRIMARY KEY', 'UNIQUE', 'CHECK')
+`;
+    FOREIGN_KEYS_QUERY = `
+SELECT
+  src_ns.nspname AS table_schema,
+  src.relname AS table_name,
+  con.conname AS constraint_name,
+  src_attr.attname AS local_column_name,
+  ref_ns.nspname AS referenced_table_schema,
+  ref.relname AS referenced_table_name,
+  ref_attr.attname AS referenced_column_name,
+  src_key.ord AS position
+FROM pg_constraint con
+JOIN pg_class src
+  ON src.oid = con.conrelid
+JOIN pg_namespace src_ns
+  ON src_ns.oid = src.relnamespace
+JOIN pg_class ref
+  ON ref.oid = con.confrelid
+JOIN pg_namespace ref_ns
+  ON ref_ns.oid = ref.relnamespace
+JOIN LATERAL unnest(con.conkey) WITH ORDINALITY AS src_key(attnum, ord)
+  ON TRUE
+JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS ref_key(attnum, ord)
+  ON ref_key.ord = src_key.ord
+JOIN pg_attribute src_attr
+  ON src_attr.attrelid = con.conrelid
+  AND src_attr.attnum = src_key.attnum
+JOIN pg_attribute ref_attr
+  ON ref_attr.attrelid = con.confrelid
+  AND ref_attr.attnum = ref_key.attnum
+WHERE con.contype = 'f'
+  AND src_ns.nspname = ANY($1::text[])
+`;
+  }
+});
+
 // node_modules/@xubylele/schema-forge-core/dist/core/paths.js
 function getProjectRoot2(cwd = process.cwd()) {
   return cwd;
@@ -2218,6 +2641,7 @@ var init_errors = __esm({
 var dist_exports = {};
 __export(dist_exports, {
   SchemaValidationError: () => SchemaValidationError,
+  analyzeSchemaDrift: () => analyzeSchemaDrift,
   applySqlOps: () => applySqlOps,
   checkOperationSafety: () => checkOperationSafety,
   checkSchemaSafety: () => checkSchemaSafety,
@@ -2236,6 +2660,7 @@ __export(dist_exports, {
   getStatePath: () => getStatePath2,
   getTableNamesFromSchema: () => getTableNamesFromSchema,
   getTableNamesFromState: () => getTableNamesFromState,
+  introspectPostgresSchema: () => introspectPostgresSchema,
   legacyPkName: () => legacyPkName,
   legacyUqName: () => legacyUqName,
   loadMigrationSqlInput: () => loadMigrationSqlInput,
@@ -2273,6 +2698,7 @@ var init_dist = __esm({
     "use strict";
     init_parser();
     init_diff();
+    init_drift_analyzer();
     init_validator();
     init_validate();
     init_safety();
@@ -2283,6 +2709,7 @@ var init_dist = __esm({
     init_schema_to_dsl();
     init_load_migrations();
     init_split_statements();
+    init_introspect_postgres();
     init_fs();
     init_normalize();
     init_paths();
@@ -2292,12 +2719,12 @@ var init_dist = __esm({
 });
 
 // src/cli.ts
-var import_commander6 = require("commander");
+var import_commander8 = require("commander");
 
 // package.json
 var package_default = {
   name: "@xubylele/schema-forge",
-  version: "1.6.0",
+  version: "1.7.0",
   description: "Universal migration generator from schema DSL",
   main: "dist/cli.js",
   type: "commonjs",
@@ -2308,6 +2735,7 @@ var package_default = {
     build: "tsup src/cli.ts --format cjs --dts",
     dev: "ts-node src/cli.ts",
     test: "vitest",
+    "test:integration:drift": "vitest run test/drift-realdb.integration.test.ts",
     prepublishOnly: "npm run build",
     "publish:public": "npm publish --access public",
     changeset: "changeset",
@@ -2339,12 +2767,15 @@ var package_default = {
   dependencies: {
     boxen: "^8.0.1",
     chalk: "^5.6.2",
-    commander: "^14.0.3"
+    commander: "^14.0.3",
+    pg: "^8.19.0"
   },
   devDependencies: {
-    "@changesets/cli": "^2.29.8",
+    "@changesets/cli": "^2.30.0",
     "@types/node": "^25.2.3",
-    "@xubylele/schema-forge-core": "^1.2.0",
+    "@types/pg": "^8.18.0",
+    "@xubylele/schema-forge-core": "^1.3.0",
+    testcontainers: "^11.8.1",
     "ts-node": "^10.9.2",
     tsup: "^8.5.1",
     typescript: "^5.9.3",
@@ -2491,6 +2922,14 @@ async function parseMigrationSql2(sql) {
   const core = await loadCore();
   return core.parseMigrationSql(sql);
 }
+async function introspectPostgresSchema2(options) {
+  const core = await loadCore();
+  return core.introspectPostgresSchema(options);
+}
+async function analyzeSchemaDrift2(state, liveSchema) {
+  const core = await loadCore();
+  return core.analyzeSchemaDrift(state, liveSchema);
+}
 async function applySqlOps2(ops) {
   const core = await loadCore();
   return core.applySqlOps(ops);
@@ -2512,6 +2951,40 @@ async function isSchemaValidationError(error2) {
   return error2 instanceof core.SchemaValidationError;
 }
 
+// src/core/postgres.ts
+var import_pg = require("pg");
+function resolvePostgresConnectionString(options = {}) {
+  const explicitUrl = options.url?.trim();
+  if (explicitUrl) {
+    return explicitUrl;
+  }
+  const envUrl = process.env.DATABASE_URL?.trim();
+  if (envUrl) {
+    return envUrl;
+  }
+  throw new Error("PostgreSQL connection URL is required. Pass --url or set DATABASE_URL.");
+}
+function parseSchemaList(value) {
+  if (!value) {
+    return void 0;
+  }
+  const schemas = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return schemas.length > 0 ? schemas : void 0;
+}
+async function withPostgresQueryExecutor(connectionString, run) {
+  const client = new import_pg.Client({ connectionString });
+  await client.connect();
+  const query = async (sql, params) => {
+    const result = await client.query(sql, params ? [...params] : void 0);
+    return result.rows;
+  };
+  try {
+    return await run(query);
+  } finally {
+    await client.end();
+  }
+}
+
 // src/utils/exitCodes.ts
 var EXIT_CODES = {
   /** Successful operation */
@@ -2646,7 +3119,6 @@ function hasDestructiveFindings(findings) {
 }
 
 // src/commands/diff.ts
-var REQUIRED_CONFIG_FIELDS = ["schemaFile", "stateFile"];
 function resolveConfigPath(root, targetPath) {
   return import_path7.default.isAbsolute(targetPath) ? targetPath : import_path7.default.join(root, targetPath);
 }
@@ -2660,14 +3132,16 @@ async function runDiff(options = {}) {
     throw new Error('SchemaForge project not initialized. Run "schema-forge init" first.');
   }
   const config = await readJsonFile(configPath, {});
-  for (const field of REQUIRED_CONFIG_FIELDS) {
+  const useLiveDatabase = Boolean(options.url || process.env.DATABASE_URL);
+  const requiredFields = useLiveDatabase ? ["schemaFile"] : ["schemaFile", "stateFile"];
+  for (const field of requiredFields) {
     const value = config[field];
     if (!value || typeof value !== "string") {
       throw new Error(`Invalid config: '${field}' is required`);
     }
   }
   const schemaPath = resolveConfigPath(root, config.schemaFile);
-  const statePath = resolveConfigPath(root, config.stateFile);
+  const statePath = config.stateFile ? resolveConfigPath(root, config.stateFile) : null;
   const { provider } = resolveProvider(config.provider);
   const schemaSource = await readTextFile(schemaPath);
   const schema = await parseSchema2(schemaSource);
@@ -2679,7 +3153,17 @@ async function runDiff(options = {}) {
     }
     throw error2;
   }
-  const previousState = await loadState2(statePath);
+  const previousState = useLiveDatabase ? await withPostgresQueryExecutor(
+    resolvePostgresConnectionString({ url: options.url }),
+    async (query) => {
+      const schemaFilters = parseSchemaList(options.schema);
+      const liveSchema = await introspectPostgresSchema2({
+        query,
+        ...schemaFilters ? { schemas: schemaFilters } : {}
+      });
+      return schemaToState2(liveSchema);
+    }
+  ) : await loadState2(statePath ?? "");
   const diff = await diffSchemas2(previousState, schema);
   if (options.force) {
     forceWarning("Are you sure to use --force? This option will bypass safety checks for destructive operations.");
@@ -2724,9 +3208,72 @@ Remove --safe flag or modify schema to avoid destructive changes.`
   process.exitCode = EXIT_CODES.SUCCESS;
 }
 
-// src/commands/generate.ts
+// src/commands/doctor.ts
 var import_commander2 = require("commander");
 var import_path8 = __toESM(require("path"));
+function resolveConfigPath2(root, targetPath) {
+  return import_path8.default.isAbsolute(targetPath) ? targetPath : import_path8.default.join(root, targetPath);
+}
+function hasDrift(report) {
+  return report.missingTables.length > 0 || report.extraTables.length > 0 || report.columnDifferences.length > 0 || report.typeMismatches.length > 0;
+}
+function printDriftReport(report) {
+  if (report.missingTables.length > 0) {
+    console.log(`Missing tables in live DB: ${report.missingTables.join(", ")}`);
+  }
+  if (report.extraTables.length > 0) {
+    console.log(`Extra tables in live DB: ${report.extraTables.join(", ")}`);
+  }
+  for (const difference of report.columnDifferences) {
+    if (difference.missingInLive.length > 0) {
+      console.log(`Missing columns in ${difference.tableName}: ${difference.missingInLive.join(", ")}`);
+    }
+    if (difference.extraInLive.length > 0) {
+      console.log(`Extra columns in ${difference.tableName}: ${difference.extraInLive.join(", ")}`);
+    }
+  }
+  for (const mismatch of report.typeMismatches) {
+    console.log(`Type mismatch ${mismatch.tableName}.${mismatch.columnName}: ${mismatch.expectedType} -> ${mismatch.actualType}`);
+  }
+}
+async function runDoctor(options = {}) {
+  const root = getProjectRoot();
+  const configPath = getConfigPath(root);
+  if (!await fileExists(configPath)) {
+    throw new Error('SchemaForge project not initialized. Run "schema-forge init" first.');
+  }
+  const config = await readJsonFile(configPath, {});
+  if (!config.stateFile || typeof config.stateFile !== "string") {
+    throw new Error("Invalid config: 'stateFile' is required");
+  }
+  const statePath = resolveConfigPath2(root, config.stateFile);
+  const previousState = await loadState2(statePath);
+  const schemaFilters = parseSchemaList(options.schema);
+  const liveSchema = await withPostgresQueryExecutor(
+    resolvePostgresConnectionString({ url: options.url }),
+    (query) => introspectPostgresSchema2({
+      query,
+      ...schemaFilters ? { schemas: schemaFilters } : {}
+    })
+  );
+  const driftReport = await analyzeSchemaDrift2(previousState, liveSchema);
+  const detected = hasDrift(driftReport);
+  process.exitCode = detected ? EXIT_CODES.DRIFT_DETECTED : EXIT_CODES.SUCCESS;
+  if (options.json) {
+    console.log(JSON.stringify(driftReport, null, 2));
+    return;
+  }
+  if (!detected) {
+    success("No schema drift detected");
+    return;
+  }
+  console.log("Schema drift detected");
+  printDriftReport(driftReport);
+}
+
+// src/commands/generate.ts
+var import_commander3 = require("commander");
+var import_path9 = __toESM(require("path"));
 
 // src/core/utils.ts
 function nowTimestamp2() {
@@ -2739,13 +3286,13 @@ function slugifyName2(name) {
 }
 
 // src/commands/generate.ts
-var REQUIRED_CONFIG_FIELDS2 = [
+var REQUIRED_CONFIG_FIELDS = [
   "schemaFile",
   "stateFile",
   "outputDir"
 ];
-function resolveConfigPath2(root, targetPath) {
-  return import_path8.default.isAbsolute(targetPath) ? targetPath : import_path8.default.join(root, targetPath);
+function resolveConfigPath3(root, targetPath) {
+  return import_path9.default.isAbsolute(targetPath) ? targetPath : import_path9.default.join(root, targetPath);
 }
 async function runGenerate(options) {
   if (options.safe && options.force) {
@@ -2757,15 +3304,15 @@ async function runGenerate(options) {
     throw new Error('SchemaForge project not initialized. Run "schema-forge init" first.');
   }
   const config = await readJsonFile(configPath, {});
-  for (const field of REQUIRED_CONFIG_FIELDS2) {
+  for (const field of REQUIRED_CONFIG_FIELDS) {
     const value = config[field];
     if (!value || typeof value !== "string") {
       throw new Error(`Invalid config: '${field}' is required`);
     }
   }
-  const schemaPath = resolveConfigPath2(root, config.schemaFile);
-  const statePath = resolveConfigPath2(root, config.stateFile);
-  const outputDir = resolveConfigPath2(root, config.outputDir);
+  const schemaPath = resolveConfigPath3(root, config.schemaFile);
+  const statePath = resolveConfigPath3(root, config.stateFile);
+  const outputDir = resolveConfigPath3(root, config.outputDir);
   const { provider, usedDefault } = resolveProvider(config.provider);
   if (usedDefault) {
     info("Provider not set; defaulting to postgres.");
@@ -2826,7 +3373,7 @@ Remove --safe flag or modify schema to avoid destructive changes.`
   const slug = slugifyName2(options.name ?? "migration");
   const fileName = `${timestamp}-${slug}.sql`;
   await ensureDir(outputDir);
-  const migrationPath = import_path8.default.join(outputDir, fileName);
+  const migrationPath = import_path9.default.join(outputDir, fileName);
   await writeTextFile(migrationPath, sql + "\n");
   const nextState = await schemaToState2(schema);
   await saveState2(statePath, nextState);
@@ -2835,14 +3382,14 @@ Remove --safe flag or modify schema to avoid destructive changes.`
 }
 
 // src/commands/import.ts
-var import_commander3 = require("commander");
-var import_path9 = __toESM(require("path"));
-function resolveConfigPath3(root, targetPath) {
-  return import_path9.default.isAbsolute(targetPath) ? targetPath : import_path9.default.join(root, targetPath);
+var import_commander4 = require("commander");
+var import_path10 = __toESM(require("path"));
+function resolveConfigPath4(root, targetPath) {
+  return import_path10.default.isAbsolute(targetPath) ? targetPath : import_path10.default.join(root, targetPath);
 }
 async function runImport(inputPath, options = {}) {
   const root = getProjectRoot();
-  const absoluteInputPath = resolveConfigPath3(root, inputPath);
+  const absoluteInputPath = resolveConfigPath4(root, inputPath);
   const inputs = await loadMigrationSqlInput2(absoluteInputPath);
   if (inputs.length === 0) {
     throw new Error(`No .sql migration files found in: ${absoluteInputPath}`);
@@ -2853,7 +3400,7 @@ async function runImport(inputPath, options = {}) {
     const result = await parseMigrationSql2(input.sql);
     allOps.push(...result.ops);
     parseWarnings.push(...result.warnings.map((item) => ({
-      statement: `[${import_path9.default.basename(input.filePath)}] ${item.statement}`,
+      statement: `[${import_path10.default.basename(input.filePath)}] ${item.statement}`,
       reason: item.reason
     })));
   }
@@ -2869,7 +3416,7 @@ async function runImport(inputPath, options = {}) {
       }
     }
   }
-  const schemaPath = targetPath ? resolveConfigPath3(root, targetPath) : getSchemaFilePath(root);
+  const schemaPath = targetPath ? resolveConfigPath4(root, targetPath) : getSchemaFilePath(root);
   await writeTextFile(schemaPath, dsl);
   success(`Imported ${inputs.length} migration file(s) into ${schemaPath}`);
   info(`Parsed ${allOps.length} supported DDL operation(s)`);
@@ -2887,7 +3434,7 @@ async function runImport(inputPath, options = {}) {
 }
 
 // src/commands/init.ts
-var import_commander4 = require("commander");
+var import_commander5 = require("commander");
 async function runInit() {
   const root = getProjectRoot();
   const schemaForgeDir = getSchemaForgeDir(root);
@@ -2946,28 +3493,61 @@ table users {
   process.exitCode = EXIT_CODES.SUCCESS;
 }
 
+// src/commands/introspect.ts
+var import_commander6 = require("commander");
+var import_path11 = __toESM(require("path"));
+function resolveOutputPath(root, outputPath) {
+  return import_path11.default.isAbsolute(outputPath) ? outputPath : import_path11.default.join(root, outputPath);
+}
+async function runIntrospect(options = {}) {
+  const connectionString = resolvePostgresConnectionString({ url: options.url });
+  const schemas = parseSchemaList(options.schema);
+  const root = getProjectRoot();
+  const schema = await withPostgresQueryExecutor(connectionString, (query) => introspectPostgresSchema2({
+    query,
+    ...schemas ? { schemas } : {}
+  }));
+  const output = JSON.stringify(schema, null, 2);
+  if (!options.json && !options.out) {
+    info(`Introspected ${Object.keys(schema.tables).length} table(s) from PostgreSQL.`);
+  }
+  if (options.out) {
+    const outputPath = resolveOutputPath(root, options.out);
+    await writeTextFile(outputPath, `${output}
+`);
+    success(`Live schema written to ${outputPath}`);
+  }
+  if (options.json || !options.out) {
+    console.log(output);
+  }
+}
+
 // src/commands/validate.ts
-var import_commander5 = require("commander");
-var import_path10 = __toESM(require("path"));
-var REQUIRED_CONFIG_FIELDS3 = ["schemaFile", "stateFile"];
-function resolveConfigPath4(root, targetPath) {
-  return import_path10.default.isAbsolute(targetPath) ? targetPath : import_path10.default.join(root, targetPath);
+var import_commander7 = require("commander");
+var import_path12 = __toESM(require("path"));
+function resolveConfigPath5(root, targetPath) {
+  return import_path12.default.isAbsolute(targetPath) ? targetPath : import_path12.default.join(root, targetPath);
 }
 async function runValidate(options = {}) {
   const root = getProjectRoot();
   const configPath = getConfigPath(root);
+  const useLiveDatabase = Boolean(options.url || process.env.DATABASE_URL);
   if (!await fileExists(configPath)) {
     throw new Error('SchemaForge project not initialized. Run "schema-forge init" first.');
   }
   const config = await readJsonFile(configPath, {});
-  for (const field of REQUIRED_CONFIG_FIELDS3) {
+  const requiredFields = ["schemaFile", "stateFile"];
+  for (const field of requiredFields) {
     const value = config[field];
     if (!value || typeof value !== "string") {
       throw new Error(`Invalid config: '${field}' is required`);
     }
   }
-  const schemaPath = resolveConfigPath4(root, config.schemaFile);
-  const statePath = resolveConfigPath4(root, config.stateFile);
+  const schemaPath = resolveConfigPath5(root, config.schemaFile);
+  if (!config.stateFile) {
+    throw new Error("Invalid config: 'stateFile' is required");
+  }
+  const statePath = resolveConfigPath5(root, config.stateFile);
   const schemaSource = await readTextFile(schemaPath);
   const schema = await parseSchema2(schemaSource);
   try {
@@ -2979,6 +3559,45 @@ async function runValidate(options = {}) {
     throw error2;
   }
   const previousState = await loadState2(statePath);
+  if (useLiveDatabase) {
+    const schemaFilters = parseSchemaList(options.schema);
+    const liveSchema = await withPostgresQueryExecutor(
+      resolvePostgresConnectionString({ url: options.url }),
+      (query) => introspectPostgresSchema2({
+        query,
+        ...schemaFilters ? { schemas: schemaFilters } : {}
+      })
+    );
+    const driftReport = await analyzeSchemaDrift2(previousState, liveSchema);
+    const hasDrift2 = driftReport.missingTables.length > 0 || driftReport.extraTables.length > 0 || driftReport.columnDifferences.length > 0 || driftReport.typeMismatches.length > 0;
+    process.exitCode = hasDrift2 ? EXIT_CODES.DRIFT_DETECTED : EXIT_CODES.SUCCESS;
+    if (options.json) {
+      console.log(JSON.stringify(driftReport, null, 2));
+      return;
+    }
+    if (!hasDrift2) {
+      success("No schema drift detected");
+      return;
+    }
+    if (driftReport.missingTables.length > 0) {
+      console.log(`Missing tables in live DB: ${driftReport.missingTables.join(", ")}`);
+    }
+    if (driftReport.extraTables.length > 0) {
+      console.log(`Extra tables in live DB: ${driftReport.extraTables.join(", ")}`);
+    }
+    for (const difference of driftReport.columnDifferences) {
+      if (difference.missingInLive.length > 0) {
+        console.log(`Missing columns in ${difference.tableName}: ${difference.missingInLive.join(", ")}`);
+      }
+      if (difference.extraInLive.length > 0) {
+        console.log(`Extra columns in ${difference.tableName}: ${difference.extraInLive.join(", ")}`);
+      }
+    }
+    for (const mismatch of driftReport.typeMismatches) {
+      console.log(`Type mismatch ${mismatch.tableName}.${mismatch.columnName}: ${mismatch.expectedType} -> ${mismatch.actualType}`);
+    }
+    return;
+  }
   const findings = await validateSchemaChanges2(previousState, schema);
   const report = await toValidationReport2(findings);
   if (isCI() && hasDestructiveFindings(findings)) {
@@ -3052,7 +3671,7 @@ async function seedLastSeenVersion(version) {
 }
 
 // src/cli.ts
-var program = new import_commander6.Command();
+var program = new import_commander8.Command();
 program.name("schema-forge").description("CLI tool for schema management and SQL generation").version(package_default.version).option("--safe", "Prevent execution of destructive operations").option("--force", "Force execution by bypassing safety checks and CI detection");
 function validateFlagExclusivity(options) {
   if (options.safe && options.force) {
@@ -3088,11 +3707,25 @@ program.command("generate").description("Generate SQL from schema files. In CI e
     await handleError(error2);
   }
 });
-program.command("diff").description("Compare two schema versions and generate migration SQL. In CI environments (CI=true), exits with code 3 if destructive operations are detected unless --force is used.").action(async () => {
+program.command("diff").description("Compare two schema versions and generate migration SQL. In CI environments (CI=true), exits with code 3 if destructive operations are detected unless --force is used.").option("--url <string>", "PostgreSQL connection URL for live diff (defaults to DATABASE_URL)").option("--schema <list>", "Comma-separated schema names to introspect (default: public)").action(async (options) => {
   try {
     const globalOptions = program.opts();
     validateFlagExclusivity(globalOptions);
-    await runDiff(globalOptions);
+    await runDiff({ ...options, ...globalOptions });
+  } catch (error2) {
+    await handleError(error2);
+  }
+});
+program.command("doctor").description("Check live database drift against state. Exits with code 2 when drift is detected.").option("--json", "Output structured JSON").option("--url <string>", "PostgreSQL connection URL (defaults to DATABASE_URL)").option("--schema <list>", "Comma-separated schema names to introspect (default: public)").action(async (options) => {
+  try {
+    await runDoctor(options);
+  } catch (error2) {
+    await handleError(error2);
+  }
+});
+program.command("introspect").description("Extract normalized live schema from PostgreSQL").option("--url <string>", "PostgreSQL connection URL (defaults to DATABASE_URL)").option("--schema <list>", "Comma-separated schema names (default: public)").option("--json", "Output normalized schema JSON to stdout").option("--out <path>", "Write normalized schema JSON to a file").action(async (options) => {
+  try {
+    await runIntrospect(options);
   } catch (error2) {
     await handleError(error2);
   }
@@ -3104,7 +3737,7 @@ program.command("import").description("Import schema from SQL migrations").argum
     await handleError(error2);
   }
 });
-program.command("validate").description("Detect destructive or risky schema changes. In CI environments (CI=true), exits with code 3 if destructive operations are detected.").option("--json", "Output structured JSON").action(async (options) => {
+program.command("validate").description("Detect destructive or risky schema changes. In CI environments (CI=true), exits with code 3 if destructive operations are detected.").option("--json", "Output structured JSON").option("--url <string>", "PostgreSQL connection URL for live drift validation (defaults to DATABASE_URL)").option("--schema <list>", "Comma-separated schema names to introspect (default: public)").action(async (options) => {
   try {
     await runValidate(options);
   } catch (error2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xubylele/schema-forge",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Universal migration generator from schema DSL",
   "main": "dist/cli.js",
   "type": "commonjs",
@@ -11,6 +11,7 @@
     "build": "tsup src/cli.ts --format cjs --dts",
     "dev": "ts-node src/cli.ts",
     "test": "vitest",
+    "test:integration:drift": "vitest run test/drift-realdb.integration.test.ts",
     "prepublishOnly": "npm run build",
     "publish:public": "npm publish --access public",
     "changeset": "changeset",
@@ -42,12 +43,15 @@
   "dependencies": {
     "boxen": "^8.0.1",
     "chalk": "^5.6.2",
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "pg": "^8.19.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
+    "@changesets/cli": "^2.30.0",
     "@types/node": "^25.2.3",
-    "@xubylele/schema-forge-core": "^1.2.0",
+    "@types/pg": "^8.18.0",
+    "@xubylele/schema-forge-core": "^1.3.0",
+    "testcontainers": "^11.8.1",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",