dbot

An agent-supported database visualizer and auditor for Supabase and Postgres. Runs locally. Teaches as it works.

dbot is a local-first tool that connects to your Supabase project (or any Postgres-compatible database), renders your schema as a beautiful interactive diagram, runs four deterministic audits — RLS gaps, missing indexes, normalization smells, naming drift — and lets an embedded agent explain the why behind every finding in plain English.

It's built for solo developers who want a polished day-to-day tool and a learning surface that explains database design as you use it.

Note

dbot is alpha-stage. The UX is polished, the audits are real, the agent is grounded in your actual schema — but APIs may change and some edges are still rough. Issues and PRs welcome.

---

Highlights

• Hero schema visualizer — React Flow + ELK orthogonal layout. RLS state, indexes, row counts, and FK relationships in a single dense, readable view.
• Four real audits — missing FK indexes, unused indexes, RLS gaps and overly-permissive policies, repeated columns, nullable-when-required, snake/camel case mixing. Each finding ships with a plain-English why and a SQL fix.
• Schema-grounded agent — paste an Anthropic API key, click any table or finding, and Claude explains it using your real schema as context. No generic advice.
• Local-first — credentials are stored at ~/.dbot/config.json (chmod 600). Nothing routes through a third-party proxy. dbot talks directly to Anthropic and to your database.
• Demo mode — a deliberately-broken synthetic schema lets you explore every feature before connecting anything real.

---

Screenshots

Coming soon — clone and run to see it.

---

Requirements

• Node.js 20+ (uses ESM imports and modern Postgres drivers)
• An Anthropic API key — get one at console.anthropic.com/settings/keys
• A Postgres-compatible database — Supabase, RDS, Neon, self-hosted, anything that speaks the PG wire protocol. (Optional: skip this and try demo mode.)

---

Install and run

git clone https://github.com/YOUR-USERNAME/dbot.git
cd dbot
npm install
npm run build
npm start

This opens http://localhost:54923. On first run you'll land on the onboarding wizard:

1. Welcome — what dbot does and where it stores things.
2. Connect the agent — paste your Anthropic API key. We send a 1-token ping to verify it works, then store it locally.
3. Connect your database — either paste a postgres:// connection string or fill in the host/port/user/password fields. We test the connection before saving.
4. Verify — runs the first introspection so you see real numbers, then drops you into the schema view.

You can re-run onboarding any time from the gear menu in the schema view.

Try demo mode (no credentials needed)

If you want to see what dbot does before connecting anything real:

npm start
# then visit http://localhost:54923/schema?demo=1

Or from the welcome screen click Try the demo first. The demo schema is intentionally broken so every audit lights up.

Running in dev mode (for hacking on dbot itself)

npm run dev    # hot-reload on http://localhost:54923
npm run typecheck
npm run build  # production build

---

How to get your credentials

Anthropic API key

1. Go to console.anthropic.com/settings/keys.
2. Click Create Key, name it something like dbot-local.
3. Copy the key — it starts with sk-ant-.
4. Paste it into the onboarding wizard.

dbot stores this key only in ~/.dbot/config.json on your machine. It is sent only to Anthropic, only when you interact with the agent.

The default model is claude-sonnet-4-6. To override, edit ~/.dbot/config.json and set anthropic.model.

Supabase connection string

1. Open your Supabase project.
2. Project Settings → Database → Connection string.
3. Pick the URI tab (not JDBC), copy it. It looks like:

   postgres://postgres:YOUR_PASSWORD@db.PROJECT.supabase.co:5432/postgres
   

4. Paste it into the onboarding wizard. dbot detects the *.supabase.co host automatically and enables SSL.

The password is the database password you set when creating the project (separate from your Supabase login). Reset it from the same panel if you've forgotten it.

Any other Postgres database

Same flow — paste any postgres://user:password@host:port/database?sslmode=require URI. dbot supports RDS, Neon, Railway, Fly, self-hosted, anything PG-wire compatible.

