Developer commands

Lower-traffic CLI surfaces — eval, mine-queries, fixture-path, and import. Useful for CI, retrieval quality measurement, and dbt onboarding.

Developer commands

Four lower-traffic subcommands that don’t share a daily-use story but earn their place:

• schemabrain eval — score the retriever against a golden set.
• schemabrain mine-queries — harvest observed SQL from pg_stat_statements.
• schemabrain fixture-path — print the absolute path to a bundled fixture.
• schemabrain import dbt — import semantic definitions from a dbt manifest.

---

eval

Score a retriever implementation against a golden set; prints recall@1 / @3 / @10.

schemabrain eval --url-env DATABASE_URL --store-path ./schemabrain.db

Flag	Default	Purpose
--source URL	(none)	Source URL — used to resolve which tables in the store to score against. Deprecated when the URL contains a password.
--url-env VARNAME	(none)	Env var holding the source URL. Preferred.
--store-path PATH	./schemabrain.db	Path to the local SQLite store.
--golden PATH	Bundled e-commerce starter set	Path to a golden-set JSON file. For your own schema, author a matching JSON.
--retriever {embedding,keyword}	embedding	embedding uses stored column embeddings + cosine (requires index without --no-embed). keyword uses the keyword-overlap baseline.
--limit N	(built-in default)	Top-K cap passed to the retriever.

Authoring a golden set

Each row in the JSON file is a {query, expected_table} pair. The eval prints how often the retriever’s top-K results contained the expected table:

• recall@1 — was it the top result?
• recall@3 — was it in the top 3?
• recall@10 — was it in the top 10?

For onboarding a new schema, run eval against the bundled starter, then write a domain-specific golden set targeting your real questions.

---

mine-queries

Harvest observed SQL from pg_stat_statements into the local store. Populates the get_example_queries MCP tool’s response.

schemabrain mine-queries --url-env DATABASE_URL --store-path ./schemabrain.db

Flag	Default	Purpose
--source URL	(none)	Source URL. Deprecated when the URL contains a password.
--url-env VARNAME	(none)	Env var holding the source URL. Preferred.
--store-path PATH	./schemabrain.db	Path to the local SQLite store.

Prerequisites

Requires the pg_stat_statements extension on the source database:

-- One-time, as a superuser, in postgresql.conf:
--   shared_preload_libraries = 'pg_stat_statements'
-- Then restart Postgres, then:
CREATE EXTENSION pg_stat_statements;

The mining role needs read access to the pg_stat_statements view (superusers always have it; non-super roles need pg_read_all_stats).

If the extension or grant is missing, mine-queries exits cleanly with an actionable message — no row is written, the store stays intact, and get_example_queries keeps returning status: empty with a recovery hint pointing to Manual flow — Mine observed queries.

The joins suggest command also reads pg_stat_statements evidence — running mine-queries first improves canonical-join ranking.

---

fixture-path

Print the absolute path to a bundled fixture. Paste-clean for shell substitution.

schemabrain fixture-path ecommerce.sql
# /abs/path/to/site-packages/schemabrain/fixtures/ecommerce.sql

psql -f "$(schemabrain fixture-path ecommerce.sql)" "$DATABASE_URL"

Argument	Purpose
name (positional)	Bundled fixture basename, e.g. ecommerce.sql (SQL seed) or ecommerce.json (golden set for eval).

Useful for:

• Seeding a demo Postgres against the bundled e-commerce schema.
• Loading the starter golden set into a custom eval driver.
• CI smoke tests that operate against a known shape.

---

import dbt

Import entities (and optionally metrics) from a dbt manifest.json. Read-only against dbt — no export path.

schemabrain import dbt /path/to/dbt/target/manifest.json --url-env DATABASE_URL

Argument / Flag	Default	Purpose
manifest_path (positional)	(required)	Path to your dbt project’s compiled target/manifest.json. Run dbt compile to produce it. Remote (dbt Cloud) manifests aren’t supported — download locally and pass the path.
--source URL	(none)	Source URL. Deprecated when the URL contains a password.
--url-env VARNAME	(none)	Env var holding the source URL. Preferred.
--store-path PATH	./schemabrain.db	Path to the local SQLite store.
--dry-run	(off)	Compute the plan (added / updated / ownership-transferred / skipped / orphans) and print the summary, but write nothing. Best mode for CI previews.
--report PATH	(none)	Optional. Writes a JSON report of the plan (bucket counts + per-model details) to this path. Works with both dry-run and apply.
--include-metrics	(off)	Also import dbt metrics (type=simple only) anchored on the entities imported in this run. Skips ratio / derived / cumulative metrics with structured reasons. Off by default to preserve backwards-compatible behaviour from earlier releases; on by default in a future release.

dbt-driven curation via init

schemabrain init auto-detects a dbt manifest from $DBT_PROJECT_DIR (or by walking up from cwd for dbt_project.yml) and routes the entity + metric curation stages through this importer instead of the LLM. See schemabrain init.

---

Related

schemabrain index

Index first, then eval / mine-queries.

schemabrain joins suggest

Consumes mine-queries output for canonical-join ranking.

MCP tool — get_example_queries

The agent-facing surface mine-queries populates.

schemabrain init

Auto-detects dbt and routes curation through this importer.