If your database documentation is always behind production, this is for you.
SchemaCrawler Scribe generates structured database documentation directly from live schema metadata, using Google Open Knowledge Format (OKF).
The result is documentation that works for both developers and AI agents, without creating a second documentation workflow.
Source code: SchemaCrawler/schemacrawler-scribe
The Problem SchemaCrawler Scribe Solves
Most teams end up in one of two modes:
- Manual docs that drift from reality
- Generated docs that are hard to read, hard to diff, or hard to reuse
SchemaCrawler Scribe targets the middle ground:
- readable Markdown that developers can review
- structured content that AI systems can parse
- plain text artifacts that belong in version control
This turns documentation into part of your engineering workflow, not a side task.
What You Get With SchemaCrawler Scribe
- AI-agent-friendly database documentation
- Documentation generated directly from schema metadata
- Localized output (German, French, and more)
- Mermaid diagrams embedded in Markdown
- Artifacts that are both human-readable and machine-parseable
- Straightforward use in VS Code and other Markdown tooling
Why Google OKF is a Strong Format for Database Docs
SchemaCrawler Scribe outputs in Google Open Knowledge Format (OKF), which gives you one format that serves multiple use cases:
- Human-friendly: Markdown pages are readable in editors, code review tools, and docs portals
- AI-friendly: structured sections and metadata make extraction and grounding more reliable
- Git-friendly: text output is diffable, reviewable, and easy to version
- Tool-friendly: open format reduces lock-in and keeps migration options open
- Team-friendly: works well in Visual Studio Code and any Markdown-centric workflow
In short: one documentation artifact that supports people, automation, and long-term maintainability.
If You Use SchemaSpy Today, This Will Feel Familiar
SchemaCrawler Scribe is in the same family of tooling as SchemaSpy: both crawl schema metadata and generate browsable documentation.
Like SchemaSpy-style documentation workflows, Scribe covers:
- per-table pages (columns, keys, constraints, triggers, references)
- cross-reference pages (what references what)
- routine documentation (functions and stored procedures)
- relationship visualization (Mermaid in Markdown)
- lint and anomaly reporting in generated output
So if your team already likes auto-generated schema docs and relationship views, SchemaCrawler Scribe keeps that experience while producing Google OKF Markdown artifacts that are easier to review in Git and consume with AI tooling.
Usage
Run standard SchemaCrawler from the command line or Docker. Use the scribe command with okf output format.
Tips:
- Use
--titleto label the generated documentation set - By default, output is zipped; add
--expanded-outputto generate a directory tree instead - Add
--include-lintto generate schema design issue reports
docker run \
--mount type=bind,source="$(pwd)",target=/home/schcrwlr/share \
--rm -it \
schemacrawler/schemacrawler \
/opt/schemacrawler/bin/schemacrawler.sh \
--server=sqlite \
--database=sc.db \
--info-level=maximum \
--command scribe \
--output-format okf \
--title "Books Database" \
--expanded-output \
--include-lint \
--load-row-counts \
--output-file=share/schema
If you are using PowerShell, replace each trailing backslash with a backtick for line continuation.
Top comments (1)
This is a strong direction. Database docs become much more useful for AI when they are versioned and reviewable instead of being a one-time schema dump.
The pieces I’d want in Git for an AI-facing database context layer:
That last part matters because “schema changed” is not the same as “meaning changed.” AI tools need both.
I wrote a related breakdown on schema context for MCP database agents here: https://conexor.io/blog/schema-context-for-mcp-database-agents?utm_source=devto&utm_medium=comment&utm_campaign=engagement
The short version: the model does not just need the database. It needs the map.