dbprint

dbprint

データベースの意味を一度書き留めてコードの隣に置けば、エージェントのセッションごとに読み取られます。

コーディングエージェントはマイグレーションとモデルを読み取るため、データベースの構造は正しく把握できます。正しく把握できないのは、構造だけではわからないことです。たとえば、revenue_cents は総額で、すべてのレポートでは純額のカラムを使うこと、status の綴りが二通りあること、orders と shipments の結合は予想以上に一対多になること、legacy_uid はマイグレーション以降使われていないことです。同僚なら30秒で教えてくれるでしょう。データベース接続がなければ、エージェントはそれを調べられません。接続があれば、セッションのたびに同じ情報をその場で再発見します。倉庫の時間と予算を消費し、エージェントのトークンも消費するクエリを実行しても、誤読する可能性は残ります。件数だけでは、そのコードが使われていないことも、カラムが総額であることもわかりません。

dbprint は、その知識をリポジトリにコミットできるプレーンテキストにします。

• データベースを一度計測します。 各テーブルの DDL、結合（宣言済みのものに加え、スキーマに宣言がない場合は推論したもの）、およびカラムごとの統計情報を取得します。NULL の割合、綴りをすべて含む完全な値の一覧、範囲、分布、値の形式などが対象です。8種類のエンジンに対応しています。
• エージェントが数値の意味を書き留めます。 dbprint annotate は、あるテーブルの計測結果と、そこからは答えがわからない質問をエージェントに渡します。コードが何を意味するのか、センチネル日付が何を表すのか、レポートで除外される行はどれか、といった質問に、エージェントはコードと読み取り専用クエリから回答し、dbprint が上書きしないファイルに書き込みます。dbprint annotate --check を実行すると、データと矛盾する注釈を検出します。
• その後のセッションでは、毎回オフラインで読み取れます。 MCP サーバー、パッケージ化されたスキル、または dbprint context を通じて利用でき、データベース接続もエージェント側の認証情報も不要です。テキストとして git に保存されるため、スキーマやデータの変更はレビューで確認でき、dbprint check で CI のチェックを通すことができます。

dbprint を使えば、エージェントはより少ないコストで、より多くの答えを正しく導けます。 複数のコードベースで行ったテストでは、注釈付きのプリントを読むコーディングエージェントは、読まない場合に比べて誤答が80％減少し、正答あたりのコストが17％低下しました。プリントにしか記載されていない情報が決め手となる質問では、誤答が90％減少しました。

エージェントが読む内容

このリポジトリの参照プリントにあるテーブルを対象に、dbprint context --purpose query を実行した際の抜粋です。エージェントが SQL を書く前に受け取る断片です。

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

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

## Data dictionary

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

## Column values

| Column | Values (count) | Coverage | Nulls |
|---|---|---|---|
| medium | 'moist filter paper' (176), 'sterile grit' (176), 'vermiculite mix' (176), 'agar medium' (175), 'sand tray' (176) {'sand tray' (151), 'Sand Tray' (25)}, 'control' (21) = 'No growth medium: a no-treatment control group, its germinated_count compared against ambient conditions rather than a physical medium.' | 100% - the list is the whole domain |  |

ここには、どのマイグレーションにも記されていないことが3つあります。medium がこれらの値だけを持ち、ほかの値はないこと、sand tray は2種類の綴りで保存されているため、一方だけでフィルタリングすると25行が漏れること、そして control はそもそも媒体ではないことです。最初の2つは dbprint が計測しました。最後の1つは人間かエージェントが一度書き留めたもので、その後のすべてのセッションで読み取られます。

データベースも設定も不要で、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

クイックスタート

Python 3.13+ が必要です。データベースに対応するドライバーの追加機能とともにインストールします：

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

同じインストール時に [mcp]、[docs]、または [dbt] の追加機能を指定してください。たとえば、uv tool install 'dbprint[postgres,mcp]' のようにします。後からインストールすると追加されるのではなく、先のインストールが置き換えられるためです。

Postgres アダプターは DDL の取得に pg_dump を呼び出すため、PostgreSQL クライアントのバイナリを PATH に含めておく必要があります。

リポジトリのルートでプロジェクトを作成します：

dbprint init

これにより .dbprint.yaml が書き込まれるので、コミットしてください。また、prints/ が作成され、認証情報のテンプレートが ~/.dbprint/connections.yaml に書き込まれます。リポジトリの外に置かれるため、シークレットが設定ファイルの隣に置かれることはありません。

認証情報ファイルに接続情報を記入します：

# ~/.dbprint/connections.yaml
primary:
  host: localhost
  port: 5432
  database: my_db
  user: dbprint_ro
  password: change_me

