Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prisma/prisma-next/llms.txt

Use this file to discover all available pages before exploring further.

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

​
query.--db
string
Database connection string. Optional when db.connection is set in your config file.
​
query.--config
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts in the current working directory.
​
query.--marker-only
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).
​
query.--schema-only
boolean
Check only the live database schema against the contract. Skip marker verification entirely. Can be combined with --strict.
​
query.--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.
​
query.--json
string
Output a JSON result envelope to stdout.
​
query.-q
boolean
Quiet mode. Suppresses all output except errors.
​
query.-v
boolean
Verbose mode. Prints debug information and timing data.
​
query.-vv
boolean
Trace mode. Prints deep internals and full stack traces.
​
query.--color
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

1

Load contract

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

Connect to database

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

Create family instance

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

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.
5

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...

​
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

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

​
Choosing a verification mode

ModeMarker checkSchema checkWhen to use
Default (no flags)YesYes (tolerant)Standard CI health check
--marker-onlyYesNoFast pre-flight check when schema drift is unlikely or tolerated
--schema-onlyNoYes (tolerant)Brownfield adoption; diagnosing a corrupt or missing marker
--schema-only --strictNoYes (strict)Ensuring no undocumented tables or columns exist
--strict (no --schema-only)YesYes (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.

Build docs developers (and LLMs) love

Get started for freeTalk to us