Question 1

What exactly is dbctx?

Accepted Answer

dbctx is an AI powered documentation creation tool for your application database. This documentation is viewable online or accessible by your AI agent (like Claude, ChatGPT, Codex or Claude Code) via a hosted MCP server.

- It looks at your DB's structure (tables, columns and their types) as well as sample data from your database (anonymized) to produce docs.
- Detailed description for each table, column, view, index, and foreign key constraint is generated individually and then improved holistically.
- Table metadata is factored in to aid in grounding the expectations for each column and table. (this is how we do stale-ness detection)
- There are multiple uses of agentic loops to make deductions about your database and then test those assumptions against your database to further improve the docs.
- After each run, the documentation is produced on our servers to assist chatbots and coding agents via MCP connectors.

Question 2

How is this different from [favorite coding agent] with a Postgres MCP?

Accepted Answer

An agent typically gets access to schema structure and sample data, but doesn't get
the overarching story behind the database and the relationships between the tables.

dbctx also looks at the structure and sample data, but uses it to deduce over
3 to 4 passes about the semantic meaning behind the structure and data; then documents
it for your agents.

This allows your agents to reason about on natural language explanations to
instantly know what to write as a query. Tools like the join path finder and semantic
search allows your agents to be token and time efficient and leverage the power of
graph algorithms that is typically not baked into the agents.

Question 3

Can't Claude Code generate a the context itself?

Accepted Answer

Well actually, yes. We are in fact huge fans of Claude Code, because it can do
most things in our work. Just not in one-shot.

dbctx secret sauce is the multiple AI assisted passes that
we do on the deduced semantic meaning. Each pass has its own non-LLM powered
algorithms that cluster, match, refine, or validate claims made by the AI.

Furthermore, the tools exposed via MCP to your agents allow it to leverage
tried and tested algorithms and semantic search at runtime rather than static
file based context.

Question 4

What kind of a database benefits most from using dbctx?

Accepted Answer

Basically, large(r) databases.

- Databases with 100 to 300 tables / views — because at these schema sizes
  agents typically try to take a cautious token efficient route and try to
  assume the data's story early (~3-5 MCP calls)
- Databases without foreign key references (common in prod for performance)

Question 5

What are the major limitations?

Accepted Answer

1. dbctx really falls flat if your database uses JSON/JSONB columns extensively
2. We currently do not support documenting stored procedures and custom functions
3. We don't support databases larger than 300 tables/views.

Question 6

What is counted as an "database object"?

Accepted Answer

1. Tables — Only partition parents, or unpartitioned tables
2. Views — Including Materialized Views

Question 7

Should I run dbctx on a production DB?

Accepted Answer

To be honest, yes. That's when dbctx get's the most context. To be on the safe side, it's wise to point dbctx to a replica server.

Question 8

Do you modify the DBs in any way?

Accepted Answer

Never, we only run SELECT queries; but we do run ANALYZE to force update statistical data from tables. To be on the safe side, only give dbctx read-only + ANALYZE permissions.

Question 9

Will dbctx servers see my DB credentials?

Accepted Answer

Nope, never. We communicate with your DB exclusively via the dbctx terminal client. The credentials are never uploaded to our server.

Question 10

Does your agent execute arbitrary SQL on my DB?

Accepted Answer

No. The exploration queries that we run are run deterministically and are themselves deterministic and predefined in our cli client's code.

For example query trial and generation, we ensure that all queries are prefixed with EXPLAIN (this is prepended in application logic of course) so that the queries aren't actually run on your DB.

Question 11

How does dbctx maintain data anonymity when sampling rows?

Accepted Answer

In two ways:

1. Our agent makes assumptions about which is sensitive or personally identifiable information fields and automatically excludes them before sampling. (the user is shown the list of fields being sampled before sampling)
2. Our client samples each column individually and randomly, i.e. if we happen to sample a two rows from column A, it's highly unlikely the rows would correspond for column B.

Question 12

Which LLM is dbctx using under the hood?

Accepted Answer

We use Anthropic's models. Primarily Claude Opus 4.7, as well an Gemini Flash 3 for lighter tasks.

Question 13

Can I bring my own Claude API key?

Accepted Answer

Yes, but only in the enterprise tier.

Question 14

What happens when I run the command twice on the same DB?

Accepted Answer

We'll charge you for only the DB objects that have been modified since last run.

Note:

1. We maintain the run states on our servers.
2. The pricing is $1 / object / run.

Question 15

What if my schema changes frequently?

Accepted Answer

