Supabase Markdown

Generate beautiful Mermaid ERD diagrams and markdown documentation from your Supabase database.types.ts file.

Installation

npm install -D supabase-markdown

pnpm add -D supabase-markdown

yarn add -D supabase-markdown

Features

• 📊 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)

Example Output

Mermaid ERD Diagram

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"

Schema Documentation

## Schema: `ecommerce`

### products

#### 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 |

Enhanced Foreign Key Extraction

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.
   • usage: DATABASE_URL=postgres://... npx supabase-markdown
   • or flag: npx supabase-markdown --db-url "postgres://..."

   [!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.
   • Only finds relationships in exposed schemas (usually public).
   • 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.

Quick Start

1. Generate Database Types

First, generate your database.types.ts file using Supabase CLI:

# For local development
npx supabase gen types typescript --local > database.types.ts

# For production
npx supabase gen types typescript --project-id your-project-id > database.types.ts

2. Generate Documentation

# Generate to ./docs directory (default)
npx supabase-markdown

# Generate to custom directory
npx supabase-markdown --output ./documentation

# Use custom types file location
npx supabase-markdown --types-file ./src/types/database.types.ts

# Generate single combined file
npx supabase-markdown --output ./database-overview.md

3. View Your ERD

Open the generated ERD.md 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 schema

Or 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:

export type Database = {
  public: { ... },
  business: { ... }
}

All schemas will be included in the generated ERD and documentation.

Requirements

• Node.js 16+
• A database.types.ts file generated by Supabase CLI

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

Inspired by prisma-markdown by @samchon. This project adapts the concept of generating markdown documentation and ERD diagrams for Supabase databases.

License

MIT © Brandon Ha

Made with ❤️ for the Supabase community