ChartDB: a self-hostable database diagram editor that imports your schema with one query

The problem ChartDB solves: getting a schema picture without a password

Most diagramming tools ask for a database connection: host, port, user, password. That is a hard sell inside a company where the production credentials sit with a platform team, and it is worse for a contractor who has a read replica URL and nothing else. ChartDB takes the opposite route. The README states the project needs "No installations • No Database password required." You run a query the app gives you, take the JSON it returns, and paste that JSON into the editor.

The audience follows from that design. It is for backend engineers who need to explain a schema in a meeting, for people planning a migration between engines, and for anyone who wants an ER diagram of a database they can query but not administer. The README lists PostgreSQL (including Supabase and Timescale), MySQL, SQL Server, MariaDB, SQLite (including Cloudflare D1), CockroachDB and ClickHouse as supported. That is a wide spread for a tool at version 1.20.1.

How the Smart Query import actually works

The flow has four steps, and the README spells them out: choose your database engine, copy the magic query, run it in your database, paste the resulting JSON set into ChartDB. The query is engine-specific because the catalog tables differ; the app hands you the right one after you pick the engine.

On the client side this is a React application. The package manifest shows @monaco-editor/react for the SQL editing surface and the xyflow topics point to the diagram canvas. The repository also depends on @dbml/core and @dbml/parse, so DBML is part of how schema text is parsed rather than a hand-written parser. Nothing in the README describes a server component that holds your schema; the JSON you paste is processed in the browser.

That architecture explains the privacy claim and also its limit. There is no database password because there is no database connection. But a browser-only model means persistence is a browser concern, and the README never describes a server-side project store.

Installing ChartDB locally and running a first import

For a local development checkout, the README gives two commands. The dev server is Vite, so you get hot reload while you work on the editor itself.

npm install
npm run dev

The build script is stricter than a bare bundle: package.json defines build as `npm run lint && tsc -b && vite build`, so a lint warning or a type error stops the build. If you want the AI export features compiled in, the README shows the key being passed at build time:

npm install
VITE_OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> npm run build

For a self-hosted deployment the README publishes a container image. The Dockerfile builds with node:24-alpine and serves the static output from nginx:stable-alpine on port 80, which is why the run command maps 8080 on the host.

docker run -e OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> -p 8080:80 ghcr.io/chartdb/chartdb:latest

After that, open http://localhost:8080, pick your engine, run the generated query, and paste the JSON. If you do not want the analytics call, the README says to add `-e DISABLE_ANALYTICS=true` to the run command.

Pointing ChartDB at a local model instead of OpenAI

The README is explicit that you configure either an OpenAI API key or a custom endpoint and model name, and warns: "Do not mix the two options." The custom path is a build-time and run-time pair, because the endpoint and model are baked into the frontend bundle as VITE_ variables while the container also receives them as environment variables.

docker build \
  --build-arg VITE_OPENAI_API_ENDPOINT=<YOUR_ENDPOINT> \
  --build-arg VITE_LLM_MODEL_NAME=<YOUR_MODEL_NAME> \
  -t chartdb .

docker run \
  -e OPENAI_API_ENDPOINT=<YOUR_ENDPOINT> \
  -e LLM_MODEL_NAME=<YOUR_MODEL_NAME> \
  -p 8080:80 chartdb

The README's example configuration for a local vLLM server uses `http://localhost:8000/v1` as the endpoint and `Qwen/Qwen2.5-32B-Instruct-AWQ` as the model name. Note the duplication: the same values appear once as VITE_ build args and once as runtime environment variables. Getting only one of the two right is an easy way to end up with a build that looks configured but cannot reach the model.

Where ChartDB is the wrong tool

The README labels the project as being in Public Beta. Treat that as the governing constraint. A beta diagram editor is fine for a one-off migration sketch and less fine as the system of record for a schema that forty people edit.

The bigger limitation is the AI export. Dialect conversion, the feature the README calls "AI-Powered Export for Easy Migration," depends on an external model. If your organisation blocks outbound calls to OpenAI and you have no internal inference server, that feature is unavailable, and the README does not describe a non-AI fallback for generating the target dialect. A custom endpoint solves it only if you already run one.

The import model has a cost too. Because you paste JSON rather than connect, the diagram is a point-in-time copy. There is no documented mechanism in the README for detecting that the live schema drifted, so a diagram that is three sprints old looks exactly as authoritative as a fresh one. For a team that wants diagrams that track migrations automatically, this is the wrong shape of tool.

ChartDB compared with drawdb and DBML-based workflows

The most common comparison in search data is ChartDB against drawdb. Both are browser-based diagram editors, and the difference is in the input. ChartDB's headline path is the Smart Query: you pull the schema out of a running database and paste the JSON. A tool built around hand-writing the schema first inverts that order, and it suits a greenfield design where no database exists yet.

The DBML route is a different trade again. ChartDB depends on @dbml/core and @dbml/parse, so DBML is already in its parsing stack, but the README does not present DBML as the primary import format; the primary import is the engine query. If your team already keeps a DBML file in the repository as the canonical schema description, a workflow centred on that file will feel more natural than one centred on a pasted JSON dump, even if ChartDB can read the format.

Neither alternative changes the deployment question. ChartDB ships a Dockerfile and a published image, so self-hosting is a first-class path rather than an afterthought, which matters if the schema cannot leave your network.

Licence, upgrade cost and what the repository does not say

ChartDB is licensed under AGPL-3.0, and the repository carries a CLA.md alongside the contributor guide and code of conduct. AGPL is a copyleft licence with a network clause: if you modify the code and let users interact with it over a network, the licence's source-availability obligation is the thing to read carefully with your own counsel. Running the published container unchanged for internal diagramming is a different situation from forking the editor and offering it as a service. This is a description of the licence, not legal advice.

Upgrade cost looks low on the surface. Releases in the repository are v1.19.0, v1.20.0 and v1.20.1, and the last push to main was on 2026-09-13, so the project is moving. The friction is in the build, not the pull. Because the AI endpoint and model name are compiled into the frontend through VITE_ variables, changing your inference server means rebuilding the image, not restarting a container with a new environment variable. Teams that swap models often will feel that.

The README is silent on several things a self-hoster would want: it does not document where diagrams are persisted, it does not describe a rollback procedure for the container image, and it does not state a supported browser matrix. Verify those against your own deployment before you standardise on it.

Editorial conclusion

Adopt ChartDB if you need a fast, read-only picture of a schema for documentation or a migration discussion, and you are comfortable running a beta tool that stores diagrams in the browser. Do not adopt it if you need a hosted, multi-user diagram service with server-side persistence, or if you cannot configure an OpenAI key or a custom inference endpoint and still expect the dialect conversion export. Before you commit, run the container with DISABLE_ANALYTICS=true, confirm the port mapping you actually want, and test the Smart Query for each database engine in your estate, because the README lists eight supported engines and the query text differs per engine.

Frequently asked questions

Official sources

1. chartdb/chartdb on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases