test(native-enums): prove managed enum add-value CRUD against a real Postgres server

The existing add-value coverage runs on PGlite and only checks catalogs.
This adds an integration test against a genuine PostgreSQL server: it applies
`ALTER TYPE … ADD VALUE`, then in separate committed statements INSERTs a row
using the new value, SELECTs it back, UPDATEs another row to it, and DELETEs —
proving the appended value is usable for CRUD, which PGlite's single-connection
model cannot fully stand in for.

Isolated in a throwaway database created and dropped on a maintenance
connection, so it never touches existing data. Availability-gated
(`describe.runIf`) so a bare checkout skips instead of failing; it connects to
`localhost:5432`, matching the `postgres:15` service the CI test jobs already
provision (previously unused), so it runs for real in CI with no new workflow
config.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden-electric

packages/3-targets/6-adapters/postgres/test/migrations/native-enum-add-value.real-postgres.integration.test.ts

@@ -0,0 +1,328 @@
+/**
+ * Managed native-enum add-value migration against a REAL PostgreSQL server
+ * (not PGlite): plans and applies `ALTER TYPE … ADD VALUE`, then proves the
+ * newly-added value is usable for CRUD in separate, subsequent statements —
+ * the whole point of committing the ALTER on a real server (PGlite tests
+ * cover planning/apply-ordering but can't prove this cross-transaction
+ * usability).
+ *
+ * Isolated in a throwaway database (`prisma_next_native_enum_add_value_realdb`)
+ * dropped and recreated on a maintenance connection; skips (does not fail)
+ * when no real Postgres is reachable.
+ */
+import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
+import { INIT_ADDITIVE_POLICY } from '@prisma-next/family-sql/control';
+import {
+  APP_SPACE_ID,
+  assembleAuthoringContributions,
+  type MigrationOperationPolicy,
+} from '@prisma-next/framework-components/control';
+import { buildSymbolTable } from '@prisma-next/psl-parser';
+import { parse } from '@prisma-next/psl-parser/syntax';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { interpretPslDocumentToSqlContract } from '@prisma-next/sql-contract-psl';
+import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import {
+  PostgresDatabaseSchemaNode,
+  postgresCreateNamespace,
+} from '@prisma-next/target-postgres/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createPostgresBuiltinCodecLookup } from '../../src/core/codec-lookup';
+import { createPostgresScalarTypeDescriptors } from '../../src/core/control-mutation-defaults';
+import {
+  controlAdapter,
+  createDriver,
+  emptySchema,
+  familyInstance,
+  formatRunnerFailure,
+  frameworkComponents,
+  type PostgresControlDriver,
+  postgresTargetDescriptor,
+  synthEdges,
+  testTimeout,
+} from './fixtures/runner-fixtures';
+
+// ============================================================================
+// PSL sources
+// ============================================================================
+
+const PSL_ENUM_TWO_MEMBERS = `
+namespace public {
+  native_enum OrderStatus {
+    draft  = "draft"
+    review = "review"
+    @@map("order_status")
+  }
+
+  model orders {
+    id     Int @id
+    status pg.enum(OrderStatus)
+  }
+}
+`;
+
+const PSL_WITH_ENUM = `
+namespace public {
+  native_enum OrderStatus {
+    draft  = "draft"
+    review = "review"
+    done   = "done"
+    @@map("order_status")
+  }
+
+  model orders {
+    id     Int @id
+    status pg.enum(OrderStatus)
+  }
+}
+`;
+
+// ============================================================================
+// PSL → contract helpers (mirrors native-enum-lifecycle-e2e.integration.test.ts)
+// ============================================================================
+
+function buildScalarTypeDescriptors(): ReadonlyMap<
+  string,
+  { codecId: string; nativeType: string }
+> {
+  const codecIdMap = createPostgresScalarTypeDescriptors();
+  const codecLookup = createPostgresBuiltinCodecLookup();
+  const result = new Map<string, { codecId: string; nativeType: string }>();
+  for (const [typeName, codecId] of codecIdMap) {
+    const nativeType = codecLookup.targetTypesFor(codecId)?.[0];
+    if (nativeType !== undefined) {
+      result.set(typeName, { codecId, nativeType });
+    }
+  }
+  return result;
+}
+
+function buildContractFromPsl(psl: string, control: ControlPolicy): Contract<SqlStorage> {
+  const assembled = assembleAuthoringContributions([postgresTargetDescriptor]);
+  const scalarTypeDescriptors = buildScalarTypeDescriptors();
+
+  const { document, sourceFile } = parse(psl);
+  const { table: symbolTable } = buildSymbolTable({
+    document,
+    sourceFile,
+    scalarTypes: [...scalarTypeDescriptors.keys()],
+    pslBlockDescriptors: assembled.pslBlockDescriptors,
+  });
+
+  const result = interpretPslDocumentToSqlContract({
+    symbolTable,
+    sourceFile,
+    sourceId: 'schema.prisma',
+    target: {
+      kind: 'target' as const,
+      familyId: 'sql' as const,
+      targetId: 'postgres' as const,
+      id: 'postgres',
+      version: postgresTargetDescriptor.version,
+      capabilities: {},
+      defaultNamespaceId: 'public',
+      ...ifDefined('authoring', postgresTargetDescriptor.authoring),
+    },
+    scalarTypeDescriptors,
+    authoringContributions: assembled,
+    composedExtensionContracts: new Map(),
+    createNamespace: postgresCreateNamespace,
+    codecLookup: createPostgresBuiltinCodecLookup(),
+    capabilities: { sql: { scalarList: true } },
+  });
+
+  if (!result.ok) throw new Error(`PSL interpretation failed: ${JSON.stringify(result)}`);
+  return { ...(result.value as Contract<SqlStorage>), defaultControlPolicy: control };
+}
+
+async function planContract(
+  contract: Contract<SqlStorage>,
+  schema: SqlSchemaIRNode,
+  policy: MigrationOperationPolicy,
+) {
+  const planner = postgresTargetDescriptor.createPlanner(controlAdapter);
+  const planResult = planner.plan({
+    contract,
+    schema,
+    policy,
+    fromContract: null,
+    frameworkComponents,
+    spaceId: APP_SPACE_ID,
+  });
+  if (planResult.kind !== 'success')
+    throw new Error(`Planner failed: ${JSON.stringify(planResult)}`);
+  return planResult.plan;
+}
+
+async function applyPlan(
+  driver: PostgresControlDriver,
+  plan: Awaited<ReturnType<typeof planContract>>,
+  contract: Contract<SqlStorage>,
+  policy: MigrationOperationPolicy,
+): Promise<void> {
+  const runner = postgresTargetDescriptor.createRunner(familyInstance);
+  const executeResult = await runner.execute({
+    driver,
+    perSpaceOptions: [
+      {
+        space: plan.spaceId ?? APP_SPACE_ID,
+        plan,
+        migrationEdges: synthEdges(plan),
+        driver,
+        destinationContract: contract,
+        policy,
+        frameworkComponents,
+      },
+    ],
+  });
+  if (!executeResult.ok)
+    throw new Error(`Runner failed:\n${formatRunnerFailure(executeResult.failure)}`);
+}
+
+async function opIds(plan: Awaited<ReturnType<typeof planContract>>): Promise<readonly string[]> {
+  const ops = await Promise.all(plan.operations);
+  return ops.map((op) => op.id);
+}
+
+/** The ordered member list of a native enum type in a namespace of an introspected/live schema tree, or `undefined` when the namespace or type is absent. */
+function nativeEnumMembers(
+  schema: SqlSchemaIRNode,
+  namespaceId: string,
+  typeName: string,
+): readonly string[] | undefined {
+  PostgresDatabaseSchemaNode.assert(schema);
+  return schema.namespaces[namespaceId]?.nativeEnums.find((e) => e.typeName === typeName)?.members;
+}
+
+// ============================================================================
+// Real-DB connection + isolation
+// ============================================================================
+
+const MAINTENANCE_URL =
+  process.env['DATABASE_URL'] ?? 'postgres://postgres:postgres@localhost:5432/postgres';
+const TEST_DB = 'prisma_next_native_enum_add_value_realdb';
+
+function testDatabaseUrl(): string {
+  const u = new URL(MAINTENANCE_URL);
+  u.pathname = '/' + TEST_DB;
+  return u.toString();
+}
+
+async function isRealPostgresAvailable(): Promise<boolean> {
+  try {
+    const d = await createDriver(MAINTENANCE_URL);
+    await d.query('select 1');
+    await d.close();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function dropTestDatabaseViaMaintenance(): Promise<void> {
+  const maintenance = await createDriver(MAINTENANCE_URL);
+  await maintenance.query(`DROP DATABASE IF EXISTS ${TEST_DB} WITH (FORCE)`);
+  await maintenance.close();
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe.runIf(await isRealPostgresAvailable())(
+  'managed native-enum add-value — real Postgres CRUD (R8)',
+  () => {
+    let driver: PostgresControlDriver | undefined;
+
+    beforeAll(async () => {
+      const maintenance = await createDriver(MAINTENANCE_URL);
+      await maintenance.query(`DROP DATABASE IF EXISTS ${TEST_DB} WITH (FORCE)`);
+      await maintenance.query(`CREATE DATABASE ${TEST_DB}`);
+      await maintenance.close();
+
+      driver = await createDriver(testDatabaseUrl());
+    }, testTimeout);
+
+    afterAll(async () => {
+      await driver?.close();
+      await dropTestDatabaseViaMaintenance();
+    }, testTimeout);
+
+    it(
+      'appends a member via ALTER TYPE ADD VALUE and the new value is usable for CRUD on a real server',
+      async () => {
+        // 1. Plan + apply the 2-member baseline from empty.
+        const baseContract = buildContractFromPsl(PSL_ENUM_TWO_MEMBERS, 'managed');
+        const basePlan = await planContract(baseContract, emptySchema, INIT_ADDITIVE_POLICY);
+        await applyPlan(driver!, basePlan, baseContract, INIT_ADDITIVE_POLICY);
+
+        // 2. Introspect, plan the append to 3 members, apply it.
+        const introspectedBase = await familyInstance.introspect({
+          driver: driver!,
+          contract: baseContract,
+        });
+        const appendedContract = buildContractFromPsl(PSL_WITH_ENUM, 'managed');
+        const appendPlan = await planContract(
+          appendedContract,
+          introspectedBase,
+          INIT_ADDITIVE_POLICY,
+        );
+        const ids = await opIds(appendPlan);
+        expect(ids).toEqual(['addNativeEnumValue.order_status.done']);
+        await applyPlan(driver!, appendPlan, appendedContract, INIT_ADDITIVE_POLICY);
+
+        // 3. The new member is live.
+        const introspectedAfter = await familyInstance.introspect({
+          driver: driver!,
+          contract: appendedContract,
+        });
+        expect(nativeEnumMembers(introspectedAfter, 'public', 'order_status')).toEqual([
+          'draft',
+          'review',
+          'done',
+        ]);
+
+        // 4. CRUD using the newly-added 'done' value, in separate statements
+        // (the whole point of a real, committed ALTER TYPE ADD VALUE).
+        await driver!.query('INSERT INTO "public"."orders" (id, status) VALUES ($1, $2)', [
+          1,
+          'done',
+        ]);
+        const createdRow = await driver!.query<{ status: string }>(
+          'SELECT status FROM "public"."orders" WHERE id = $1',
+          [1],
+        );
+        expect(createdRow.rows[0]?.status).toBe('done');
+
+        await driver!.query('INSERT INTO "public"."orders" (id, status) VALUES ($1, $2)', [
+          2,
+          'draft',
+        ]);
+        await driver!.query('UPDATE "public"."orders" SET status = $1 WHERE id = $2', ['done', 2]);
+        const updatedRow = await driver!.query<{ status: string }>(
+          'SELECT status FROM "public"."orders" WHERE id = $1',
+          [2],
+        );
+        expect(updatedRow.rows[0]?.status).toBe('done');
+
+        await driver!.query('DELETE FROM "public"."orders" WHERE id = $1', [2]);
+        const remaining = await driver!.query<{ count: string }>(
+          'SELECT count(*)::text AS count FROM "public"."orders" WHERE id = $1',
+          [2],
+        );
+        expect(remaining.rows[0]?.count).toBe('0');
+
+        // 5. Verify is clean against the appended contract.
+        const verify = familyInstance.verifySchema({
+          contract: appendedContract,
+          schema: introspectedAfter,
+          strict: true,
+          frameworkComponents,
+        });
+        expect(verify.ok).toBe(true);
+      },
+      testTimeout,
+    );
+  },
+);

projects/native-postgres-enums/slices/managed-native-enum-add-value/code-review.md

@@ -27,4 +27,6 @@
 - R9 rename / removal / reorder → each `planDirect` returns `failure` carrying the exact operator-worded refusal (verbatim `orderStatusRefusalMessage`), zero ops, and the live member list is unchanged after the attempt (DB untouched).
 - R5 external enum carrying a live-appended fourth value → zero `addNativeEnumValue` / `createNativeEnumType` / `dropNativeEnumType` ops under the external grade; the extra live value is left in place.
 
+**Verified live (real PostgreSQL), in `native-enum-add-value.real-postgres.integration.test.ts`:** against a genuine Postgres server (throwaway database created/dropped on a maintenance connection, availability-gated so a bare checkout skips, and matching the `postgres:15` service CI already provisions on `localhost:5432`), the append applies and the new value is usable for CRUD in statements after the migration commits — INSERT `'done'` → SELECT; INSERT `'draft'` → UPDATE to `'done'` → SELECT; DELETE — plus strict verify clean. This is the cross-transaction usability PGlite's single-connection model can't fully stand in for.
+
 **Enums-only namespace pulled from scope (Option A):** whether a model-less, enums-only namespace reaches verify/plan is an authoring-surface limitation (`buildSqlContractFromDefinition` derives a namespace's existence from its models), not a planner one — moved to the generic contract-builder follow-up slice. D2's `pruneTableLessNamespaces` widening and its enums-only tests were reverted; Slice A's prune stands unchanged. Reviewer focus for this dispatch is carried by D1 above (the `additive` op-class grading and the `qualifiedNativeEnumTypeName` unbound path).

projects/native-postgres-enums/slices/managed-native-enum-add-value/spec.md

@@ -46,7 +46,7 @@ One reviewer sitting: a planner-lowering change confined to one function's tail,
 
 ## Scope
 
-**In:** the suffix-append classification + `AddNativeEnumValueCall` lowering; the plain-language refusal diagnostic with the `pris.ly` link; the `docs/reference/postgres-native-enums.md` page (content from the project explainer, `projects/` copy becomes a pointer); the op class with prechecks/postchecks + caveat-bearing description; the hand-authored `addNativeEnumValue`; unit + planner tests; a live PGlite integration proof (single + multi append, all three refusal classes, external append suppressed).
+**In:** the suffix-append classification + `AddNativeEnumValueCall` lowering; the plain-language refusal diagnostic with the `pris.ly` link; the `docs/reference/postgres-native-enums.md` page (content from the project explainer, `projects/` copy becomes a pointer); the op class with prechecks/postchecks + caveat-bearing description; the hand-authored `addNativeEnumValue`; unit + planner tests; a live PGlite integration proof (single + multi append, all three refusal classes, external append suppressed); a **real-PostgreSQL** integration proof that the appended value round-trips CRUD (throwaway-database isolated, availability-gated, wired to the Postgres service CI already provisions).
 
 **Deliberately out:**
 
@@ -67,7 +67,7 @@ One reviewer sitting: a planner-lowering change confined to one function's tail,
 
 ## Slice-specific done conditions
 
-R8 and R9 proven against a live database (PGlite): the append path applies and round-trips verify; each refusal class (rename, removal, reorder) yields the diagnostic and zero ops. Plan output shows the caveat on the `ADD VALUE` op description. (CI-green, reviewer-accept, project-DoD floor inherited.)
+R8 and R9 proven against a live database: the append path applies and round-trips verify, and each refusal class (rename, removal, reorder) yields the diagnostic and zero ops (PGlite). Additionally, against a **real PostgreSQL server** (throwaway database, skipped when none is reachable), the appended value is usable for CRUD — INSERT / SELECT / UPDATE / DELETE in statements after the migration commits — which PGlite's single-connection model cannot fully stand in for. Plan output shows the caveat on the `ADD VALUE` op description. (CI-green, reviewer-accept, project-DoD floor inherited.)
 
 ## Open questions