Deepsql

The database agent for Postgres and MySQL. Point it at PostgreSQL or MySQL and ask questions in plain English — schema exploration, query generation, slow query analysis, index recommendations, generated dashboards.

You bring the model. DeepSQL ships with no model provider of its own and no vendor account to sign up for. You point it at OpenAI, Azure OpenAI, a LiteLLM proxy, or a model running on your own hardware, and it uses that. Everything else runs in your environment: database credentials are encrypted in a local vault, and nothing leaves the machines you control except the prompts you send to the endpoint you chose.

📄 Read the whitepaper — the architecture and the reasoning behind it.

Quick start

Five steps, in order. Budget about fifteen minutes, most of it waiting on the first build.

1. Check you have what you need

• Docker Engine with Compose v2 and buildx — verify with docker compose version and docker buildx version. Compose delegates builds to buildx and refuses anything older than 0.17.0.
• git, curl and openssl
• ~4 GB of memory available to Docker. The backend JVM is configured with a 3 GB max heap, so a smaller allocation fails in ways that look unrelated.
• An API key for a model provider. See step 3 — you need this before you start, not after.

On a fresh server, one command does all of that:

sudo ./scripts/self-host/bootstrap-server.sh

It handles Debian/Ubuntu and Amazon Linux 2023 / RHEL, installs whatever is missing, and verifies the result before exiting. Worth running even where Docker is already present: a stock dnf install docker on Amazon Linux 2023 ships neither the Compose plugin nor a buildx new enough to build, and the resulting failure surfaces much later, at docker compose up --build, naming neither.

2. Get the code

There are no prebuilt images and no container registry. Compose builds the backend and frontend from your checkout.

git clone https://github.com/DeepSQLAI/deepsql.git
cd deepsql
cp .env.example .env

3. Choose your model

This is the step that matters, and the one thing DeepSQL cannot decide for you.

Open .env and set the chat group. Whatever you pick, the provider id stays openai — there is one provider implementation and it speaks OpenAI, Azure OpenAI, and every OpenAI-compatible server. It dispatches on the shape of your endpoint, not on a name you configure.

Pick the one that matches you:

DEEPSQL_CHAT_PROVIDER=openai
DEEPSQL_CHAT_API_KEY=sk-your-key
DEEPSQL_CHAT_ENDPOINT=https://api.openai.com/v1
DEEPSQL_CHAT_MODEL=gpt-4o

DEEPSQL_CHAT_PROVIDER=openai
DEEPSQL_CHAT_API_KEY=your-azure-openai-key
DEEPSQL_CHAT_ENDPOINT=https://your-resource.cognitiveservices.azure.com/
DEEPSQL_CHAT_MODEL=your-deployment-name

DEEPSQL_CHAT_PROVIDER=openai
DEEPSQL_CHAT_API_KEY=sk-ant-your-key
DEEPSQL_CHAT_ENDPOINT=https://api.anthropic.com/v1
DEEPSQL_CHAT_MODEL=claude-haiku-4-5-20251001

DEEPSQL_CHAT_PROVIDER=openai
DEEPSQL_CHAT_API_KEY=ollama
DEEPSQL_CHAT_ENDPOINT=http://host.docker.internal:11434/v1
DEEPSQL_CHAT_MODEL=llama3.1

DEEPSQL_CHAT_PROVIDER=openai
DEEPSQL_CHAT_API_KEY=sk-your-litellm-virtual-key
DEEPSQL_CHAT_ENDPOINT=http://litellm:4000/v1
DEEPSQL_CHAT_MODEL=your-alias

DEEPSQL_CHAT_PROVIDER gates the whole group: with it unset, no other DEEPSQL_CHAT_* variable is read. That is the most common reason a carefully filled-in .env appears to be ignored.

4. Add embeddings (recommended)

Configured independently of chat, so they can point at a different provider, key or endpoint — which is exactly what you need when your chat model has no embeddings API.

DEEPSQL_EMBEDDING_PROVIDER=openai
DEEPSQL_EMBEDDING_API_KEY=sk-your-key
DEEPSQL_EMBEDDING_ENDPOINT=https://api.openai.com/v1
DEEPSQL_EMBEDDING_MODEL=text-embedding-3-large

