fix(planner): emit executable DDL for NOT NULL columns on non-empty tables

docs/architecture docs/subsystems/7. Migration System.md

@@ -298,6 +298,16 @@ For CLI usage, output formats, and common failure modes, see the canonical comma
 
 Greenfield, brownfield-conservative, and brownfield-incremental paths are supported. Baselines help bootstrap fresh environments; incremental adoption expands contract coverage safely over time. See [ADR 122 — Database Initialization & Adoption](../adrs/ADR%20122%20-%20Database%20Initialization%20&%20Adoption.md).
 
+### `db update` (live reconciliation)
+
+`prisma-next db update` is the **reconciliation** entrypoint. It introspects the live database schema, diffs it against the destination contract, and applies the resulting operations.
+
+Unlike `migration apply`, which replays serialized edges, `db update` always works from a live introspection. Plans produced by the planner carry `origin: null` (no prior-state assertion). The runner treats this as "trust the planner": operations are always applied regardless of marker state. This ensures `db update` can recover from schema drift — for example, when a DBA manually drops a column, the planner detects the missing column and re-adds it even though the contract marker already matches the destination hash.
+
+By contrast, `migration apply` constructs plans with `origin: { storageHash }` from the migration chain. When the marker matches the destination, the runner skips operations (the migration was already applied). This provides safe idempotent replays.
+
+**NOT NULL columns without defaults.** When adding a NOT NULL column to a potentially non-empty table, the planner uses a temporary type-appropriate zero default (`''` for text, `0` for integers, `false` for booleans, etc.) so existing rows receive a value. The temporary default is dropped immediately after the column is added. Existing rows permanently retain the zero value; future inserts must provide an explicit value.
+
 ## Multi-Service Namespacing
 
 Per-service markers allow independent contracts within a single physical database (e.g., Postgres schemas). Each service has its own `prisma_contract.marker`; permissions and verification remain isolated. For engines without schemas, use separate databases. See namespacing notes in [ADR 021 — Contract Marker Storage](../adrs/ADR%20021%20-%20Contract%20Marker%20Storage.md).

packages/3-targets/3-targets/postgres/src/core/migrations/planner.ts

@@ -346,16 +346,21 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
     const qualified = qualifyTableName(schema, tableName);
     const notNull = column.nullable === false;
     const hasDefault = column.default !== undefined;
