dbprint

dbprint

Example · Quickstart · Using dbprint · Compared with other tools · The format

dbprint measures a database and writes each table's DDL, its joins and per-column statistics as plain text to commit beside the code, next to the notes on what the values mean that a person or an agent writes. A coding agent reads both offline, with no database connection.

Migrations and models record a database's shape, not what its values mean: that revenue_cents is gross and every report uses the net column, that status is spelled two ways, how often orders joins shipments one-to-many, that legacy_uid has been unused since a migration. An agent without a database connection cannot find these out. An agent with one re-runs the same queries in every session, at a cost in warehouse time, budget and tokens, and can still misread the result: a count does not say that a code is unused or that a column is gross.

What dbprint does, and what an agent adds:

• It measures the database once. Each table's DDL, its joins — declared, and inferred where the schema declares none — and per-column statistics: null shares, complete value lists with every spelling, ranges, distributions, value shapes and more. On PostgreSQL, MySQL, Snowflake, BigQuery, Databricks, Redshift, ClickHouse, duckdb or SQLite.
• An agent writes down what the numbers mean. dbprint annotate hands an agent one table's measurements and the questions they leave open — what a code means, what a sentinel date stands for, which rows a report leaves out — and the agent answers them from the project's code and read-only queries, into files dbprint never overwrites. dbprint annotate --check flags a note the data contradicts.
• Every later session reads it offline. Through an MCP server, a packaged skill or dbprint context, with no database connection and no credentials at the agent. Because it is text in git, a schema or data change shows up in review, and dbprint check gates it in CI.

With dbprint, agents get more answers right, for less. In our tests across multiple codebases, coding agents reading an annotated print got 80% fewer answers wrong than without one, at 17% lower cost per correct answer, and 90% fewer on questions whose catch only the print stated.

Example

An excerpt of dbprint context --purpose query on a table from the reference print in this repo — the fragment an agent gets before it writes SQL:

# Table: arboretum.seedbank.germination_trial  (900 rows, 8 columns)

Column values

Data dictionary

One row per germination attempt run against a batch drawn from an accession.

Joins

• accession_id -> arboretum.seedbank.accession.accession_id (declared)
• collector_id -> arboretum.seedbank.collector.collector_id (inferred)

Three things here no migration states: medium holds exactly these values and no others, sand tray is stored in two spellings, so a filter on one misses 25 rows, and control is not a medium at all. dbprint measured the first two; a person or an agent wrote the third once, and every later session reads it.

The same command runs with no database and no configuration, given only uv:

uvx dbprint context arboretum.seedbank.germination_trial --purpose query \

--project https://github.com/jakubro/dbprint/blob/main/docs/format/v1/examples/production/.dbprint.yaml

Quickstart

Requires Python 3.13+. Install with the driver extra for the database's engine:

uv tool install 'dbprint[postgres]'     # or [mysql], [snowflake], [duckdb], [clickhouse], [redshift], [databricks], [bigquery]; SQLite needs none

Add [mcp], [docs] or [dbt] in the same install — uv tool install 'dbprint[postgres,mcp]', or 'dbprint[all]' for every extra — since a later install replaces the earlier one.

The Postgres adapter shells out to `pg_dump` for DDL, so the PostgreSQL client binaries must be on PATH.

Scaffold a project in the repository root:

dbprint init

That writes .dbprint.yaml (commit it), creates prints/, and writes a credentials template to ~/.dbprint/connections.yaml — outside the repo, so secrets never sit next to the config.

Put the connection details in the credentials file:

# ~/.dbprint/connections.yaml

primary: host: localhost port: 5432 database: my_db user: dbprint_ro password: change_me

and tell .dbprint.yaml which adapter to use and which tables to read:

# .dbprint.yaml

connections: primary: adapter: postgres auto: true tables: include:

• "*.public.*"

Credentials resolve from DBPRINT_ _ environment variables first, then ~/.dbprint/connections.yaml, then a project-root .env. Every key of both files is in docs/CONFIG.md.

Profile it:

dbprint generate

Commit the result beside the code. Then inspect it with no database in reach:

dbprint list

Then have an agent annotate a table — the brief carries the annotation skill's steps, so any agent CLI can follow it:

