<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alikarami76/keygraph/main/design/visuals/readme-hero-dark.svg"> <img alt="keygraph: map how your tables connect, for people and AI agents" src="https://raw.githubusercontent.com/alikarami76/keygraph/main/design/visuals/readme-hero-light.svg"> </picture>

keygraph

keygraph is an open-source schema map for people building a data analyst agent, a text-to-SQL agent or any other LLM agent that answers questions from a database. It maps how your tables connect (keys, indexes, declared and inferred foreign keys, grain, status codes, business context and value profiles) and serves that schema context to agents through an MCP server, a CLI with --json, or markdown files, and to people through an offline HTML explorer. It reads only metadata, makes no LLM calls, and gives the same output for the same input. It can also link your source code to the same tables and columns (where each column is declared, written, read and used) and keep a log of the queries people and agents ran, with their timing and the business question behind them.

At a glance. MIT licence. Python 3.11 or newer. Reads MySQL, MariaDB, PostgreSQL, SQLite, SQL Server, ClickHouse, Metabase and MongoDB, or information_schema dumps. Fifteen MCP tools: fourteen read-only and one that logs a query. Runs without a server, and the bundled demo webshop has 35 tables in three schemas. Jump to: build a data analyst agent, quickstart, MCP setup, FAQ.

Why a prebuilt map beats no context or context made on the fly

An agent that writes SQL needs to know which tables exist, how they join, what one row means and what the codes in a column stand for. There are three ways to give it that.

No context at all. The agent guesses table names and joins on columns that look alike. It cannot see that a table holds one row per order line rather than per order, so its sums double count. It does not know that status = 4 means "cancelled". The SQL runs and returns a number, and nothing tells you the number is wrong.

Context the agent makes itself. The agent queries information_schema and samples rows at the start of each session, or asks an LLM to describe the tables. This helps, with four costs:

• the same exploration is repeated in every session, which costs time, tokens and load on the database;
• a large database does not fit in a context window. A 10,000-table warehouse has well over 100,000 columns, so the agent sees only the slice it happened to open and misses the join path that runs through a table it never looked at;
• the result changes from run to run. LLM-written descriptions can be confidently wrong, and nothing marks which parts are guesses;
• sampled rows can carry personal data straight into prompts and logs.

A map built in advance (keygraph). keygraph reads the metadata once and stores the result:

• Whole schema, small prompts. Join paths, hub tables and business areas are computed by code over the whole database. The agent asks for only what it needs, such as one path or one table page, so it doesn't load the schema into its prompt.
• Same answer every time. There are no LLM calls, and the same input always gives the same output, so the map can be reviewed and versioned in git like code.
• Guesses are labelled. Every inferred relation carries a confidence and the reason it was inferred. Curated business context is marked verified or unverified, so the agent knows what to double-check.
• Knowledge accumulates. Grain, status codes, pitfalls and corrections are written down once and reused by every person and agent, instead of being rediscovered and forgotten in each session.
• Safe by construction. It reads metadata only, value profiles mask personal data, and agents query the map instead of the production database.
• One map for people and agents. The HTML explorer, the CLI, the MCP server and the markdown pages all read the same graph.

| | No context | Made on the fly | keygraph | |---|---|---|---| | Covers the whole schema | no | only what fits in the prompt | yes | | Cost per question | low, but answers are often wrong | repeated exploration every session | one lookup | | Same answer each run | no | no | yes | | Shows which joins are guesses | no | no | yes, with confidence and reason | | Business meaning of codes and grain | no | rediscovered, then lost | stored, curated, reused | | Personal data in prompts | no | often | masked |

How do I build a data analyst agent with keygraph?

Build the map once with keygraph scan, then let your agent look up tables, join paths and keys through MCP or the CLI before it writes any SQL. keygraph works with any agent that can call MCP tools or run a CLI, including Claude Code and the Claude Agent SDK, and agents written with LangChain, LlamaIndex or your own tool-calling loop. It exposes three interfaces (MCP, CLI --json and markdown files) and no framework-specific plugins.

The problem it solves. An LLM that writes SQL against a database it has never seen tends to fail in three ways. It invents joins from column names that look alike. It misses the grain of a table, so a sum over order lines is counted twice. It misreads codes, such as treating status = 4 as something other than "cancelled". The query runs, returns a number, and nothing says the number is wrong.

The loop. An agent that uses keygraph follows the same six steps for each question. The order is the one recommended in AGENTS.md.

