DEV Community

Ryuya Ikeda
Ryuya Ikeda

Posted on • Originally published at dev.to

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

#typescript #database #drizzle #documentation

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.

GitHub logo rikeda71 / drizzle-docs-generator

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

drizzle-docs-generator

NPM

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
Enter fullscreen mode Exit fullscreen mode

Global Install

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

drizzle-docs generate ./src/db/schema.ts -d postgresql
Enter fullscreen mode Exit fullscreen mode

Usage

Basic Usage

# Markdown output (default)
drizzle-docs generate ./src/db/schema.ts -d postgresql -o ./docs
…
Enter fullscreen mode Exit fullscreen mode
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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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(),
});
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

3. Multi-Dialect Support

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

* -d mysql
* -d postgresql
* -d sqlite
Enter fullscreen mode Exit fullscreen mode

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:

  1. AST Analysis: It converts your schema files into an Abstract Syntax Tree (AST).
  2. Schema Extraction: It identifies Drizzle-specific functions like mysqlTable and parses their arguments.
  3. JSDoc Mapping: It captures the JSDoc nodes associated with each table and column to use as descriptions.
  4. 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.

Happy coding! 🌧️

Top comments (0)