prisma-next db schema — inspect live database

prisma-next db schema connects to a live database, queries its catalog, and renders the discovered schema as a human-readable tree or a machine-consumable JSON envelope. The command is entirely read-only — it never writes files, modifies schema, or touches the contract marker. This is useful for spot-checking what a database actually contains, debugging schema drift, or confirming the result of a migration before signing. The output reflects native database types (for example int4, text, timestamptz) rather than mapped codec IDs, giving you an accurate view of the actual database state.

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 instead of the TTY tree.

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 schema requires a driver entry in your config to open a database connection. A contract entry is not required since this command does not read or compare contract artifacts.

prisma-next.config.ts

import { defineConfig } from '@prisma-next/cli/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';

export default defineConfig({
  family: sql,
  target: postgres,
  adapter: postgresAdapter,
  driver: postgresDriver,
  extensionPacks: [],
  db: {
    connection: process.env.DATABASE_URL,
  },
});

Usage examples

# Use config defaults
prisma-next db schema

# Specify database URL explicitly
prisma-next db schema --db postgresql://user:pass@localhost/db

# Output as JSON for scripting
prisma-next db schema --json

# Verbose output with timing data
prisma-next db schema -v

Output formats

sql schema (tables: 2)
├─ table user
│  ├─ id: int4 (not null)
│  ├─ email: text (not null)
│  └─ unique user_email_key
├─ table post
│  ├─ id: int4 (not null)
│  ├─ title: text (not null)
│  └─ userId: int4 (not null)
├─ extension plpgsql
└─ extension vector

{
  "ok": true,
  "summary": "Schema introspected successfully",
  "schema": {
    "root": {
      "kind": "root",
      "id": "sql-schema",
      "label": "sql schema (tables: 2)",
      "children": [
        {
          "kind": "entity",
          "id": "table-user",
          "label": "table user",
          "children": [
            {
              "kind": "field",
              "id": "column-user-id",
              "label": "id: int4 (not null)",
              "meta": {
                "nativeType": "int4",
                "nullable": false
              }
            }
          ]
        }
      ]
    }
  },
  "meta": {
    "configPath": "/path/to/prisma-next.config.ts",
    "dbUrl": "postgresql://user:pass@localhost/db"
  },
  "timings": {
    "total": 42
  }
}

Column types in the output are native database types (int4, text, timestamptz), not Prisma Next codec IDs (pg/int4@1). This reflects the actual database state and may differ from the codec mappings defined in your contract.

Introspection process

The command follows these steps internally:

Connects to the database using config.driver.create(url).
Builds a ControlStack and creates a family instance via config.family.create(stack).
Calls familyInstance.introspect() to query the database catalog and return a family-specific schema IR (for example, SqlSchemaIR for the SQL family).
Calls familyInstance.toSchemaView() to project the schema IR into a CoreSchemaView for display.
Renders the CoreSchemaView as a tree (TTY) or JSON envelope (--json).

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.

To capture a baseline snapshot of your database schema before making changes, pipe the JSON output to a file: prisma-next db schema --json > schema-snapshot.json. You can diff two snapshots to understand what changed between deployments.

Overview

Contract Commands

Database Commands

Migration Commands

prisma-next db schema — inspect live database

Options

Config requirements

Usage examples

Output formats

Introspection process

Error codes

​Options

​Config requirements

​Usage examples

​Output formats

​Introspection process

​Error codes

Options

Config requirements

Usage examples

Output formats

Introspection process

Error codes