db2md 1.0.0

One URL in. Schema docs out.

Database  →  db2md  →  Markdown  →  Mermaid ER

Connect with any SQLAlchemy URL. Discover databases. Introspect tables, FKs, indexes, and comments. Write one Markdown file per database with a Mermaid ER diagram — no hardcoded names, no config file.

pip install 'db2md[postgres]'
db2md --url 'postgresql+asyncpg://user:pass@localhost:5432/postgres'
# → ./schemas/<database>.md

Full documentation: edwinalkins.github.io/db2md

MkDocs integration: generate into docs/schemas/ then enable Mermaid superfences — see docs/integrate-mkdocs.md.

Why db2md?

Install

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

# From this repo
uv sync --extra postgres

CLI

# List databases (skips system catalogs by default)
db2md --url 'postgresql+asyncpg://user:pass@localhost:5432/postgres' --list

# Document every non-system database → ./schemas/<db>.md
db2md --url 'postgresql+asyncpg://user:pass@localhost:5432/postgres'

# Specific databases / output path
db2md \
  --url 'postgresql+asyncpg://user:pass@localhost:5432/postgres' \
  -d myapp -d analytics \
  -o ./docs/db

uv run db2md --url 'sqlite+aiosqlite:///./app.db' -o ./schemas

Options

Bare dialects are upgraded to async drivers automatically (postgresql://… → postgresql+asyncpg://…, etc.).

Library API

import asyncio
from db2md import list_databases, generate_schema_markdown, export_schemas

URL = "postgresql+asyncpg://user:pass@localhost:5432/postgres"

async def main() -> None:
    dbs = await list_databases(URL)
    name, table_count, md = await generate_schema_markdown(URL, "myapp")
    paths = await export_schemas(URL, "schemas")
    print(dbs, name, table_count, paths)

asyncio.run(main())

Public symbols

Output

Each generated file contains:

1. ER diagram — Mermaid erDiagram with PK/FK markers and cardinalities inferred from the constraints (1–0..1, 1–0..N, N–N)
2. Tables — columns, nullability, defaults, primary keys, comments
3. Foreign keys, unique constraints, check constraints (name + SQL), indexes (columns + UNIQUE)

Example sketch:

# Database schema — `myapp`

> Auto-generated on 2026-08-02 12:00:00 UTC (schema `public`, 2 table(s)).

## ER diagram

```mermaid
erDiagram
    "users" {
        INTEGER id PK "Primary key"
        VARCHAR(255) email
    }
    "notes" {
        INTEGER id PK
        INTEGER user_id FK
        TEXT body "nullable"
    }
    "users" ||--o{ "notes" : "notes_user_id_fkey"
```

## Tables

### `users`

Application users

| Column | Type | Nullable | Default | PK | Comment |
|---|---|---|---|---|---|
| `id` | `INTEGER` | no | — | yes | Primary key |
…

Dialect behaviour

System databases skipped by default:

• PostgreSQL: postgres, template0, template1
• MySQL / MariaDB: mysql, information_schema, performance_schema, sys

Limitations

• Views, materialized views, and sequences are not documented yet (base tables only).
• Mermaid cardinalities are inferred from UNIQUE/PK constraints and FK nullability (junction tables → N–N). Details: docs/mermaid-cardinalities.md.
• Under SQLite, -d / --database does not switch files (one DB per path); a warning is logged.

Development

uv sync --all-extras --group dev
uv run ruff check src tests
uv run mypy src
uv run pytest

# Docs
uv sync --group docs
uv run mkdocs serve

See CONTRIBUTING.md.

License

MIT © edwinalkins