Skipping this is survivable — the app starts and retrieval falls back to keyword-only — but answer quality drops noticeably, so treat it as part of setup rather than an extra.

Your embedding model must produce 3072-dimension vectors. rag_documents.embedding is a single vector(3072) column shared by every connection, so text-embedding-3-small (1536) is rejected. Changing width means migrating the column.

5. Install and log in

./scripts/self-host/install.sh

The installer generates your JWT secret, the credential-vault encryption key, the vault DB password, and the DeepSQL Agent provision secret; prompts for the first admin account; builds the backend, frontend, and DeepSQL Agent images; starts the stack; and verifies pgvector is live. The Agent tab and AI dashboard generation are served by the deepsql-agent Compose service — no host-side agent install is required.

The first build takes several minutes — it compiles the Spring Boot backend with Maven inside the container, bundles the frontend with Vite, and builds the DeepSQL Agent image. It has not hung. Later builds reuse the Docker layer cache.

Then open http://localhost:3000 and log in with the admin email and password you entered.

Back up ENCRYPTION_KEY from .env now. It encrypts every database credential you store. Lose it and you re-enter all of them — there is no recovery path.

printf 'SECURITY_JWT_SECRET=%s\n' "$(openssl rand -base64 64 | tr -d '\n')" >> .env
printf 'ENCRYPTION_KEY=%s\n'      "$(openssl rand -base64 32)"             >> .env

docker compose up -d --build

What it does

Your 24/7 DBA and data engineer. It answers BI questions, fixes slow queries, and watches your schema — all from one shared brain.

• Answers BI questions. Ask in plain English. The agent loads your business context, resolves the schema, drafts and validates SQL, then executes it read-only — with every step you can inspect. The hand-written SQL editor is the only path that can mutate, and only for a confirming admin.
• Fixes slow queries. Reads pg_stat_statements or the MySQL slow log, groups queries by fingerprint, ranks them by cost, and flags regressions against their baseline.
• Index recommendations. Advises, and can apply them for you — CREATE INDEX CONCURRENTLY on PostgreSQL, so no table lock.
• Watches your schema. Tracks what changed and what needs attention, so drift surfaces before it breaks a query or a dashboard.
• A brain that knows your business. Teach it your metrics, rules and conventions once — MRR, active accounts, currency handling — and every query, dashboard and recommendation uses the same governed definitions.
• Dashboards without the analyst backlog. An agent writes a single self-contained HTML document, rendered in a sandboxed iframe with no network access. It reads data only through a read-only query bridge back to the backend — the agent gets creative freedom, the database keeps its guard rail.
• Ask it from anywhere. The web UI, your terminal, or a Slack channel. The MCP server gives coding agents (Claude Code, Cursor, Codex, Claude Desktop) the same capabilities over stdio.
• Postgres and MySQL, in your infra. One dialect registry, read-only execution, and SSH tunnelling to reach databases behind a bastion.

Operating the stack

./scripts/self-host/status.sh                    # compose ps + health probes
./scripts/self-host/smoke-test.sh                # end-to-end check against the vault DB
./scripts/self-host/seed-demo-data.sh            # seed demo e-commerce database for exploration
./scripts/self-host/uninstall.sh                 # stop and remove containers, keep data
./scripts/self-host/uninstall.sh --purge-data    # also drop the volumes

Demo Database

To explore DeepSQL features without connecting your own database, run:

./scripts/self-host/seed-demo-data.sh

This creates a demo_shop e-commerce database with:

• 100 products, 500 customers, 5,000+ orders
• Intentionally suboptimal query patterns (to trigger recommendations)
• Pre-configured slow query analysis and index recommendations
• Sample saved queries in the SQL Editor
• Sample agent conversation history

Alternatively, set DEEPSQL_SEED_DEMO_DATA=1 in .env before running install.sh to seed automatically.

Upgrading:

git pull && docker compose up -d --build

Accessing a remote self-hosted instance (SSH tunnel)

