Stop Manual Documentation: Auto-generate Markdown & DBML from Drizzle ORM

Ryuya Ikeda — Wed, 14 Jan 2026 14:35:44 +0000

Drizzle ORM is gaining massive traction in the TypeScript ecosystem for being lightweight and type-safe. With v1.0 currently in beta, it is becoming a go-to choice for modern web applications.

However, as your project grows, you might face a familiar challenge: The gap between your schema code and your documentation.

To solve this, I built drizzle-docs-generator—a CLI tool that automatically generates Markdown documentation and DBML files directly from your Drizzle schema definitions.

rikeda71 / drizzle-docs-generator

CLI tool to generate DBML or markdown document from Drizzle ORM schemas.

drizzle-docs-generator

CLI tool to generate DBML and Markdown documentation from Drizzle ORM schemas. Extracts JSDoc comments and outputs them as Note clauses.

Features:

Directory Import Support: Import all schema files from a directory
No File Extension Required: Works with extensionless imports (e.g., import { users } from './users')
JSDoc Comments: Automatically extracts and converts to DBML Notes
Relations Support: Generate refs from relations() or defineRelations()
Watch Mode: Auto-regenerate on file changes
Multiple Output Formats: Markdown (default) and DBML with ER diagrams

日本語版READMEはこちら

Install

Local Install (recommended)

# As a dev dependency
npm install --save-dev drizzle-docs-generator
# or
pnpm add -D drizzle-docs-generator

# Then use with npx
npx drizzle-docs generate ./src/db/schema.ts -d postgresql

Global Install

npm install -g drizzle-docs-generator
# or
pnpm add -g drizzle-docs-generator

drizzle-docs generate ./src/db/schema.ts -d postgresql

Usage

Basic Usage

# Markdown output (default)
drizzle-docs generate ./src/db/schema.ts -d postgresql -o ./docs

…

View on GitHub

The Problem: The Documentation Drift

If you use Drizzle to manage your database, you’ve likely experienced these frustrations:

Forgotten Updates: You modified the schema but forgot to update the Notion or Confluence wiki.
Redundant Work: You’re writing JSDoc comments in your code, then manually re-typing them into a separate document.
Black Box Columns: Without documentation, teammates have to dig through .ts files to understand what a specific column does.

Drizzle does not currently have a built-in documentation generator. While drizzle-kit handles migrations beautifully, its DDL generation doesn't fully support comment clauses yet.

Note: There is an open issue for comment support (#886), but it is not yet finalized in the v1 roadmap as of early 2026.

Introducing drizzle-docs-generator

drizzle-docs-generator solves these issues by acting as a single source of truth. By integrating this tool into your CI/CD pipeline, your documentation remains in lockstep with your code changes.

Installation

$ npm install -D drizzle-docs-generator
# or using pnpm
$ pnpm add -D drizzle-docs-generator

Key Features

1. Markdown Documentation with Mermaid ER Diagrams

Generate comprehensive documentation including table lists, column details, and visual diagrams.

$ drizzle-docs generate ./src/db/schema.ts -d mysql -f markdown -o ./docs

The tool creates a README.md with a Mermaid-based ER diagram (which renders automatically on GitHub/GitLab) and separate table-specific .md files. These files detail constraints, indexes, and relations.

The generator pulls directly from your JSDoc comments:

export const users = mysqlTable("users", {
    /** User's display name */
    name: varchar("name", { length: 100 }).notNull(),
});

2. DBML Support for Visual Tools

DBML (Database Markup Language) is a standard for defining database schemas. You can export your Drizzle schema to DBML and import it into tools like dbdiagram.io or dbdocs.io.

$ drizzle-docs generate ./src/db/schema.ts -d mysql -f dbml -o schema.dbml

3. Multi-Dialect Support

The tool supports MySQL, PostgreSQL, and SQLite. Specify your database using the -d flag:

* -d mysql
* -d postgresql
* -d sqlite

4. Drizzle v1 (Beta) Compatibility

Drizzle v1 introduced a new way to define relations. drizzle-docs-generator supports both the legacy (v0) and the new v1/v2 relation syntax.

How it works under the hood

The tool leverages the TypeScript Compiler API to parse your schema files without actually running the code:

AST Analysis: It converts your schema files into an Abstract Syntax Tree (AST).
Schema Extraction: It identifies Drizzle-specific functions like mysqlTable and parses their arguments.
JSDoc Mapping: It captures the JSDoc nodes associated with each table and column to use as descriptions.
Relation Mapping: It parses the relations() function calls to understand how your tables are linked.

Conclusion

Automating your documentation saves time and reduces the risk of human error. If you are using Drizzle ORM, I hope drizzle-docs-generator helps your team keep your database architecture clear and accessible.

I’d love to get your feedback! Feel free to leave a star, open an issue, or submit a PR on GitHub.

GitHub Repository: https://github.com/rikeda71/drizzle-docs-generator
NPM Package: https://www.npmjs.com/package/drizzle-docs-generator

Happy coding! 🌧️

DEV Community: Ryuya Ikeda