dbprint annotate my_db.public.orders | claude -p

and connect an agent to the result.

Using dbprint

The full documentation is on the dbprint site.

What dbprint does to the database

• It reads. A role that can SELECT the profiled tables is enough; each engine's adapter page, linked from your first print, lists the exact grants. The one write is a temporary copy of a sampled table's drawn rows, gone when the session ends (on BigQuery, when its expiration passes), and only for a sampled table — read.tables.materialize turns it off.
• It publishes real values. Value lists, ranges and percentiles are cell values, and they are committed to the repository. Nothing is withheld by default: redaction masks, drops or hashes them by column name, by detected sensitivity (personal_name, national_id, ...) or by shape, keeping every count. A password or key written into the schema itself — a view body, a default, a comment — is masked in ddl.sql on every run, whatever the rules say.
• It costs one profiling run, then whatever later runs re-read. A table is re-read when its print is older than its freshness threshold or its settings changed; sampling, row filters and catalog-only reads bound the cost on a warehouse — see choosing what to profile.

What a print looks like

Under the context an agent reads are plain YAML files. An excerpt of one table's statistics.yaml, some fields elided, from the same reference print:

row_count: 2500

columns: catalogue_url: sql_type: character varying(200) nullable: false null_rate: 0.0 classification: text cardinality: 2500 cardinality_ratio: 1.0 inferred: looks_like: url sampled: 1000 matched: 1000 candidate_key: true values:

• value: https://specimens.example.org/accession/1 count: 1
• value: https://specimens.example.org/accession/10 count: 1

... 28 more

values_coverage: 0.012 # top 30 of 2500 - a value list, not a claim of completeness distribution: long_tail

provenance_country: sql_type: character(2) classification: categorical cardinality: 10 inferred: looks_like: country_code sampled: 10 matched: 10 values:

• value: AU count: 250
• value: CA count: 250
• value: DE count: 250
• value: FR count: 250
• value: GB count: 250

... 5 more

values_coverage: 1.0 # the list is the whole domain, not a sample distribution: uniform

received_at: sql_type: timestamp(0) with time zone classification: temporal range: min: '2018-01-08T00:00:00Z' max: '2024-11-28T00:00:00Z' span_days: 2516 percentiles: p01: '2018-02-09T00:00:00Z' p25: '2019-10-02T00:00:00Z' p50: '2021-06-19T00:00:00Z' p75: '2023-03-05T00:00:00Z' p99: '2024-10-25T00:00:00Z'

values_coverage: 1.0 marks those ten values as the *entire* domain, not the top ten, so an eleventh value is ruled out without querying the database. (When a table is profiled from a sample rather than in full, coverage is measured over the rows that were actually read — see Scoped profiling below.)

inferred is what dbprint concluded rather than read: looks_like: country_code is a verdict, and sampled/matched are the evidence for it, so a shape confirmed by ten values never looks like one confirmed by ten thousand.

Alongside it, relationships.yaml carries the join graph:

refers_to:

• column:
• collector_id target_table: arboretum.seedbank.collector target_column:
• collector_id on_delete: RESTRICT detection: declared # or inferred, when dbprint guessed the edge from naming observed: fanout_avg: 6.25 target_coverage: 1.0

Those two files are measured. Notes are written beside them, by a person or an agent, in the same directory and the same commit — statistics.annotations.yaml for a column:

columns:

collector_id: note: >- FK to collector.collector_id. Field collectors are affiliated with a partner institution; collector.institution names it.

and description.md for table-level narrative that no statistic can express.

dbprint never writes to either file, and both are read alongside the statistics — but on anything the statistics can answer, the statistics win; the narrative is authoritative only on what a number can't.

Print directory layout

prints/<connection>/

manifest.yaml # inventory, freshness, per-table thresholds reading.md # generated guide - how to read the rest of the print diff.yaml # machine-readable drift from the last run manifest.annotations.yaml # optional, connection-level notes you write / / # one directory per FQN segment, e.g. arboretum/seedbank/accession/ ddl.sql # native DDL, normalized for stable diffs statistics.yaml # column distributions relationships.yaml # d