1. search the business term (for example "net revenue") to find candidate tables and see why each one matched.
2. describe each candidate to read its grain, keys, columns, status codes and pitfalls.
3. path between the tables to get ranked join routes with confidence, evidence, fan-out warnings and a JOIN snippet. Do not write a join from column-name guesses when path can answer it.
4. keys on the large tables to pick filters that match an index, leading with the first column of an index.
5. Write the SQL and run it with your own read-only database access. keygraph has no tool for running your queries: it only reads metadata, and samples values when you ask it to profile. Before you write it, if code or past queries were indexed, code_where shows how a column is used in code and query_for shows queries that already touched the table, with their business question and timing.
6. Check the result against what the map said: aggregate before a fan-out join, treat relations below 0.6 confidence as unverified, and verify them with a small SELECT. Then log the query you ran with query_submit (or keygraph queries add), so the next agent can reuse a proven query shape. query_submit only records; keygraph still runs nothing.

Register the MCP server once and the fifteen tools appear in your agent (the configs for other clients are in MCP):

claude mcp add keygraph -- uvx --from 'keygraph[mcp]' keygraph mcp --dir /abs/path/to/out

If your agent cannot use MCP, have it run the same commands with --json, for example keygraph path orders shipments --json, or let it read areas/<area>.md and tables/<schema.table>.md as ordinary files. When the agent confirms what a table or status code means, keygraph context add saves it, so the next question starts from better context.

When to use keygraph

Use keygraph when you need to:

• find the join path between two tables, with the join columns, a confidence for each hop and a ready JOIN snippet;
• infer missing foreign keys in a database that declares few or none;
• get an ER diagram of an existing database, grouped into business areas so it stays readable;
• give an LLM agent schema context for text-to-SQL: keys, indexes, join paths, grain, status codes and pitfalls, through MCP, a CLI with --json, or markdown files;
• find which table holds a business concept such as "net revenue" or "in transit";
• learn what an enum or status code means, and compare the documented codes with the values actually in the data;
• profile column values (top values, empty rate, ranges) with personal data masked;
• browse a data catalog from one offline HTML file, without running a server.

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alikarami76/keygraph/main/design/visuals/section-quickstart-dark.svg"> <img alt="Quickstart" src="https://raw.githubusercontent.com/alikarami76/keygraph/main/design/visuals/section-quickstart-light.svg"> </picture>

Quickstart

keygraph needs Python 3.11 or newer. Install it, build a graph from a live database, and open the explorer:

pip install 'keygraph[live]'     # or: uvx --from 'keygraph[live]' keygraph ...
keygraph scan --url postgresql://user@host/db --schema public       # read-only metadata scan, writes ./keygraph-out
keygraph ui                                                          # opens keygraph-out/keygraph.html

scan takes any SQLAlchemy URL, so add the driver for your database (for example psycopg for PostgreSQL or pymysql for MySQL). Then ask questions from the command line:

keygraph path customers shipments        # ranked join paths with a JOIN snippet
keygraph search "monthly revenue"        # which tables hold this
keygraph keys orders                     # primary key, unique keys, indexes in column order

To try it without a database, clone the repository and build the bundled fictional webshop (35 tables, three schemas):

git clone https://github.com/alikarami76/keygraph && cd keygraph
uv sync && uv run bash examples/shop/build.sh && uv run keygraph ui --dir examples/shop/out

The build writes graph.json, RELATIONS_REPORT.md, keygraph.html (a self-contained explorer that works from disk, offline), keygraph.db (SQLite with full-text search) and the agent pages areas/*.md and tables/*.md. Details of every step are in How keygraph works (PDF) and examples/shop.

If you cannot connect to the database, build from information_schema dumps instead:

keygraph load --columns columns.jsonl [--statistics stats.jsonl] [--key-columns kcu.jsonl] [--tables tables.jsonl]

Dumps use information_schema field names. --columns-map '{"TABLE_SCHEMA":"db"}', --flatten raw and --where field=value adapt other shapes. Without STATISTICS the tool falls back to COLUMN_KEY (PRI/UNI/MUL), and without KEY_COLUMN_USAGE every relation is inferred. keygraph fetch --cmd 'my-sql-cli --sql {sql}' --out dir fetches those two tables through any read-only command that prints JSON rows.

Supported sources

Each source is a module in keygraph.adapters, read-only by construction. SQL statements pass assert_select (a single SELECT, no write keywords, no INTO OUTFILE or FOR UPDATE); SQLite is read through the SQLAlchemy inspector, and MongoDB and Metabase are limited to the calls listed below.

| Source | What keygraph reads | How you use it | |---|---|---| | MySQL, MariaDB | information_schema (columns, indexes with column order, foreign keys, table facts, enum members) | keygraph scan --url, dumps, or the mysql adapter | | PostgreSQL | information_schema and pg_catalog (indexes, foreign keys, enum types, row estimates, comments, checks) | `keygraph scan