You can also use the Individual fields tab if you'd rather not deal with URLs.

---

What the audits actually detect

Audit	Catches
Indexes	Foreign keys without a supporting index. Secondary indexes with zero scans on non-trivial tables (potential write overhead).
RLS & Security	Tables with Row Level Security disabled (critical when the table name suggests sensitive data: users, api_keys, billing, etc). Policies that grant USING (true) to the anon role.
Normalization	Columns repeated across multiple tables without a foreign key linking them. Nullable columns whose names suggest they should be NOT NULL (_id, _at, email, status).
Naming	Tables that don't match the project's dominant convention (snake_case vs PascalCase). Single tables that mix snake_case and camelCase columns.

Each finding includes:

• a severity (critical / high / medium / low)
• a plain-English why — the teaching moment
• a SQL suggestion when applicable
• targets that highlight on the diagram when clicked

---

How it works (architecture)

src/
  app/                     # Next.js App Router
    page.tsx                 # Welcome screen
    onboarding/              # 4-step setup wizard
    schema/                  # Hero visualizer
    api/
      agent/chat/            # SSE streaming agent endpoint
      onboarding/{status,anthropic,connection,finish}/
      schema/refresh/
  components/
    flow/                    # React Flow canvas, ELK layout, custom TableNode
    chrome/                  # Sidebar, header, settings menu
    onboarding/Wizard.tsx
    audits/                  # Finding cards and filter tabs
    agent/                   # Chat panel + tiny markdown renderer
    ui/                      # shadcn-style primitives
  lib/
    db/                      # Postgres client + introspection (6 SQL queries → SchemaSnapshot)
    audits/                  # Pure deterministic audit functions
    agent/                   # System prompt + Anthropic streaming client
    config.ts                # ~/.dbot/config.json reader/writer
    demo/seed.ts             # Deliberately-broken demo schema
bin/dbot.ts                # CLI entry (boots Next programmatically)

Audits are deterministic TypeScript, not LLM judgments. Detection is reproducible and fast; the agent's job is explanation, not detection. That keeps audits cheap, predictable, and offline-capable.

Schema introspection runs six parallel queries against pg_catalog and information_schema: tables + columns, primary keys, foreign keys, indexes (with pg_stat_user_indexes for usage stats), RLS state, and pg_policies. The result is a single typed SchemaSnapshot that drives every other surface.

The agent route (/api/agent/chat) prepends the schema snapshot and detected findings to its system prompt, so every answer is grounded in your actual database — no hallucinated tables.

---

Privacy and security

• All credentials are stored on your machine in ~/.dbot/config.json with file mode 600.
• dbot does not route anything through a proxy. The browser talks to a localhost Next.js server, which talks directly to:
  • your database (over TLS for hosted providers), and
  • the Anthropic API (when you interact with the agent).
• Disconnecting the database or clearing the Anthropic key removes them from disk.
• The schema snapshot includes table/column/index/policy metadata and row-count estimates — never row data.

Run dbot only against databases you own or are authorised to inspect. The included audits look at structure and policy, not data.

---

CLI flags

dbot                 Start the local UI on http://localhost:54923
dbot --demo          Skip onboarding and run against the synthetic schema
dbot --port <n>      Bind to a different port (also via DBOT_PORT)
dbot --no-open       Don't auto-open the browser
dbot --help          Show all flags

---

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md for the development setup and what kinds of contributions are most useful right now.

Good first PRs:

• A new audit (e.g. detecting unused columns, oversized text columns, missing created_at/updated_at).
• Polish on the visualizer (better edge routing, per-column tooltips, table search keyboard shortcuts).
• A new database adapter (MySQL, SQLite — current code assumes Postgres).
• Snapshot export (PNG, SVG, or shareable JSON).

---

License

MIT © Yusuf Farah

Anthropic, Claude, Supabase, Postgres, Next.js, React Flow, ELK, and shadcn/ui are trademarks of their respective owners. dbot is not affiliated with any of them.