ChartDB

Last reviewed Sep 13, 2026 · 813 words

The whole ChartDB workflow is: pick your database dialect, copy the query it gives you, run that query in your usual SQL client, paste the JSON it returns into the browser, and look at an ER diagram of your schema. There is no database connection to configure, no credentials handed to a web app, and no agent. That design choice is the reason it is safe to run on any box and the reason it can never do some things people expect of it. Both halves matter.

Import by query is the clever part

The "smart query" is a single SELECT against the database's information schema that emits a JSON description of tables, columns, types, keys, and foreign-key relationships. Because you run it yourself, the app never sees a connection string, works against a production replica you can only reach through a jump host, and is fine with the strictest network policy. Dialects cover PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, ClickHouse, and CockroachDB, and the query for each is version-aware enough that I have not had one fail on a mainstream release. A 200-table schema renders in a few seconds and the auto-layout is good enough to read immediately, which is not something I can say about most ER tools.

Diagrams live in the browser; the server is a static container

This surprises people. The self-hosted container is a static frontend; diagrams are saved to the browser's IndexedDB on the machine you used. Open the same URL from another laptop and the diagram is not there. That is fine for a solo developer sketching a schema, and it is a trap for a team that assumed "self-hosted" meant "shared". The fix is to export: ChartDB writes DBML, JSON, and images, and the DBML file in git is the version of record. Clear your browser's site data without exporting and the diagram is gone. The container itself is a one-liner:

services:
  chartdb:
    image: ghcr.io/chartdb/chartdb:latest
    ports:
      - "8080:80"
    environment:
      - OPENAI_API_KEY=sk-...   # optional, only for AI-assisted DDL export
    restart: unless-stopped

The 512 MB rating is conservative; an nginx container serving a bundle needs a fraction of that, and the actual memory cost lands in the browser tab rendering a large diagram. The OpenAI key is optional and only feeds the AI-assisted export between dialects. Leave it out and the standard DDL export still works. Put it behind your reverse proxy like anything else, though there is nothing on the server worth protecting; the interesting data is in your browser.

What it will not do

No migrations. ChartDB shows you a schema and lets you edit the diagram, and it can emit DDL for the result, but it does not diff the diagram against a live database or generate an ALTER script. It is a design and documentation tool, and the migration step still belongs to Flyway, Alembic, Prisma, or whatever you already use. No live sync either: when the schema changes, you re-run the query and re-import. And no multi-user editing, for the reason above. If you were hoping for a self-hosted replacement for a collaborative schema tool, the dbdiagram.io alternatives page is honest about how close the open-source options get.

The AGPL question

ChartDB is AGPL-3.0. For a tool you run for yourself, that changes nothing. It matters if you were planning to embed it in a product you offer to others as a service, in which case the copyleft reaches your modifications. The licences for self-hosters post covers what that does and does not require, but the short version is that a developer team using it internally has nothing to think about.

Where it sits next to the general-purpose tools

draw.io and Excalidraw will draw an ER diagram, and if you already run one of them and have 12 tables, that is enough. ChartDB earns its container once you have a schema too large to draw by hand or one that changes often enough that re-importing beats re-drawing. For actually querying and browsing the data, pgweb is the lightweight companion; the rest of the dev-tools category covers the heavier admin interfaces.

What I'd do

Run the container on the same host as your other dev tools, skip the OpenAI key, and adopt one rule: every import ends with an export to DBML committed next to the migrations. Use it to onboard new developers, to argue about a redesign on a call, and to document what the database looks like on a given date. Do not expect it to be the source of truth; the database is, and ChartDB is the fastest way I know to look at it.