続いて、使用するアダプターと読み取るテーブルを .dbprint.yaml で指定します：

# .dbprint.yaml
connections:
  primary:
    adapter: postgres
    auto: true
    tables:
      include:
        - "*.public.*"

認証情報は、まず DBPRINT_<CONNECTION>_<KEY> 環境変数から、次に ~/.dbprint/connections.yaml から、最後にプロジェクトルートの .env から解決されます。両方のファイルで使えるすべてのキーは、docs/CONFIG.md に記載されています。

プロファイルを作成します：

dbprint generate

結果をコードと一緒にコミットします。その後、データベースに接続できない環境でも内容を確認できます：

dbprint list

次に、エージェントにテーブルの注釈を付けてもらいます。手順をまとめたブリーフには注釈スキルが含まれているため、どのエージェント CLI でも実行できます：

dbprint annotate my_db.public.orders | claude -p

そして、エージェントを接続して結果を利用します。

データベースに対する動作

• 読み取りを行います。 プロファイル対象のテーブルに対して SELECT を実行できるロールがあれば十分です。各エンジンのアダプターページには、最初のプリントからリンクされており、必要な権限が正確に記載されています。唯一の書き込みは、サンプリング時にのみ行われる、サンプリング対象テーブルの描画された行の一時コピーです。このコピーはセッション終了時（BigQuery の場合は有効期限が切れたとき）に削除されます。これを無効にするには、read.tables.materialize を設定します。
• 実際の値を公開します。 値のリスト、範囲、パーセンタイルはセルの値であり、リポジトリに保存されます。デフォルトでは何も除外されません。秘匿化では、列名、検出された機微情報（personal_name、national_id など）、または値の形式に基づいて値をマスク、削除、またはハッシュ化し、すべての件数を保持します。
• プロファイルの実行は一度だけで、以降は必要に応じて再実行できます。 プリントが鮮度のしきい値を超えた場合、または設定が変更された場合に、テーブルが再読み込みされます。データウェアハウスでのコストは、サンプリング、行フィルター、カタログのみの読み取りで抑えられます。プロファイル対象の選び方をご覧ください。

プリントの内容

エージェントが読み取るコンテキストは、プレーンな YAML ファイルです。同じリファレンスプリントに含まれる、あるテーブルの statistics.yaml の一部を示します。一部のフィールドは省略しています：

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 は重要なフィールドです。この 10 個の値が、上位 10 個ではなく、値のドメイン全体を表していることを意味します。データベースに問い合わせなくても、11 個目の値が存在しないと判断できます。（テーブル全体ではなくサンプルからプロファイルを作成した場合、カバレッジは実際に読み取った行を対象に測定されます。詳しくは、以下のスコープを絞ったプロファイリングをご覧ください。）

inferred は、dbprint が読み取ったのではなく推定した内容です。looks_like: country_code は判定であり、sampled／matched はその根拠です。そのため、10 個の値で確認された形式が、1 万個の値で確認された形式と同じように扱われることはありません。

これに加えて、relationships.yaml には結合グラフが含まれます：

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

ここまでが測定によって得られる情報です。残りは、同じディレクトリに、同じコミットで自分で記述します。列の注釈は statistics.annotations.yaml に記述します：

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

また、統計では表現できないテーブル単位の説明は description.md に記述します。

dbprint はどちらのファイルにも書き込みません。両方とも統計情報とあわせて読み込まれます。ただし、統計情報で答えられる内容については統計情報が優先され、説明文が優先されるのは数値では表せない内容だけです。

リポジトリに追加されるもの

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
  <schema>/<table>/
    ddl.sql                        # native DDL, normalized for stable diffs
    statistics.yaml                # column distributions
    relationships.yaml             # declared + inferred foreign keys
    description.md                 # optional, you write it
    statistics.annotations.yaml    # optional, per-column notes you write
    relationships.annotations.yaml # optional, per-edge notes you write

reading.md は実行のたびに新しく書き込まれます。各フィールドで何を信頼すべきかを利用者に説明するため、フォーマットを初めて目にするエージェントにも、プリントの内容がひと目で分かります。

4 つの .md / .annotations.yaml ファイルはユーザーが管理します。dbprint が上書きすることはなく、4 つすべてがエージェントの読み取り内容に反映されます。

コマンド