-    // Only require empty table for NOT NULL columns WITHOUT defaults.
-    // PostgreSQL allows adding NOT NULL columns with defaults to non-empty tables
-    // because the default value is applied to existing rows.
-    const requiresEmptyTable = notNull && !hasDefault;
+    // For NOT NULL columns without an explicit default, use a temporary type-appropriate
+    // zero default so PostgreSQL can add the column to non-empty tables. The temporary
+    // default is dropped immediately after the column is added, leaving the column as
+    // NOT NULL with no default (matching the contract intent).
+    const needsTemporaryDefault = notNull && !hasDefault;
+    const temporaryDefault = needsTemporaryDefault
+      ? buildTypeZeroDefaultLiteral(column.nativeType)
+      : null;
+    const requiresEmptyTableCheck = needsTemporaryDefault && temporaryDefault === null;
     const precheck = [
       {
         description: `ensure column "${columnName}" is missing`,
         sql: columnExistsCheck({ schema, table: tableName, column: columnName, exists: false }),
       },
-      ...(requiresEmptyTable
+      ...(requiresEmptyTableCheck
         ? [
             {
               description: `ensure table "${tableName}" is empty before adding NOT NULL column without default`,
@@ -367,8 +372,17 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
     const execute = [
       {
         description: `add column "${columnName}"`,
-        sql: buildAddColumnSql(qualified, columnName, column, codecHooks),
+        sql: buildAddColumnSql(qualified, columnName, column, codecHooks, temporaryDefault),
       },
+      // Drop the temporary default so future inserts must provide an explicit value.
+      ...(temporaryDefault
+        ? [
+            {
+              description: `drop temporary default from column "${columnName}"`,
+              sql: `ALTER TABLE ${qualified} ALTER COLUMN ${quoteIdentifier(columnName)} DROP DEFAULT`,
+            },
+          ]
+        : []),
     ];
     const postcheck = [
       {
@@ -388,6 +402,14 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
             },
           ]
         : []),
+      ...(temporaryDefault
+        ? [
+            {
+              description: `verify column "${columnName}" has no default after temporary default removal`,
+              sql: columnHasNoDefaultCheck({ schema, table: tableName, column: columnName }),
+            },
+          ]
+        : []),
     ];
 
     return {
@@ -980,14 +1002,106 @@ function tableIsEmptyCheck(qualifiedTableName: string): string {
   return `SELECT NOT EXISTS (SELECT 1 FROM ${qualifiedTableName} LIMIT 1)`;
 }
 
+function columnHasNoDefaultCheck(opts: { schema: string; table: string; column: string }): string {
+  return `SELECT NOT EXISTS (
+  SELECT 1
+  FROM information_schema.columns
+  WHERE table_schema = '${escapeLiteral(opts.schema)}'
+    AND table_name = '${escapeLiteral(opts.table)}'
+    AND column_name = '${escapeLiteral(opts.column)}'
+    AND column_default IS NOT NULL
+)`;
+}
+
+/**
+ * Returns a type-appropriate zero-value SQL literal for the given PostgreSQL native type.
+ * Used as a temporary DEFAULT when adding a NOT NULL column without an explicit default
+ * to a potentially non-empty table. Existing rows permanently receive this zero value.
+ *
+ * Returns null for unrecognized types (e.g. enums, arrays, extensions), which causes
+ * the planner to fall back to the empty-table precheck.
+ *
+ * @internal Exported for testing only.
+ */
+export function buildTypeZeroDefaultLiteral(nativeType: string): string | null {
+  switch (nativeType.toLowerCase()) {
+    // String types
+    case 'text':
+    case 'character':
+    case 'character varying':
+      return "''";
+
+    // Numeric types (integer, float, decimal)
+    case 'int2':
+    case 'int4':
+    case 'int8':
+    case 'integer':
+    case 'bigint':
+    case 'smallint':
+    case 'float4':
+    case 'float8':
+    case 'real':
+    case 'double precision':
+    case 'numeric':
+    case 'decimal':
+      return '0';
+
+    // Boolean
+    case 'bool':
+    case 'boolean':
+      return 'false';
+
+    // UUID
+    case 'uuid':
+      return "'00000000-0000-0000-0000-000000000000'";
+
+    // JSON types — use empty object rather than JSON null to avoid
+    // ambiguity with JS null when drivers deserialize the value.
+    case 'json':
+    case 'jsonb':
+      return "'{}'::jsonb";
+
+    // Date and timestamp types
+    case 'date':
+    case 'timestamp':
+    case 'timestamptz':
+    case 'timestamp with time zone':
+    case 'timestamp without time zone':
+      return "'epoch'";
+
+    // Time types
+    case 'time':
+    case 'timetz':
+    case 'time with time zone':
+    case 'time without time zone':
+      return "'00:00:00'";
+
+    // Interval
+    case 'interval':
+      return "'0'";
+
+    // Bit types
+    case 'bit':
+      return "B'0'";
+    case 'bit varying':
+      return "B''";
+
+    default:
+      return null;
+  }
+}
+
 function buildAddColumnSql(
   qualifiedTableName: string,
   columnName: string,
   column: StorageColumn,
   codecHooks: Map<string, CodecControlHooks>,
+  temporaryDefault?: string | null,
 ): string {
   const typeSql = buildColumnTypeSql(column, codecHooks);
-  const defaultSql = buildColumnDefaultSql(column.default, column);
+  const defaultSql =
+    buildColumnDefaultSql(column.default, column) ||
+    (temporaryDefault ? `DEFAULT ${temporaryDefault}` : '');
   const parts = [
     `ALTER TABLE ${qualifiedTableName}`,
     `ADD COLUMN ${quoteIdentifier(columnName)} ${typeSql}`,

packages/3-targets/3-targets/postgres/src/core/migrations/runner.ts

@@ -117,11 +117,12 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
         return markerCheck;
       }
 
-      // Apply plan operations or skip if marker already at destination
+      // db update (origin: null) always applies; migration-apply (origin set) skips if marker matches.
       const markerAtDestination = this.markerMatchesDestination(existingMarker, options.plan);
+      const skipOperations = markerAtDestination && options.plan.origin != null;
       let applyValue: ApplyPlanSuccessValue;
 
-      if (markerAtDestination) {
+      if (skipOperations) {
         applyValue = { operationsExecuted: 0, executedOperations: [] };
       } else {
         const applyResult = await this.applyPlan(driver, options);

packages/3-targets/3-targets/postgres/test/migrations/planner.behavior.test.ts

@@ -1,9 +1,13 @@
+import type { ColumnDefaultLiteralInputValue } from '@prisma-next/contract/types';
 import { coreHash, profileHash } from '@prisma-next/contract/types';
 import { INIT_ADDITIVE_POLICY } from '@prisma-next/family-sql/control';
 import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import { describe, expect, it } from 'vitest';
-import { createPostgresMigrationPlanner } from '../../src/core/migrations/planner';
+import {
+  buildTypeZeroDefaultLiteral,
+  createPostgresMigrationPlanner,
+} from '../../src/core/migrations/planner';
 
 describe('PostgresMigrationPlanner - subset/superset/conflict handling', () => {
   const planner = createPostgresMigrationPlanner();
@@ -119,6 +123,112 @@ describe('PostgresMigrationPlanner - subset/superset/conflict handling', () => {
   });
 });
 
+describe('NOT NULL column without default uses temporary default', () => {
+  it('emits 2-step execute (add with temp default, drop default) for NOT NULL text column', () => {
+    const addCol = planAddColumn('name', {
+      nativeType: 'text',
+      codecId: 'pg/text@1',
+      nullable: false,
+    });
+
+    // No empty-table precheck
+    expect(addCol.precheck.map((p) => p.description)).not.toContainEqual(
+      expect.stringContaining('empty'),
+    );
+
+    // 2-step execute: add with temporary default, then drop default
+    expect(addCol.execute).toHaveLength(2);
+    expect(addCol.execute[0]!.sql).toContain("DEFAULT ''");
+    expect(addCol.execute[0]!.sql).toContain('NOT NULL');
+    expect(addCol.execute[1]!.sql).toContain('DROP DEFAULT');
+
+    // Postcheck includes verification that temporary default was removed
+    expect(addCol.postcheck.map((p) => p.description)).toContainEqual(
+      expect.stringContaining('no default'),
+    );
+  });
+
+  it('emits 2-step execute for NOT NULL int4 column', () => {
+    const addCol = planAddColumn('age', {
+      nativeType: 'int4',
+      codecId: 'pg/int4@1',
+      nullable: false,
+    });
+
+    expect(addCol.execute).toHaveLength(2);
+    expect(addCol.execute[0]!.sql).toContain('DEFAULT 0');
+    expect(addCol.execute[0]!.sql).toContain('NOT NULL');
+    expect(addCol.execute[1]!.sql).toContain('DROP DEFAULT');
+  });
+
+  it('skips temporary default for nullable columns', () => {
+    const addCol = planAddColumn('bio', {
+      nativeType: 'text',
+      codecId: 'pg/text@1',
+      nullable: true,
+    });
+
+    expect(addCol.execute).toHaveLength(1);
+    expect(addCol.execute[0]!.sql).not.toContain('DEFAULT');
+    expect(addCol.execute[0]!.sql).not.toContain('NOT NULL');
+  });
+
+  it('skips temporary default for NOT NULL columns with explicit default', () => {
+    const addCol = planAddColumn('active', {
+      nativeType: 'bool',
+      codecId: 'pg/bool@1',
+      nullable: false,
+      default: { kind: 'literal', value: true },
+    });
+
+    // Single execute step (explicit default, no temporary default needed)
+    expect(addCol.execute).toHaveLength(1);
+    expect(addCol.execute[0]!.sql).toContain('DEFAULT true');
+    expect(addCol.execute[0]!.sql).toContain('NOT NULL');
+  });
+});
+
+describe('buildTypeZeroDefaultLiteral', () => {
+  it.each([
+    ['text', "''"],
+    ['character', "''"],
+    ['character varying', "''"],
+    ['int2', '0'],
+    ['int4', '0'],
+    ['int8', '0'],
+    ['integer', '0'],
+    ['bigint', '0'],
+    ['smallint', '0'],
+    ['float4', '0'],
+    ['float8', '0'],
+    ['real', '0'],
+    ['double precision', '0'],
+    ['numeric', '0'],
+    ['decimal', '0'],
+    ['bool', 'false'],
+    ['boolean', 'false'],
+    ['uuid', "'00000000-0000-0000-0000-000000000000'"],
+    ['json', "'{}'::jsonb"],
+    ['jsonb', "'{}'::jsonb"],
+    ['date', "'epoch'"],
+    ['timestamp', "'epoch'"],
+    ['timestamptz', "'epoch'"],
+    ['time', "'00:00:00'"],
+    ['timetz', "'00:00:00'"],
+    ['interval', "'0'"],
+    ['bit', "B'0'"],
+    ['bit varying', "B''"],
+  ] as const)('returns %s → %s', (nativeType, expected) => {
+    expect(buildTypeZeroDefaultLiteral(nativeType)).toBe(expected);
+  });
+
+  it('returns null for unknown types (enum, array, extension)', () => {
+    expect(buildTypeZeroDefaultLiteral('my_enum')).toBeNull();
+    expect(buildTypeZeroDefaultLiteral('int4[]')).toBeNull();
+    expect(buildTypeZeroDefaultLiteral('tsvector')).toBeNull();
+  });
+});
+
 function createTestContract(overrides?: Partial<SqlContract<SqlStorage>>): SqlContract<SqlStorage> {
   return {
     schemaVersion: '1',
@@ -183,6 +293,61 @@ function buildUserTableSchema(): SqlSchemaIR['tables'][string] {
   };
 }
 
+/**
+ * Plans adding a single column to the user table and returns the resulting operation.
+ * The schema contains only the `id` column, so the planner generates an ADD COLUMN for `columnName`.
+ */
+function planAddColumn(
+  columnName: string,
+  columnDef: {
+    nativeType: string;
+    codecId: string;
+    nullable: boolean;
+    default?: { kind: 'literal'; value: ColumnDefaultLiteralInputValue };
+  },
+) {
+  const planner = createPostgresMigrationPlanner();
+  const contract = createTestContract({
+    storage: {
+      tables: {
+        user: {
+          columns: {
+            id: { nativeType: 'uuid', codecId: 'pg/uuid@1', nullable: false },
+            [columnName]: columnDef,
+          },
+          primaryKey: { columns: ['id'] },
+          uniques: [],
+          indexes: [],
+          foreignKeys: [],
+        },
+      },
+    },
+  });
+  const schema: SqlSchemaIR = {
+    tables: {
+      user: {
+        name: 'user',
+        columns: { id: { name: 'id', nativeType: 'uuid', nullable: false } },
+        primaryKey: { columns: ['id'] },
+        uniques: [],
+        foreignKeys: [],
+        indexes: [],
+      },
+    },
+    dependencies: [],
+  };
+  const result = planner.plan({
+    contract,
+    schema,
+    policy: INIT_ADDITIVE_POLICY,
+    frameworkComponents: [],
+  });
+  if (result.kind !== 'success') throw new Error('expected planner success');
+  const op = result.plan.operations.find((o) => o.id === `column.user.${columnName}`);
+  if (!op) throw new Error(`operation column.user.${columnName} not found`);
+  return op;
+}
+
 function buildPostTableSchema(): SqlSchemaIR['tables'][string] {
   return {
     name: 'post',