We only charge you based on objects that has changed. You may run dbctx on CI pipelines (in the near future) if you like.

Question 16

Can I run dbctx as part of my CI pipeline?

Accepted Answer

Not yet but non-interactive mode is on our roadmap.

Question 17

Does it work with managed databases (Supabase, Neon, RDS, Cloud SQL, Aurora, PlanetScale, SkySQL, …)?

Accepted Answer

Yes, of course. dbctx connects over the standard wire protocol for each engine, so any managed offering that exposes Postgres / MySQL / MariaDB works the same as a self-hosted server.

- **PostgreSQL:** Supabase, Neon, Amazon RDS / Aurora Postgres, Google Cloud SQL, Crunchy Bridge, Timescale, etc.
- **MySQL:** Amazon RDS / Aurora MySQL, Google Cloud SQL for MySQL, PlanetScale, etc.
- **MariaDB:** Amazon RDS for MariaDB, SkySQL, etc.

Question 18

How accurate is the phantom foreign key detection?

Accepted Answer

Hard to quantify without a benchmark, but we're working on creating the benchmark dataset. Preliminary tests show, it
performing better than approaches that simply look at naming and schema.

Question 19

How long does a typical run take?

Accepted Answer

In off-peak hours under typical load, we process about 10 tables a minute.

Question 20

Can I pause / resume a run?

Accepted Answer

Sort of. Our initial inspection and sampling is single shot, all subsequent processing happens on the server. If you cancel early after sampling is done but before the docs and MSP is generated, our servers will still produce them. A subsequent run will detect no changes, and return the already created revision.

Run npx dbctx@latest list to attach to a running documentation agent.

Question 21

Do you have a free tier?

Accepted Answer

Yes actually. We don't charge you for the first run of a database that is smaller than 16 tables.

Question 22

What if I hate the generated docs?

Accepted Answer

You're entitled to get your money back. Get in touch with us.

But also, you don't actually pay your first invoice until 7 days later. You can cancel at any time within this period.

Question 23

Will you support data warehouses like BigQuery and Snowflake?

Accepted Answer

We might! We want to. If you have this use-case we'd love to hear from you over email or face-to-face over a call.

Question 24

Can I edit the docs?

Accepted Answer

Not at the moment. We are currently relying on the fully agentic mode to work well (and it does, for the most part). While we are in early experiments to do human in the loop documentation, a web based editor is on our roadmap.

Query & Data Visualization Powers for AI Agents

🔨 Code Better

📈 Analyze Better

🤝 Onboard Better

// HOW TO USE

// AGENT SUPPORT

Semantic Documentation Agent

More Than Just Structure

Tools An Agent Needs

Auto Discovers Phantom Foreign Keys

Auto-categorization

Web Hosted Docs

Stale Table Detection COMING SOON

Example Query Generation COMING SOON

Web Research & OSS Docs COMING SOON

// PRICING

// FAQ

Query & Data Visualization Powers for AI Agents

🔨 Code Better

📈 Analyze Better

🤝 Onboard Better

// HOW TO USE

// AGENT SUPPORT

Semantic Documentation Agent

More Than Just Structure

Tools An Agent Needs

Auto Discovers Phantom Foreign Keys

Auto-categorization

Web Hosted Docs

Stale Table Detection COMING SOON

Example Query Generation COMING SOON

Web Research & OSS Docs COMING SOON

// PRICING

// FAQ

What exactly is dbctx?▾

How is this different from [favorite coding agent] with a Postgres MCP?▾

Can't Claude Code generate a the context itself?▾

What kind of a database benefits most from using dbctx?▾

What are the major limitations?▾

What is counted as an "database object"?▾

Should I run dbctx on a production DB?▾

Do you modify the DBs in any way?▾

Will dbctx servers see my DB credentials?▾

Does your agent execute arbitrary SQL on my DB?▾

How does dbctx maintain data anonymity when sampling rows?▾

Which LLM is dbctx using under the hood?▾

Can I bring my own Claude API key?▾

What happens when I run the command twice on the same DB?▾

What if my schema changes frequently?▾

Can I run dbctx as part of my CI pipeline?▾

Does it work with managed databases (Supabase, Neon, RDS, Cloud SQL, Aurora, PlanetScale, SkySQL, …)?▾

How accurate is the phantom foreign key detection?▾

How long does a typical run take?▾

Can I pause / resume a run?▾

Do you have a free tier?▾

What if I hate the generated docs?▾

Will you support data warehouses like BigQuery and Snowflake?▾

Can I edit the docs?▾