Getting started¶

Requirements¶

Python ≥ 3.14
An async database driver for your dialect

Install¶

pipuv (from source)

pip install 'db2md[postgres]'   # or [mysql] / [sqlite] / [all]

git clone https://github.com/edwinalkins/db2md.git
cd db2md
uv sync --extra postgres        # or --extra mysql / sqlite / --all-extras

Dialect	Extra	Driver
PostgreSQL	`postgres`	`asyncpg`
MySQL / MariaDB	`mysql`	`aiomysql`
SQLite	`sqlite`	`aiosqlite`

First export¶

db2md --url 'postgresql+asyncpg://user:pass@localhost:5432/postgres'

By default, db2md writes one Markdown file per non-system database under ./schemas/.

# List databases first
db2md --url 'postgresql+asyncpg://user:pass@localhost:5432/postgres' --list

# Document a single database to a specific file
db2md \
  --url 'postgresql+asyncpg://user:pass@localhost:5432/postgres' \
  -d myapp \
  -o ./docs/myapp.md

You can also set DATABASE_URL instead of passing --url.

URL shortcuts¶

Bare dialects are upgraded to async drivers automatically:

Input	Normalized
`postgresql://user:pass@host:5432/postgres`	`postgresql+asyncpg://…`
`mysql://user:pass@host:3306/`	`mysql+aiomysql://…`
`sqlite:///./app.db`	`sqlite+aiosqlite:///./app.db`

What you get¶

Each generated file includes:

A Mermaid erDiagram (with inferred cardinalities)
Tables with columns, defaults, PKs, and comments
Foreign keys, unique constraints, check constraints, and indexes

See Output format and Mermaid cardinalities.