If DeepSQL runs on a server you only reach through a bastion/jump host — common in locked-down cloud environments — forward the frontend port locally instead of exposing it to the internet.

Direct bastion, one hop:

ssh -N -L 3100:localhost:3000 -o ExitOnForwardFailure=yes <user>@<bastion-host>

Target host is itself only reachable from inside the bastion's network (two hops): add a Host entry per leg in ~/.ssh/config and let ProxyJump chain them — no manual double-hop command needed.

Host my-bastion
    HostName <bastion-ip-or-dns>
    User <bastion-user>
    IdentityFile ~/.ssh/<bastion-key>

Host deepsql
    HostName <target-host-ip-or-dns>
    Port <target-ssh-port>
    User <target-user>
    IdentityFile ~/.ssh/<target-key>
    ProxyJump my-bastion
    LocalForward 3100 localhost:3000
    ServerAliveInterval 30
    ExitOnForwardFailure yes

ssh -N deepsql

Then open http://localhost:3100. Use a non-3000 local port if something on your machine (often a local Docker container) already binds 3000 — ExitOnForwardFailure=yes makes a port collision fail loudly instead of silently handing you a dead tunnel that looks connected while your browser actually talks to the wrong service.

If the connection hangs at the TCP handshake rather than failing immediately, check, in order: the target's firewall/security-group rules for the SSH port, whether the target host is actually reachable from the bastion (ssh <bastion> "nc -zv <target> <port>"), and only then your local tunnel config — a hung handshake almost always means the network path is blocked somewhere upstream of your laptop, not a misconfigured tunnel.

Ports

Configuration reference

Everything lives in .env, documented inline. The variables that matter most:

Telemetry

The backend can report anonymous install and usage counters to PostHog. No project key ships with this repository, so the sink is a no-op unless you configure deepsql.telemetry.posthog-project-key yourself. DO_NOT_TRACK=1 or DEEPSQL_TELEMETRY_DISABLED=1 disables it outright, as does the admin toggle.

MCP server

mcp/ exposes 44 tools wrapping the backend API, so agents reuse the same orchestration, retrieval and guardrails instead of getting raw database credentials. SQL execution is read-only-enforced before it reaches the backend.

DEEPSQL_API_BASE_URL=http://localhost:8080/api/ \
DEEPSQL_AUTH_TOKEN=<your-deepsql-token> \
npm run mcp:phase1

It has no npm dependencies of its own — npm run mcp:phase1 is just node mcp/deepsql-phase1-server.js, so it runs straight from a fresh clone.

See mcp/README.md for the CLI, editor configuration and the full tool table, and docs/root/MCP_PHASE1.md for rollout notes.

Development

Run the stateful dependencies in Docker — PostgreSQL needs the pgvector extension, which is tedious to install by hand — and everything else natively for hot reload.

docker compose up -d postgres valkey    # requires .env to exist

cd backend && ./mvnw spring-boot:run    # http://localhost:8080/api
npm install && npm run dev              # http://localhost:3000

You need JDK 25 and Node 22. Maven comes from the wrapper (./mvnw), which pins the same version CI uses — no separate install.

The backend needs the same environment as the container: at minimum DB_URL, DB_USERNAME, DB_PASSWORD, SECURITY_JWT_SECRET, ENCRYPTION_KEY, and the DEEPSQL_CHAT_* group. Authentication is on by default in every profile and there is no admin/admin shortcut: either create the first account through the bootstrap flow, or set SECURITY_AUTH_ENABLED=false to let the backend accept unauthenticated API calls while you work on it.

npm run lint                # eslint
npm run build               # production frontend bundle
cd backend && ./mvnw test   # backend test suite

Stack

Spring Boot 4 on Java 25 · React 19 + Vite · PostgreSQL with pgvector · Valkey for caching · nginx.

Documentation

• Whitepaper — architecture and design rationale
• docs/README.md — documentation index
• AGENTS.md — codebase map
• mcp/README.md — CLI and MCP server
• SECURITY.md — reporting a vulnerability

License

Apache 2.0.