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
• PostgreSQL Enums: Documents pgEnum definitions, including JSDoc comments on the enum and each value
• 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

# DBML output
drizzle-docs generate ./src/db/schema.ts -d postgresql -f dbml -o schema.dbml

Output Format Options

Markdown Format (Default)

The default output format is Markdown, which generates multiple files with an ER diagram. For PostgreSQL schemas with pgEnum definitions, an enums.md file is generated and linked from README.md.

Options specific to Markdown format:

| Option | Description | | ----------------- | ------------------------------------------- | | --single-file | Output as a single file instead of multiple | | --no-er-diagram | Exclude ER diagram from output |

Examples:

# Multiple files with ER diagram (default)
drizzle-docs generate ./src/db/schema.ts -d postgresql -o ./docs

# Single file Markdown
drizzle-docs generate ./src/db/schema.ts -d postgresql --single-file -o schema.md

# Multiple files without ER diagram
drizzle-docs generate ./src/db/schema.ts -d postgresql --no-er-diagram -o ./docs

DBML Format

Use the -f dbml or --format dbml option to generate DBML format.

Examples:

# Output to file
drizzle-docs generate ./src/db/schema.ts -d postgresql -f dbml -o schema.dbml

# Directory - import all schema files from directory
drizzle-docs generate ./src/db/schema/ -d postgresql -f dbml -o schema.dbml

# Watch mode
drizzle-docs generate ./src/db/schema.ts -d postgresql -f dbml -w

Common Options

| Option | Description | | ------------------------- | --------------------------------------------------- | | -o, --output <path> | Output file or directory path | | -d, --dialect <dialect> | Database: postgresql (default), mysql, sqlite | | -f, --format <format> | Output format: markdown (default), dbml | | -w, --watch | Regenerate on file changes | | --force | Overwrite existing files without confirmation |

Relation Detection

Relations are automatically detected from your schema:

• v1 API (defineRelations()): Detected from schema objects at runtime
• v0 API (relations()): Detected by parsing source files

No configuration needed - the tool will use relation definitions when present, or fall back to foreign key constraints.

Example

/** Users table */
export const users = pgTable("users", {
  /** User ID */
  id: serial("id").primaryKey(),
  /** User name */
  name: text("name").notNull(),
});

DBML Output

Table users {
  id serial [pk, increment, note: 'User ID']
  name text [not null, note: 'User name']

  Note: 'Users table'
}

Markdown Output

# users

Users table

## Columns

| Name | Type   | Nullable | Default | Comment   |
| ---- | ------ | -------- | ------- | --------- |
| id   | serial | No       |         | User ID   |
| name | text   | No       |         | User name |

Enum Comments (PostgreSQL)

JSDoc comments on pgEnum definitions and on each value are extracted as well. Pass the schema directory (or the file that defines the enum) as the source so the enum definition is parsed.

/** Lifecycle status of an order */
export const orderStatusEnum = pgEnum("order_status", [
  /** Order has been placed but not yet paid */
  "pending",
  /** Payment confirmed */
  "paid",
]);

// Lifecycle status of an order
Enum "order_status" {
  pending [note: 'Order has been placed but not yet paid']
  paid [note: 'Payment confirmed']
}

## order_status

Lifecycle status of an order

| Value   | Comment                                |
| ------- | -------------------------------------- |
| pending | Order has been placed but not yet paid |
| paid    | Payment confirmed                      |

See examples/ for more detailed output samples.

License

MIT