コマンド	内容
dbprint init	.dbprint.yaml、prints/、認証情報のテンプレートを作成します
dbprint config explain	あるテーブルに適用されるプロファイルを出力し、各値に、それを設定したデフォルト値、接続、またはルールをコメントとして付記します
dbprint generate	データベースをプロファイリングし、プリントと diff.yaml を書き込みます
dbprint list	コミット済みのプリントのオフライン概要を表示します
dbprint diff	稼働中のデータベースとコミット済みのプリントを比較します
dbprint check	CI ゲートとして、構造、新しさ、統計のアサーションを確認します。--online を指定すると、ドリフトと SQL のアサーションも追加されます
dbprint context	1 つ以上のテーブルの、プロンプトにすぐ使える Markdown ビューを出力します
dbprint annotate	1 つのテーブルのアノテーション作成用ブリーフを出力します。または --check でアノテーションを確認します
dbprint docs	HTML サイトとしてプリントを閲覧します。serve でライブ配信するか、build で静的サイトを生成します（[docs] エクストラ）
dbprint serve	コミット済みのプリントを提供する読み取り専用 MCP サーバーです（[mcp] エクストラ）

全リファレンスは docs/CLI.md をご覧ください。

エージェントの接続

MCP クライアントがサーバーを起動するため、作業ディレクトリを選ぶのはあなたではなくクライアントです。プロジェクト名を明示してください。

{
  "mcpServers": {
    "dbprint": {
      "command": "uvx",
      "args": ["--from", "dbprint[mcp]", "dbprint", "serve", "--project", "/srv/analytics"]
    }
  }
}

サーバーはコミット済みのプリントを読み取り、データベースには接続しないため、クライアントに認証情報は必要ありません。

リモートプロジェクトの読み取り

--project には Git アドレスも指定できます。そのため、他者のリポジトリにコミットされたプリントも、事前に手動でクローンせずに読み取れます。

dbprint list --project https://github.com/jakubro/dbprint/blob/main/docs/format/v1/examples/production/.dbprint.yaml
dbprint context arboretum.seedbank.accession --project https://github.com/jakubro/dbprint#main:docs/format/v1/examples/production

dbprint がクローンを行うため、dbprint 自体の認証情報は不要です。プライベートリポジトリでは、既存の SSH エージェントまたは認証情報ヘルパーを使用します。読み取り専用のため、書き込みや稼働中のデータベースへの接続を行うコマンド（generate、diff、check --online）はリモートロケーターを拒否します。それ以外のコマンドは、ローカルの場合とまったく同じように実行できます。

基本を超えて

• セマンティック推論。 すべての列に、8種類の分類のいずれかが付与されます。テキスト列、カテゴリ列、外部キー列には、38種類の形状パターン（uuid、email、phone、ip、country_code、…）のいずれかが付与され、判定の根拠となるサンプルサイズと一致数も公開されます。データベースの外に出してはならないデータを保持する列には、sensitivity 軸（personal_name、postal_address、national_id、credential、…）が付与されます。実質的に一意な列（カーディナリティ比 >= 0.9999）には candidate_key の印が付き、このしきい値によって真の一意性ではなく、測定済みまたは推定済みの重複が許容される場合は、あわせて candidate_key_exception も付与されます。スキーマで宣言されていない外部キーは、名前から推論され、detection: inferred の印が付きます。
• マスキング。 mask、drop、または hash（ソルト付き）を使ってセルの値を伏せます。列は glob、推論された機密性、または形状のいずれかを基準に指定できるため、来四半期に追加された personal_name 列も、今日作成したルールの対象になります。件数、カーディナリティ、分布はそのまま残り、リテラル値だけが伏せられます。ソルトは認証情報とともに保存され、コミット済みの設定には含まれません。
• アサーション。 あらゆる統計値に対するデータ品質チェックを YAML で記述するか、SQL をそのまま記述します。統計値のアサーションは、データベースに接続せず、コミット済みの出力に対して通常の dbprint check で評価されます。SQL アサーションには dbprint check --online が必要です。詳しくは docs/ASSERTIONS.md をご覧ください。
• CI の終了コード。 0 は正常、1 は出力の形式不正または設定が使用不能、2 は古い状態、3 は差分あり、4 は接続失敗、5 は部分実行、6 はアサーション失敗、7 は全体的な失敗を表します。diff、check、context はすべて --format json|yaml に対応しています。
• 範囲を指定したプロファイリング。 テーブルごとのルールでは、サンプリング（エンジンがシードに対応している場合はテーブル名をシードとして使用）、行フィルターの適用、または測定対象の変更ができます。テーブルサイズを条件にできるため、まだ名前を指定していないすべてのファクトテーブルに1つのルールを適用できます。この方法で読み取られたテーブルには scope ブロックと列ごとの rows_scanned が記録され、ファイル内のすべての件数は、テーブル全体ではなく、実際に読み取った行数に基づきます。
• MCP サーバー。 dbprint serve は7つのツール（get_table_context、list_tables、search_columns、resolve_value、get_manifest、get_diff、get_reference）に加え、すべての成果物をリソースとして公開します。コミット済みの出力のみを読み取り、データベースへの接続は一切行いません。詳しくは docs/MCP.md をご覧ください。
• Markdown スキル。 Markdown のルールやカスタム指示を受け取るクライアント向けに、コミット済みの出力で分かること、質問に答えるツール、各数値の対象範囲をエージェントに伝える、すぐに使えるスキルファイルを用意しています。実行すべきプロセスはありません。もう1つのスキルでは、各テーブルを書き込むコードと読み取り専用クエリをもとに、エージェントがアノテーションファイルを作成します。これは dbprint annotate --check で検証できます。どちらも docs/examples/skill/ にあるので、インストールする前に内容を確認できます。
• dbt のリネージ。 接続の dbt_manifest にコンパイル済み dbt の manifest.json を指定すると、generate が各モデル列のソース列を derived_from として記録します。これにより、ソース列に一度記述した注記が、そこから構築されたすべてのモデルに引き継がれます（[dbt] extra）。詳しくは docs/CONFIG.md をご覧ください。
• トークン予算に合わせたコンテキスト。 dbprint context arboretum.seedbank.accession --budget 4000 は、優先度の低いセクションから順に削除して、Markdown 表示をトークン予算内に収めます。

