Generate beautiful Mermaid ERD diagrams and markdown documentation from your Supabase database.types.ts file
npm install supabase-markdown
Generate beautiful Mermaid ERD diagrams and markdown documentation from your Supabase database.types.ts file.
``bash
npm install -D supabase-markdown
pnpm add -D supabase-markdown
yarn add -D supabase-markdown
`
- 📊 Mermaid ERD Diagrams - Automatically generate visual database diagrams
- 📚 Schema Documentation - Detailed markdown docs for all tables and relationships
- 🎯 Multi-Schema Support - Works with multiple schemas (business, omx, public, etc.)
- 🔄 Type-Safe - Parses TypeScript types directly from generated files
- 🚀 Zero Config - Works out of the box with Supabase CLI generated types
- 📋 Complete - Includes tables, columns, types, nullability, and relationships
- 🔗 Enhanced FK Support - Optionally inspects database for system relationships (e.g. auth.users)
`mermaid`
erDiagram
ecommerce_orders {
json details
varchar created_at
varchar id PK
varchar user_id "NOT NULL"
}
ecommerce_products {
varchar id PK
varchar name "NOT NULL"
varchar order_id "NOT NULL"
varchar status
}
orders ||--o{ ecommerce_products : "order_id"
`markdownecommerceSchema:
#### Columns
| Column | Type | Nullable |
| -------- | ------ | -------- |
| id | string | ✗ |
| name | string | ✗ |
| order_id | string | ✗ |
| status | string | ✓ |
#### Relationships
| Foreign Key | Column(s) | References | Type |
| ---------------------- | --------- | ---------- | ----------- |
| products_order_id_fkey | order_id | orders.id | One-to-Many |
`
By default, supabase-markdown generates relationships solely from database.types.ts. However, some relationships (especially to system schemas like auth or cross-schema foreign keys) might be missing from the generated types.
To include these missing relationships, you can provide database credentials. The tool follows this priority:
1. Direct Database Connection (Recommended)
- Provides the most complete results, including auth, storage, and other system schemas.DATABASE_URL=postgres://... npx supabase-markdown
- usage:
- or flag:
> [!TIP]
> If you encounter ENOTFOUND or connection errors (common with IPv6-only databases on AWS), use the Transaction or Session pooler connection string instead of the direct connection string.
2. Supabase API (Fallback)
- Uses SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.public
- Only finds relationships in _exposed_ schemas (usually ).
- Does NOT require a direct connection, but is less powerful.
3. Manual Relations
- Create a manualRelations.json file in your project root to manually define missing links.
First, generate your database.types.ts file using Supabase CLI:
`bashFor local development
npx supabase gen types typescript --local > database.types.ts
$3
bash
Generate to ./docs directory (default)
npx supabase-markdownGenerate to custom directory
npx supabase-markdown --output ./documentationUse custom types file location
npx supabase-markdown --types-file ./src/types/database.types.tsGenerate single combined file
npx supabase-markdown --output ./database-overview.md
`$3
Open the generated
file in any markdown viewer that supports Mermaid diagrams (GitHub, VS Code, etc.)Generated Files
After running the generator, you'll find:
-
ERD.md - Beautiful Mermaid ERD diagram showing all tables and relationships
- database-schema.md - Detailed documentation of your database schemaOr a single combined file if you specified a
.md output file.Multi-Schema Support
supabase-markdown automatically detects and documents all schemas in your database:
`typescript
export type Database = {
public: { ... },
business: { ... }
}
`All schemas will be included in the generated ERD and documentation.
Requirements
- Node.js 16+
- A
Contributions are welcome! Please feel free to submit a Pull Request.
Inspired by prisma-markdown by @samchon. This project adapts the concept of generating markdown documentation and ERD diagrams for Supabase databases.
MIT © Brandon Ha
---
Made with ❤️ for the Supabase community