prisma-next db verify — verify database contract

prisma-next db verify confirms that a database instance is aligned with the emitted contract.json. By default it runs two checks in sequence: it reads the contract marker stored in the database and compares its hashes against the contract, then introspects the live schema to confirm no manual DDL has drifted it away from the contract. Both checks must pass for the command to exit with code 0. You can narrow the scope with --marker-only (skip schema check) or --schema-only (skip marker check), and you can tighten the schema check with --strict to reject schema elements that are present in the database but absent from the contract.

Options

string

Database connection string. Optional when db.connection is set in your config file.

string

Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts in the current working directory.

boolean

Check only the contract marker. Skip schema verification entirely. Cannot be combined with --schema-only or --strict (exits with code 2, PN-CLI-4012).

boolean

Check only the live database schema against the contract. Skip marker verification entirely. Can be combined with --strict.

boolean

When schema verification runs, treat schema elements not present in the contract as failures rather than warnings. Cannot be combined with --marker-only.

string

Output a JSON result envelope to stdout.

boolean

Quiet mode. Suppresses all output except errors.

boolean

Verbose mode. Prints debug information and timing data.

boolean

Trace mode. Prints deep internals and full stack traces.

boolean

Force color output. Use --no-color to disable color output entirely.

Config requirements

db verify requires a driver entry in your config to connect to the database.

prisma-next.config.ts

import { defineConfig } from '@prisma-next/cli/config-types';
import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
import postgresAdapter from '@prisma-next/adapter-postgres/control';
import postgresDriver from '@prisma-next/driver-postgres/control';
import postgres from '@prisma-next/target-postgres/control';
import sql from '@prisma-next/family-sql/control';
import { contract } from './prisma/contract';

export default defineConfig({
  family: sql,
  target: postgres,
  adapter: postgresAdapter,
  driver: postgresDriver,
  extensionPacks: [],
  contract: typescriptContract(contract, 'src/prisma/contract.json'),
  db: {
    connection: process.env.DATABASE_URL,
  },
});

Verification process

Load contract

Reads contract.json from the path specified by config.contract.output.

Connect to database

Creates a driver instance using config.driver.create(url).

Create family instance

Builds a ControlStack via createControlStack() and passes it to config.family.create(stack).

Verify marker (default and --marker-only)

Calls familyInstance.verify() which reads the contract marker from the database and checks:

Marker presence (PN-RUN-3001 if missing).
Target compatibility (PN-RUN-3003 if the contract target does not match config.target).
storageHash match (PN-RUN-3002 if hashes differ).
profileHash match (PN-RUN-3002 if hashes differ, when present).
Codec coverage (reports missing codecs when contract column types are not covered).

Skipped when --schema-only is provided.

Verify schema (default and --schema-only)

Calls familyInstance.schemaVerify() to introspect the live schema and compare it against the contract. In default (tolerant) mode, extra schema elements are allowed. With --strict, extra elements are treated as failures.Skipped when --marker-only is provided.

Output formats

✔ Database marker and schema match contract
  verification: marker + schema
  storageHash: sha256:abc123...
  profileHash: sha256:def456...

✔ Database marker matches contract
  verification: marker only (--marker-only)
  storageHash: sha256:abc123...
  profileHash: sha256:def456...

⚠ Schema verification skipped because --marker-only was provided

✖ Marker missing (PN-RUN-3001)
  Why: Contract marker not found in database
  Fix: Run `prisma-next db sign --db <url>` to create marker

✖ Schema verification failed
  [Schema verification tree with failing nodes]

JSON output

Full success (--json)

{
  "ok": true,
  "summary": "Database marker and schema match contract",
  "mode": "full",
  "contract": {
    "storageHash": "sha256:abc123...",
    "profileHash": "sha256:def456..."
  },
  "marker": {
    "storageHash": "sha256:abc123...",
    "profileHash": "sha256:def456..."
  },
  "target": {
    "expected": "postgres"
  },
  "missingCodecs": [],
  "schema": {
    "summary": "Database schema satisfies contract",
    "counts": {
      "pass": 12,
      "warn": 0,
      "fail": 0,
      "totalNodes": 12
    },
    "strict": false
  },
  "meta": {
    "configPath": "/path/to/prisma-next.config.ts",
    "contractPath": "/path/to/src/prisma/contract.json",
    "schemaVerification": "performed"
  },
  "timings": {
    "total": 42
  }
}

Error codes

Code	Meaning
`PN-CLI-4010`	Missing driver in config. Add a driver descriptor to your config.
`PN-CLI-4012`	Invalid flag combination. `--marker-only` cannot be combined with `--schema-only` or `--strict`.
`PN-RUN-3001`	Marker missing. The contract marker was not found in the database.
`PN-RUN-3002`	Hash mismatch. The stored marker hash does not match the contract.
`PN-RUN-3003`	Target mismatch. The contract target does not match the configured target.
Exit code 1	Schema verification failed (default mode or `--schema-only`).

Choosing a verification mode

Mode	Marker check	Schema check	When to use
Default (no flags)	Yes	Yes (tolerant)	Standard CI health check
`--marker-only`	Yes	No	Fast pre-flight check when schema drift is unlikely or tolerated
`--schema-only`	No	Yes (tolerant)	Brownfield adoption; diagnosing a corrupt or missing marker
`--schema-only --strict`	No	Yes (strict)	Ensuring no undocumented tables or columns exist
`--strict` (no `--schema-only`)	Yes	Yes (strict)	Full contract compliance including no extra schema elements

--marker-only accepts the trade-off that schema drift since the last signing will go undetected. Use it only when you control both the schema and the signing workflow, and you want to minimize verification overhead.

Relationship to db sign

db verify reads the marker that db sign writes. If db verify reports PN-RUN-3001 (marker missing), run db sign to create the marker. If it reports PN-RUN-3002 (hash mismatch), re-sign the database after ensuring the schema matches the contract.

Overview

Contract Commands

Database Commands

Migration Commands

prisma-next db verify — verify database contract

Options

Config requirements

Verification process

Output formats

JSON output

Error codes

Choosing a verification mode

Relationship to db sign

​Options

​Config requirements

​Verification process

​Output formats

​JSON output

​Error codes

​Choosing a verification mode

​Relationship to db sign

Options

Config requirements

Verification process

Output formats

JSON output

Error codes

Choosing a verification mode

Relationship to db sign