最も近いプロジェクト

プロジェクト	機能	dbprintとの違い
dryrun	オフラインのPostgresスキーマスナップショット＋MCPサーバー＋リンティング	最も近いプロジェクトです。スナップショットは圧縮されたバイナリバンドルで、.gitattributes で binary と指定します。dbprintの成果物は、公開仕様に基づく、8種類のデータベースに対応した、行単位で差分を確認できるYAMLです
dbt-profiler	dbt YAML／Markdownにコミットするカラムプロファイル	dbtプロジェクト専用です。DDL、リレーショングラフ、セマンティック推論、秘匿化には対応していません
ライブ接続型MCPサーバー（dbhub、postgres-mcp、Supabase、Neon）	エージェントの実行時にデータベースをクエリし、イントロスペクトします	エージェント側に認証情報が必要で、セッションごとに設定しなければなりません。dbprintは一度だけプロファイルを作成して結果をコミットし、データベースにアクセスせずに提供します
tbls、SchemaSpy	人間向けのスキーマドキュメントとER図	構造のみで、データ分布は含みません。dbprint docs serve は、計測済みカラムを含むプリントから、同じように閲覧できるページとFK図を生成します

dbprintではないもの

• マイグレーションツールではありません。 DDLの変更を作成、適用、バージョン管理するものではありません。Alembic、Flyway、Liquibase、sqldef、Atlasをお使いください。
• スキーマ管理レイヤーやORMレイヤーではありません。 プリントはデータベース から 生成されるものであり、そこから構築する信頼できる唯一の情報源ではありません。
• ライブクエリインターフェースではありません。 プリントを使ってエージェントがSQLを実行することはありません。
• データ品質プラットフォームではありません。 アサーションDSLはプリントに対するCIゲートであり、監視、アラート、リネージではありません。Soda、Great Expectations、Elementaryをお使いください。
• データカタログではありません。 ホステッドサービス、共有検索インデックス、ビジネス用語集はありません。dbprint docs は、コミット済みプリントのローカル読み取り専用ビューをループバックにバインドして提供し、管理が必要なものはありません。

フォーマット

プリントは、データベースの構造とカラムレベルのデータ分布をまとめた、持ち運び可能なGitコミット済みスナップショットです。人間、AIコーディングエージェント、CIがオフラインで利用できます。 ここで長期的に保持される成果物はCLIではなく、ディスク上のフォーマットです。仕様が定められ、ツールとは独立してバージョン管理されており、ほかの生成元からも出力できるよう設計されています。

フォーマットの仕様は docs/format/v1/SPEC.md に記載されています。

7つのJSON Schemaがインストール済みパッケージ内の src/dbprint/spec/v1/ に含まれています。生成される成果物用が4つ、作成するアノテーションファイル用が3つです。適合性バリデーターは、データベース、設定、CLIを必要としない公開APIです。

from dbprint.conformance import validate_print

issues = validate_print("prints/production")  # conforms iff no error-severity issues

docs/format/v1/examples/ にある参照用プリントは、手書きの例ではなく、実際のdbprint出力です。そこで読めるものが、そのまま得られる内容です。

設定

.dbprint.yaml にはプロジェクト設定を記述し、コミットします。~/.dbprint/connections.yaml には認証情報を記述し、コミットしません。両方のすべてのキーについて、型、デフォルト値、解決順序を docs/CONFIG.md に記載しています。内部構造については docs/ARCHITECTURE.md をご覧ください。

ライセンス

Copyright 2026 Jakub Roman. Apache License 2.0 に基づき配布されています。