prisma-next db sign — write contract marker

prisma-next db sign stamps a database with a contract marker — a lightweight record stored inside the database that encodes the storageHash and profileHash of the emitted contract. The marker is what db verify reads when it checks whether a database is up to date. Signing is a precondition for using db verify --marker-only, and is automatically performed by db init and migration apply at the end of a successful run. Before writing the marker, db sign always runs a full schema verification pass. If the live database schema does not satisfy the contract, the command exits with code 1 and prints the schema verification tree — the marker is never written in a failure case. This guarantees that a signed database is always one that genuinely matches 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.

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 sign requires both a driver entry (to connect to the database) and a contract entry pointing to the emitted contract.json.

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,
  },
});

Signing 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 schema (precondition)

Calls familyInstance.schemaVerify() to confirm the live database schema matches the contract. If verification fails, the command prints the schema verification tree and exits with code 1. The marker is not written.

Write marker

Calls familyInstance.sign() which ensures the marker schema and table exist, reads any existing marker, and then:

Inserts a new marker row if no marker is present.
Updates the existing row if the stored hashes differ from the contract.
Takes no action if the stored hashes already match (idempotent).

Output formats

✔ Database signed (marker created)
  storageHash: sha256:abc123...
  profileHash: sha256:def456...
  Total time: 42ms

✔ Database signed (marker updated from sha256:old-hash)
  storageHash: sha256:abc123...
  profileHash: sha256:def456...
  previous storageHash: sha256:old-hash
  Total time: 42ms

✔ Database already signed with this contract
  storageHash: sha256:abc123...
  profileHash: sha256:def456...
  Total time: 42ms

✖ Schema verification failed
  [Schema verification tree output]

JSON output

{
  "ok": true,
  "summary": "Database signed (marker created)",
  "contract": {
    "storageHash": "sha256:abc123...",
    "profileHash": "sha256:def456..."
  },
  "target": {
    "expected": "postgres",
    "actual": "postgres"
  },
  "marker": {
    "created": true,
    "updated": false
  },
  "meta": {
    "configPath": "/path/to/prisma-next.config.ts",
    "contractPath": "/path/to/src/prisma/contract.json"
  },
  "timings": {
    "total": 42
  }
}

{
  "ok": true,
  "summary": "Database signed (marker updated from sha256:old-hash)",
  "contract": {
    "storageHash": "sha256:abc123...",
    "profileHash": "sha256:def456..."
  },
  "target": {
    "expected": "postgres",
    "actual": "postgres"
  },
  "marker": {
    "created": false,
    "updated": true,
    "previous": {
      "storageHash": "sha256:old-hash",
      "profileHash": "sha256:old-profile-hash"
    }
  },
  "meta": {
    "configPath": "/path/to/prisma-next.config.ts",
    "contractPath": "/path/to/src/prisma/contract.json"
  },
  "timings": {
    "total": 42
  }
}

Error codes

Code	Meaning
`PN-CLI-4005`	Missing database connection. Provide `--db <url>` or set `db.connection` in config.
`PN-CLI-4010`	Missing driver in config. Add a driver descriptor to your config.
Exit code 1	Schema verification failed. The live schema does not match the contract. The marker was not written.

Idempotency

db sign is safe to run multiple times. If the marker already encodes the same hashes as the current contract, no database changes are made and the command reports success. This makes it safe to include in deployment pipelines without guarding against repeated runs.

Relationship to db verify

db sign writes the marker; db verify reads it. After signing, you can confirm the marker was written correctly with:

prisma-next db verify --marker-only --db postgresql://user:pass@localhost/db

A full db verify (without --marker-only) additionally re-runs the schema verification that db sign ran as a precondition. If db sign succeeded, db verify should also succeed unless the schema was modified after signing.

Overview

Contract Commands

Database Commands

Migration Commands

prisma-next db sign — write contract marker

Options

Config requirements

Signing process

Output formats

JSON output

Error codes

Idempotency

Relationship to db verify

​Options

​Config requirements

​Signing process

​Output formats

​JSON output

​Error codes

​Idempotency

​Relationship to db verify

Options

Config requirements

Signing process

Output formats

JSON output

Error codes

Idempotency

Relationship to db verify