dbatlas: Database Documentation
One of the most difficult challenges as a data professional is understanding your database’s data model.
Historically, a data professional would need to open up different IDEs, write custom queries to find table relationships, and map out all relationships with Visio.
I have attempted to speed up parts of that process with dbatlas, a python library for database catalogs.
All you have to do is point dbatlas at a database and it will generate useful docs, and serve them locally.
dbatlas has a variety of features out of the box:
generates ERDs, relationships,lineage, profiling and data quality.
supports a variety of outputs: html, markdown, json, yaml, mermaid, graphviz, svg, and zip.
provides convenient cli commands document generation, aiming to be as close to “one click” as possible.
exposes a python API.
has compatibility for multiple databases: duckdb, sqlite, postgres, mysql, snowflake, sql server, and sqlalchemy.
This post will cover its high-level architecture and use cases.
Architecture
To get started with dbatlas, pull the repo down and issue these commands to a DuckDB you are targeting:
uv run dbatlas build --database warehouse.duckdb --output docs
uv run dbatlas serve --config dbatlas.yml
When you run “dbatlas build”, the CLI becomes the entry point to the metadata pipeline. The command loads a config or builds one direct from the warehouse argument. It figures out the connection type, creates the adapter, introspects the database, profiles the tables, infers relationships, and generates the documentation bundle.
Then the command “dbatlas serve” serves the generated static directory over HTTP so you can open the docs in a browser.
I created the database adapter layer because the command needs to work against different databases. DuckDB and SQLite should work easily for local files. Postgres, MySQL, Snowflake, SQL Server, and generic SQLAlchemy URLs should work through configured connections and optional drivers.
The typed metadata graph creates one normalized representation from the adapter layer. Renderers should not care whether the table came from DuckDB or Snowflake. They should care that it is a Table with columns, constraints, indexes, relationships, and profile metadata.
The profiling layer adds context, like summary statistics for tables and columns, to the database schema.
Inference exists because most databases are incomplete. Many warehouses do not declare foreign keys. The command should still produce useful relationship docs when naming patterns (might) exist.
The metadata generated docs adds owners, descriptions, tags, freshness columns, and example SQL.
Renderers create artifacts people can actually use. The same database graph can become searchable HTML, single-file HTML, Markdown, JSON, YAML, Mermaid, Graphviz, SVG ERD, and ZIP output.
You can also issue doc generation commands from the python library:
from dbatlas import Project
project = Project.from_database("warehouse.duckdb", output_directory="docs")
project.build()
Conclusion
Your database already contains a huge amount of useful context.
Tables, columns, types, constraints, indexes, relationships, row counts, and view definitions are all sitting there waiting to be turned into something readable.
Database documentation should not start from scratch.
One dbatlas command should get you from “I have no idea what is in this database” to “I have something I can open, search, read, and share” within minutes.