# Liam ERD

---
title: Welcome to Liam ERD
description: Liam ERD is a tool that effortlessly generates beautiful and easy-to-read ER diagrams.
---

import { Package, Globe } from "lucide-react";
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; // For package-install code blocks

![Liam logo](/images/liam_erd.png)

Liam ERD is an open-source tool that instantly generates beautiful, interactive ER diagrams from your database. Whether you’re working on public or private repositories, Liam ERD helps you visualize complex schemas with ease.

## Why Choose Liam ERD?

- **Beautiful UI & Interactive**: A clean design and intuitive features (like panning, zooming, and filtering) make it easy to understand even the most complex databases.
- **Simple Reverse Engineering**: Seamlessly turn your existing database schemas into clear, readable diagrams.
- **Effortless Setup**: Get started with zero configuration—just provide your schema, and you’re good to go.
- **High Performance**: Optimized for both small and large projects, easily handling 100+ tables.
- **Fully Open-Source**: Contribute to the project and shape Liam ERD to fit your needs.

## Supported Formats

Liam ERD supports a variety of schema formats. For a detailed and up-to-date list, check out [Supported Formats](/docs/parser/supported-formats).

## How to Get Started

### Public Project Setup

Want a quick setup for a public repository?
For example, if the schema file you want to explore is hosted at the following URL:

```
# A public repo's schema file
https://github.com/docusealco/docuseal/blob/master/db/schema.rb
```

You can generate an ER diagram by inserting `liambx.com/erd/p/` into the URL:

```
https://liambx.com/erd/p/github.com/docusealco/docuseal/blob/master/db/schema.rb
      👾^^^^^^^^^^^^^^^^^👾
```

For detailed instructions, check out [Web version](/docs/web).

### Private Project Setup

For internal or private repositories, run this command to start an interactive setup:

```package-install
npx @liam-hq/cli init
```

Then follow the prompts to build a static version of your diagrams.

For more info, see [CLI version](/docs/cli).

## Need More?

- **Feature Requests & Ideas**: Share your thoughts on our [GitHub Discussions](https://github.com/liam-hq/liam/discussions).
- **Roadmap**: Check our latest progress on the [Roadmap](https://github.com/orgs/liam-hq/projects/1/views/1).


---
title: CI/CD Integration
---

import { File, Folder, Files } from "fumadocs-ui/components/files";

## Overview

By integrating Liam ERD into your CI/CD pipeline, you can **automatically generate ER diagrams on every commit and host their latest versions**.  
This ensures that your entire team and all stakeholders can consistently access the most up-to-date database structure.

### Why is Hosting the Latest ER Diagram Important?

- **Streamlined Onboarding**  
  When new or cross-functional team members need to understand the database structure, there’s no need to dig through source code or spreadsheets. The information is consistently available and always current.
- **Improved Communication**  
  Visual representations of the data structure make it easier to discuss, clarify, and align on database design among developers, product managers, customer support, data analysts, and more.
- **Drawbacks of Manual Updates**  
  Manually maintaining ER diagrams can lead to oversights, typos, and inconsistent documentation, making it **difficult to stay up to date**. By automatically generating and hosting ER diagrams via CI/CD, you reduce human errors and management overhead, guaranteeing **accurate information at all times**.

## Example: GitHub Actions + Static Hosting

Because Liam ERD is built as a Vite-based SPA, it can be deployed on **any static hosting service**. Below is an example showing how to automatically build and deploy ER diagrams using GitHub Actions:

```yaml
name: Deploy ERD on every commit

on:
  push:
    branches:
      - main
    # If you only want to trigger this when the schema file is updated:
    # paths:
    #   - db/schema.rb
    #   - db/structure.sql
    #   - prisma/schema.prisma

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # 1. Install the Liam ERD CLI
      - name: Install Liam ERD CLI
        run: npm install -g @liam-hq/cli

      # 2. Generate the ER diagram
      - name: Generate ER Diagram
        run: liam erd build --input ./db/schema.rb --format=schemarb

      # 3. Publish the build artifacts (dist folder) to a static hosting service
      #    Here, we show an example using GitHub Pages.
      # NOTE: To keep your GitHub Pages site private, 
      # your organization must be on GitHub Enterprise Cloud.
      - name: Deploy to GitHub Pages
        uses: actions-gh-pages/action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: dist
```

<Callout title="info" type="info">You can use either `npx @liam-hq/cli erd build` or `liam erd build` (if installed globally) to run the Liam ERD CLI.</Callout>

The same approach can be applied to hosting services such as [Cloudflare Pages](https://www.cloudflare.com/developer-platform/products/pages/), [Vercel](https://vercel.com/), and [Netlify](https://www.netlify.com/).

## Liam ERD’s HTML Structure (Vite-based SPA)

When you run `npx @liam-hq/cli erd build` or `liam erd build`, a `./dist` directory is created with the following structure. Here, `index.html` acts as the single entry point for your **single-page application (SPA)**:

<Files>
  <Folder name="dist" defaultOpen>
    <Folder name="assets" defaultOpen>
      <File name="favicon-xxxxxxxx.ico" />
      <File name="index-xxxxxxxx.css" />
      <File name="index-xxxxxxxx.js" />
    </Folder>
    <File name="favicon.ico" />
    <File name="index.html" />
    <File name="schema.json" />
  </Folder>
</Files>

The `schema.json` file contains the parsed schema data in JSON format, which `index.html` reads to render the ER diagram.  

Additional notes:

- You can place these files under a subdirectory if needed.  
- This output is similar to a typical Vite-built SPA. Refer to [Deploying a Static Site (Vite official documentation)](https://vite.dev/guide/static-deploy.html) for more details on deployment to common hosting providers.

## Using the `init` Command

The `init` command in the [Liam ERD CLI](/docs/cli) provides an interactive way to generate configuration files or GitHub Actions templates tailored to your project, automatically handling tasks like:

- Specifying the input file (`--input`) and schema format (`--format`)
- Generating sample GitHub Actions workflows

If you’re new to Liam ERD or unsure about configurations, simply run:

```bash
npx @liam-hq/cli init
```

Follow the on-screen prompts to set up Liam ERD quickly.

## Example: Prisma + GitHub Actions + Cloudflare Pages

Below is a more advanced example using `schema.prisma` with GitHub Actions to generate and deploy ER diagrams to Cloudflare Pages.  
Cloudflare Pages supports simple access restrictions via Cloudflare Access, enabling you to limit diagram visibility to internal team members only.

```yaml
name: Deploy ERD (Prisma) to Cloudflare Pages

on:
  push:
    branches:
      - main
    # NOTE: If you only want to trigger this when the schema file is updated:
    paths:
      - prisma/schema.prisma

jobs:
  build-and-deploy-erd:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      deployments: write

    steps:
      - uses: actions/checkout@v4
      - name: Generate ER Diagrams
        run: npx @liam-hq/cli erd build --input prisma/schema.prisma --format prisma
      - name: Deploy ERD to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN_SAMPLE_PRISMA }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID_SAMPLE_PRISMA }}
          command: pages deploy ./dist --project-name=prisma-with-cloudflare-pages
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
```

We plan to share more examples for other static hosting platforms. The above workflow is adapted from [Deploy ERD to Cloudflare Pages Sample](https://github.com/liam-hq/liam-erd-samples/blob/main/.github/workflows/prisma-with-cloudflare-pages.yml). To see more examples, visit [Liam ERD Samples](https://github.com/liam-hq/liam-erd-samples).

## Common Pitfalls

### Security and Privacy
- If you are using a static hosting service like Cloudflare Pages, Vercel, or Netlify, **avoid exposing your private repository schema** by default.
- Configure organizational authentication so that **only internal members** can view it.

## Conclusion

Integrating Liam ERD into your CI/CD pipeline is a **powerful way** to share **“the most up-to-date ER diagram based on your latest DB schema”** across the entire team.

- By automatically building and hosting ER diagrams, you **reduce manual workload and human errors** while ensuring that database documentation is always current.
- This approach improves development, maintenance, and onboarding, ultimately boosting overall team productivity.

Try incorporating Liam ERD into your CI/CD workflow and experience the benefits of **automated ER diagram management** firsthand!


---
title: Liam ERD CLI
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; // For package-install code blocks

## Quick Start

The fastest way to get started with Liam ERD is using the interactive setup command:

```package-install
npx @liam-hq/cli init
```

## Manual Setup

For more control over the ERD generation process, you can use the `erd` command directly:

### Basic Usage

Generate an ERD from your schema file using the following command:

```package-install
npx @liam-hq/cli erd build --input <path|url>
```

This command processes your schema file and generates interactive ERD visualization files in the `dist` directory. The schema format is automatically detected (see [Format Auto-Detection](/docs/parser/supported-formats#format-auto-detection)), but you can override it using the `--format` option if needed.

Once the ERD is generated, you can view it by serving the files using a local HTTP server:

```package-install
npx http-server dist
```

The server will start and provide you with a local URL (typically http://localhost:8080) where you can view your ERD in a web browser.

You can use any hosting service of your choice to serve the generated files.

### Options

- `--input <path|url>`: Path to your schema file or URL
- `--format <format>`: (Optional) Override the auto-detected schema format

### From GitHub Public Repository

You can directly specify URLs to schema files stored in public GitHub repositories. Using raw URLs allows you to generate ERDs directly from remote schema files.

```package-install
npx @liam-hq/cli erd build --input https://github.com/user/repo/blob/main/examples/schema.sql --format postgresql
```

```package-install
npx @liam-hq/cli erd build --input https://raw.githubusercontent.com/user/repo/main/examples/schema.sql --format postgresql
```


### Output

The command generates a simple web application using [Vite](https://vite.dev/), which includes JavaScript, CSS, and HTML files, in the `dist` directory of your current working directory.

To view the generated ERD, serve the `dist` directory using any HTTP server:

```package-install
npx http-server dist
```

## Sample Projects

For sample projects and setup examples, check out our [liam-erd-samples](https://github.com/liam-hq/liam-erd-samples) repository.


---
title: Community Resources
description: A collection of community-created resources and articles about Liam ERD
---

## Using Liam ERD with Databases

### MySQL

- [Liam ERD で tbls からサクッと MySQL の ER 図を作成してみた](https://zenn.dev/nextbeat/articles/liam-erd-tbls-mysql)
  - February 2024 • zenn.dev • [translated](https://zenn-dev.translate.goog/nextbeat/articles/liam-erd-tbls-mysql?_x_tr_sl=auto&_x_tr_tl=ja&_x_tr_hl=ja&_x_tr_pto=wapp&_x_tr_hist=true)
  - A guide to generating MySQL ER diagrams using Liam ERD with tbls
  - Includes practical examples using the sakila sample database

## Contributing

Have you written about Liam ERD? We'd love to add your content to this list! Please submit a PR with the following information:

- Title of your article/resource
- Publication date (Month YYYY), domain, translated version(if not in English)
- Brief description (1-3 lines)


---
title: Contributing
description: Learn how to contribute to Liam ERD
---

import { source } from "@/lib/source"
import { DocsCategory } from "fumadocs-ui/page"

<DocsCategory page={source.getPage(["contributing"])} from={source} />


---
title: Repository Architecture
description: This document provides a detailed overview of our repository structure, architecture, and development workflow.
---

# Tech Stack

Liam is built using a modern JavaScript/TypeScript stack with a focus on React and Next.js. Here's an overview of our technology stack:

## Core Technologies
- **TypeScript**: Strongly-typed programming language that builds on JavaScript
- **React 18**: UI library for building component-based interfaces
- **Next.js 15**: React framework for server-rendered applications
- **Vite**: Build tool used in CLI for static site generation

## Frontend
- **UI Components**: Custom component library with Radix UI primitives
- **Styling**: CSS Modules with typed definitions
- **Icons**: Lucide React for consistent iconography
- **State Management**: Valtio for state management
- **Visualization**: @xyflow/react (React Flow) for diagram visualization
- **Documentation**: Fumadocs for documentation site

## Database Schema Parsing
- **Parsers**: Support for multiple database schema formats
- **Validation**: Valibot for schema validation

## Development Tools
- **Package Management**: pnpm for efficient dependency management
- **Monorepo Management**: pnpm workspaces
- **Build System**: Turborepo for optimized builds
- **Linting & Formatting**: Biome for code quality
- **Testing**: Vitest for unit testing, Playwright for e2e testing

## Deployment
- **Web Applications**: Deployed with Vercel
- **CI/CD**: GitHub Actions for continuous integration

## Overview

Our project uses a monorepo structure managed with pnpm workspaces, allowing us to maintain multiple packages and applications in a single repository while sharing dependencies and code.

## Repository Structure

```text
/
├── frontend/
│   ├── apps/
│   │   ├── docs/              # Documentation site (@liam-hq/docs)
│   │   │   ├── content/       # MDX documentation files
│   │   │   └── app/            # Next.js app router
│   │   │   └── components/          # Documentation site components
│   │   └── app/          # Main web application (@liam-hq/app)
│   │       ├── app/      # Next.js app router
│   │      └── components/
│   │       └── public/       # Static assets
│   └── packages/
│       ├── cli/              # Command-line tool (@liam-hq/cli)
│       │   ├── src/
│       │   └── package.json
│       ├── configs/          # Shared configurations (@liam-hq/configs)
│       │   ├── biome/
│       │   ├── tsconfig/
│       │   └── package.json
│       ├── db-structure/     # Database structure parser (@liam-hq/db-structure)
│       │   ├── src/
│       │   │   ├── parser/
│       │   │   └── utils/
│       │   └── package.json
│       ├── erd-core/         # Core ERD functionality (@liam-hq/erd-core)
│       │   ├── src/
│       │   │   ├── components/
│       │   │   ├── hooks/
│       │   │   └── utils/
│       │   └── package.json
│       └── ui/               # UI component library (@liam-hq/ui)
│           ├── src/
│           │   ├── components/
│           │   └── styles/
│           └── package.json
└── package.json             # Root package (liam-frontend)
```

## Packages

This section describes the main responsibilities and relationships between packages in our monorepo. Each package is designed to be modular and focused on specific functionality.

### Web Application (`@liam-hq/app`)

Next.js App Router based web application for exploring ER diagrams. see: [/docs/web](/docs/web)

**Key Responsibilities:**

- Interactive ERD interface
- Schema file URL parsing
- Server Components optimization

### CLI Package (`@liam-hq/cli`)

Command-line tool for generating static ERD visualization files. see: [/docs/cli](/docs/cli)

**Key Responsibilities:**

- Interactive project setup via `init` command
- Static site generation with Vite

### DB Structure Package (`@liam-hq/db-structure`)

Database schema parser supporting multiple formats. see: [/docs/parser/supported-formats](/docs/parser/supported-formats)

**Key Responsibilities:**

- Multiple format parser implementations
- Automatic format detection
- Type-safe schema validation

### ERD Core Package (`@liam-hq/erd-core`)

React Flow based ERD visualization components and logic. see: [/docs/ui-features](/docs/ui-features)

**Key Responsibilities:**

- ERD Visualization
- UI Components
- State Management

### UI Package (`@liam-hq/ui`)

Base UI component library.

**Key Responsibilities:**

- Reusable components
- Design systems

**Tech Stack:**

- CSS Modules
- Radix UI
- Lucide Icons

### Documentation Site (`frontend/apps/docs`)

Built with [Fumadocs](https://fumadocs.vercel.app/).

**Key Responsibilities:**

- User documentation
- Contribution guides

### Development Tools

- **Linting & Formatting**: Biome
- **Testing**: Vitest
- **Build Tool**: Turborepo


{
  "pages": [
    "index",
    "ui-features",
    "web",
    "cli",
    "parser",
    "contributing",
    "community-resources"
  ]
}


---
title: Parser
---

TBD


{
  "pages": ["supported-formats", "troubleshooting"]
}


---
title: BigQuery
---

Currently, BigQuery is supported through the tbls integration. While direct BigQuery support is not yet implemented, you can use tbls as a workaround to generate schema documentation for your BigQuery datasets.

## Using tbls with BigQuery

1. First, install tbls by following the [installation instructions](https://github.com/k1LoW/tbls?tab=readme-ov-file#install)

2. Set up Google Cloud authentication:

   - Create a service account and download the JSON key file
   - Set the environment variable: `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"`

3. Use tbls to generate a schema.json file from your BigQuery dataset:

```bash
tbls out -t json -o schema.json "bigquery://project-id/dataset-id"
```

Replace the following with your BigQuery details:

- `project-id`: Your Google Cloud project ID
- `dataset-id`: Your BigQuery dataset ID

4. Use the generated schema.json with Liam:

```bash
npx @liam-hq/cli erd build --format=tbls --input schema.json
```

For more details about using tbls format, see the [tbls documentation](/docs/parser/supported-formats/tbls#using-tbls-json-output).

## Direct BigQuery Support

Direct BigQuery support is planned but not yet implemented. If you're interested in this feature, please follow or contribute to the discussion on [GitHub](https://github.com/liam-hq/liam/discussions/364).


---
title: Django ORM
---

Django ORM is supported through PostgreSQL integration. You can use Django's ORM to define your database models and then extract the schema using pg_dump for use with Liam ERD.

## Using Django ORM with Liam ERD

1. Set up a Django project with PostgreSQL as the database backend:

```python
# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'your_database_name',
        'USER': 'your_database_user',
        'PASSWORD': 'your_database_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}
```

2. Define your models using Django's ORM:

```python
# models.py
from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField(unique=True)
    
    def __str__(self):
        return self.name

class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='posts')
    
    def __str__(self):
        return self.title
```

3. Apply migrations to create the database schema:

```bash
python manage.py makemigrations
python manage.py migrate
```

4. Extract the schema using pg_dump:

```bash
pg_dump --schema-only --no-privileges --no-owner --file=schema.sql postgres://username:password@localhost:5432/your_database_name
```

5. Use Liam CLI to build an ER diagram:

```bash
npx @liam-hq/cli erd build --format postgres --input schema.sql
```

## Sample Implementation

You can find a sample implementation of Django ORM with Liam ERD on GitHub:

- GitHub Actions: [.github/workflows/django-with-postgres.yml](https://github.com/liam-hq/liam-erd-samples/blob/main/.github/workflows/django-with-postgres.yml)
- Django project: [samples/django-with-postgres](https://github.com/liam-hq/liam-erd-samples/tree/main/samples/django-with-postgres)

The sample project demonstrates how to:
- Set up a Django project with PostgreSQL
- Define models using Django's ORM
- Extract the schema using pg_dump
- Use the extracted schema with Liam ERD

## Under the Hood

Django ORM generates SQL for PostgreSQL, which is then parsed by Liam ERD using the PostgreSQL parser. For more details about PostgreSQL support, see the [PostgreSQL documentation](/docs/parser/supported-formats/postgresql).


---
title: Drizzle
---

TBD


---
title: Supported Formats
---

**Legend**

- ✅: Supported
- ⚡: Supported via workaround
- ⛔: Not in progress
- ⌛️: In progress

Below is a list of currently supported (or planned) formats and integrations.

- **Web Support**: Support status for the web version.
- **CLI Support**: Support status for the CLI version. ⚡ indicates support through workarounds (e.g., using pg_dump or tbls).
- **Identifier**: Used for specifying the format in the CLI (via `--format=postgresql`) or as a web query parameter (e.g., `?format=schemarb`).

| Technology                                              | Web Support | CLI Support | Identifier   |
| ------------------------------------------------------- | ----------- | ----------- | ------------ |
| [PostgreSQL](/docs/parser/supported-formats/postgresql) | ✅          | ✅          | `postgresql` |
| [Ruby on Rails](/docs/parser/supported-formats/rails)   | ✅          | ✅          | `schemarb`   |
| [Prisma](/docs/parser/supported-formats/prisma)         | ✅          | ✅          | `prisma`     |
| [tbls](/docs/parser/supported-formats/tbls)             | ✅          | ✅          | `tbls`       |
| [Drizzle](/docs/parser/supported-formats/drizzle)       | ⛔          | ⚡          | -            |
| [MySQL](/docs/parser/supported-formats/mysql)           | ⛔          | ⚡          | -            |
| [SQLite](/docs/parser/supported-formats/sqlite)         | ⛔          | ⚡          | -            |
| [BigQuery](/docs/parser/supported-formats/bigquery)     | ⛔          | ⚡          | -            |

For CLI support marked with ⚡, you can use the following workarounds:

- Generate a PostgreSQL file using pg_dump ([see instructions](/docs/parser/supported-formats/postgresql#using-a-pg_dump-generated-sql-file)), then process it with the `postgresql` format
- Generate a schema.json using tbls ([see instructions](/docs/parser/supported-formats/tbls#using-tbls-json-output)), then process it with the `tbls` format

## Format Auto-Detection

Liam ERD automatically attempts to determine the schema format for both Web and CLI versions. The detection process works as follows:

- **File Name Check**: Filenames such as `schema.rb` or `Schemafile` are assumed to be in **`schemarb`** format.
- **File Extension Check**: Files ending in **`.rb`** are treated as **`schemarb`**, while files ending in **`.sql`** are treated as **`postgresql`**.
- For more details, refer to the [`detectFormat.ts`](https://github.com/liam-hq/liam/blob/main/frontend/packages/db-structure/src/parser/supportedFormat/detectFormat.ts) file in our GitHub repository.

If the automatic detection does not match your desired format, you can specify it manually:
- **Web**: Use the `format` query parameter (e.g., `?format=schemarb`)
- **CLI**: Use the `--format` option (e.g., `--format=schemarb`)

If there's another database schema or ORM you'd love to see supported, please let us know in the [GitHub Discussions](https://github.com/liam-hq/liam/discussions/364).


---
title: Microsoft SQL Server
---

Currently, Microsoft SQL Server (MSSQL) is supported through the tbls integration. While direct MSSQL support is not yet implemented, you can use tbls as a workaround to generate schema documentation for your MSSQL database.

## Using tbls with Microsoft SQL Server

1. First, install tbls by following the [installation instructions](https://github.com/k1LoW/tbls?tab=readme-ov-file#install)

2. Use tbls to generate a schema.json file from your MSSQL database:

```bash
tbls out -t json -o schema.json "mssql://dbuser:dbpass@hostname:1433/dbname"
```

Replace the following with your database details:

- `dbuser`: Your MSSQL username
- `dbpass`: Your MSSQL password
- `hostname`: Your database host (e.g., localhost)
- `1433`: Port number (default is 1433)
- `dbname`: Your database name

3. Use the generated schema.json with Liam:

```bash
npx @liam-hq/cli erd build --format=tbls --input schema.json
```

You can find sample implementations for this case on GitHub:

- GitHub Actions: [.github/workflows/mssql-with-tbls.yml](https://github.com/liam-hq/liam-erd-samples/blob/main/.github/workflows/mssql-with-tbls.yml)
- tbls project: [samples/mssql-with-tbls](https://github.com/liam-hq/liam-erd-samples/tree/main/samples/mssql-with-tbls)

For more details about using tbls format, see the [tbls documentation](/docs/parser/supported-formats/tbls#using-tbls-json-output).

## Direct MSSQL Support

Direct MSSQL support is planned but not yet implemented. If you're interested in this feature, please follow or contribute to the discussion on [GitHub](https://github.com/liam-hq/liam/discussions/364).


---
title: MySQL
---

Currently, MySQL is supported through the tbls integration. While direct MySQL support is not yet implemented, you can use tbls as a workaround to generate schema documentation for your MySQL database.

## Using tbls with MySQL

1. First, install tbls by following the [installation instructions](https://github.com/k1LoW/tbls?tab=readme-ov-file#install)

2. Use tbls to generate a schema.json file from your MySQL database:

```bash
tbls out -t json -o schema.json "mysql://dbuser:dbpass@hostname:3306/dbname"
```

Replace the following with your database details:

- `dbuser`: Your MySQL username
- `dbpass`: Your MySQL password
- `hostname`: Your database host (e.g., localhost)
- `3306`: Port number (default is 3306)
- `dbname`: Your database name

3. Use the generated schema.json with Liam:

```bash
npx @liam-hq/cli erd build --format=tbls --input schema.json
```

You can find sample implementations for this case on GitHub:

- GitHub Actions: [.github/workflows/mysql-with-tbls.yml](https://github.com/liam-hq/liam-erd-samples/blob/main/.github/workflows/mysql-with-tbls.yml)
- tbls project: [samples/mysql-with-tbls](https://github.com/liam-hq/liam-erd-samples/tree/main/samples/mysql-with-tbls)

For more details about using tbls format, see the [tbls documentation](/docs/parser/supported-formats/tbls#using-tbls-json-output).

## Direct MySQL Support

Direct MySQL support is planned but not yet implemented. If you're interested in this feature, please follow or contribute to the discussion on [GitHub](https://github.com/liam-hq/liam/discussions/364).


---
title: PostgreSQL
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; // For package-install code blocks

To use Liam ERD in a PostgreSQL environment, you can simply parse an `.sql` file generated by commands such as `pg_dump --schema-only`. Below is a guide on how to create an ER diagram using a PostgreSQL dump file.

## Using a pg_dump-generated SQL File

For example, you can dump only the database schema into a file named `schema.sql` with the following command:

```bash
pg_dump --schema-only --file=schema.sql postgres://username:password@hostname:5432/dbname
```

You may also consider using the following options, because privilege-related statements and owner information are generally unnecessary for ER diagrams:

- **`--no-privileges`**: Excludes all privilege-related statements (e.g., `GRANT` / `REVOKE`) from the dump.  
- **`--no-owner`**: Omits ownership statements (e.g., `ALTER TABLE ... OWNER TO ...`).

Once you have generated `schema.sql`, you can use Liam CLI to build an ER diagram.  
Specify `--format postgres` and `--input schema.sql` as follows:

```package-install
npx @liam-hq/cli erd build --format postgres --input schema.sql
```

If the above command runs successfully, an ER diagram will be generated.

## Under the Hood

For parsing PostgreSQL SQL files, Liam CLI relies on the following libraries:

- [pganalyze/pg-query-emscripten](https://github.com/pganalyze/pg-query-emscripten)
- [pganalyze/libpg_query](https://github.com/pganalyze/libpg_query)


---
title: Prisma
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; // For package-install code blocks

If you’re using [Prisma](https://www.prisma.io/), in most cases you can automatically generate a useful ER diagram with Liam ERD. This page provides instructions and tips for generating an ER diagram in a Prisma project.

## Prisma and `schema.prisma`

When a Prisma project manages migrations using the Prisma CLI, the latest database structure is typically described in `schema.prisma`.  

When using Liam CLI, specify `--format prisma` and `--input path/to/schema.prisma` as follows:

```package-install
npx @liam-hq/cli erd build --format prisma --input prisma/schema.prisma
```

If the above command runs without issue, you should see an ER diagram generated.

### Handling Multiple Prisma Schema Files

If you use the [prismaSchemaFolder](https://www.prisma.io/docs/orm/prisma-schema/overview/location#multi-file-prisma-schema) option in your Prisma configuration, you can still generate the ER diagram by specifying a glob pattern to include all `.prisma` files in the folder. 

For example, if you have multiple `.prisma` files in the `prisma/schema/` directory, use the following command:

```package-install
npx @liam-hq/cli erd build --format prisma --input "prisma/schema/*.prisma"
```

This allows you to generate the ER diagram.

## Under the Hood

Liam CLI analyzes the content of your `schema.prisma` file using a dedicated parser that relies on [`@prisma/internals`](https://www.npmjs.com/package/@prisma/internals) to build the ER diagram.


---
title: schema.rb (Ruby on Rails)
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; // For package-install code blocks

If you’re using Ruby on Rails with ActiveRecord, in most cases you can automatically generate a useful ER diagram with Liam ERD. This page provides instructions and tips for generating an ER diagram in a Rails project.

## ActiveRecord and db/schema.rb

When a Rails application manages migrations using ActiveRecord, the latest database structure is typically described in `db/schema.rb`.  
Since `db/schema.rb` is recommended to be kept under version control, most projects will have it in their Git repository.

When using Liam CLI, specify `--format schemarb` and `--input db/schema.rb` as follows:

```package-install
npx @liam-hq/cli erd build --format schemarb --input db/schema.rb
```

If the above command runs without issue, you should see an ER diagram generated.

## Under the Hood

- Liam CLI does not run an internal Ruby or Rails runtime. In other words, there is no Ruby process running under the hood.
- Instead, it analyzes the content of `db/schema.rb` using the [`ruby/prism` parser](https://github.com/ruby/prism).

## Trouble Shooting

### If You Don’t Have `db/schema.rb` but Use `db/structure.sql`

If your Rails app doesn’t have `db/schema.rb` and instead uses `db/structure.sql`, here’s what you need to know.

#### For Rails 7.0 or Later

Somewhere under `config` (most commonly `config/application.rb`), you may have `config.active_record.schema_format = :sql`.  
In such cases, running the dump command `rails db:schema:dump` will generate `db/structure.sql`.

If you want to obtain `db/schema.rb`, run the following in an environment with database access:

- Change `config.active_record.schema_format` to `:ruby` and run `rails db:schema:dump`.
- Alternatively, set the environment variable `SCHEMA_FORMAT=ruby` and run `rails db:schema:dump`.
  - For example: `SCHEMA_FORMAT=ruby rails db:schema:dump`

You can find sample implementations for this case on GitHub:

- GitHub Actions: [.github/workflows/rails-8-0-db-structure.yml](https://github.com/liam-hq/liam-erd-samples/blob/main/.github/workflows/rails-8-0-db-structure.yml)
- Rails App: [samples/rails-8-0-db-structure](https://github.com/liam-hq/liam-erd-samples/tree/main/samples/rails-8-0-db-structure)

#### For Rails 6.1 or Earlier

To generate `db/schema.rb` in an environment with database access, set the environment variable `SCHEMA_FORMAT=ruby` and run `rails db:schema:dump`.

#### Using `db/structure.sql` Directly

If you’re using PostgreSQL, you can hand `db/structure.sql` directly to Liam CLI, and it should be parsed correctly.

In that case, the usage is the same as [--format=postgres](/docs/parser/supported-formats/postgresql):


```package-install
npx @liam-hq/cli erd build --format postgres --input db/structure.sql
```

### When Associations Don’t Appear in the ER Diagram

<Callout title="warn" type="warn">Please note that this approach can be somewhat complicated or may not work as expected.</Callout>

Liam ERD’s Rails support is specialized for analyzing a standalone `db/schema.rb` file. It does not load the entire Rails project to read associations (such as `has_many` or `belongs_to`) directly from model files.

As a result, logical relationships (associations) not backed by foreign keys may not be reflected in the ER diagram.

In some Rails projects, associations are declared in models without foreign keys in the database. In this situation, you won’t see relationships in the ER diagram.

A potential workaround—though it requires additional setup—is to manually add `add_foreign_key` statements to `db/schema.rb` in your CI/CD process, then run Liam CLI. This way, the diagram will reflect those associations.

Below is a conceptual example code snippet showing how you might gather table names from models with `belongs_to` associations and add foreign keys manually (note: this example is illustrative and may need adjustments for production use):

```ruby
# Prerequisite: The database must be accessible.
Rails.application.eager_load!

# Filter out models that have valid table_name
models_with_table = ActiveRecord::Base.descendants.select do |model|
  model.table_exists? && model.table_name.present?
end
# Map belongs_to associations to the corresponding referenced tables
assoc_map = models_with_table.map do |model|
  target_tables = model.reflect_on_all_associations(:belongs_to).map do |assoc|
    {
      table_name: assoc.class_name.safe_constantize&.table_name,
      column_name: "#{assoc.name}_id",
    }
  end.compact
  [model.table_name, target_tables]
end.to_h
# Generate add_foreign_key statements from the mapped relationships
# This is a simple example, so in practice you’d need to handle duplicates carefully
content = assoc_map.flat_map do |from_table, to_tables|
  to_tables.map { |to_table| %(add_foreign_key "#{from_table}", "#{to_table[:table_name]}", column: "#{to_table[:column_name]}") }
end.join("\n")

# Write or append this content to db/schema.rb in some way
File.open("db/schema.rb", "a") do |file|
  file.puts(content) if content.present?
end
```

By taking these steps to define foreign keys, you can produce an ER diagram closer to your expectations.

You can find sample implementations for this case on GitHub:

- GitHub Actions: [.github/workflows/rails-add-association-foreign-key.yml](https://github.com/liam-hq/liam-erd-samples/blob/main/.github/workflows/rails-add-association-foreign-key.yml)
- Rails App: [samples/rails-add-association-foreign-key](https://github.com/liam-hq/liam-erd-samples/tree/main/samples/rails-add-association-foreign-key)

## Pro Tips: Using `Schemafile` Instead of `db/schema.rb`

<Callout title="warn" type="warn">Please note that this approach can be somewhat complicated or may not work as expected.</Callout>

If your project uses a tool called [Ridgepole](https://github.com/ridgepole/ridgepole), you might have a `Schemafile` instead of a `db/schema.rb`.

A `Schemafile` uses a DSL similar to what appears in `db/schema.rb`, so handing `Schemafile` directly to Liam CLI might work in some cases.

However, because users can write arbitrary Ruby code in a `Schemafile`, there may be scenarios where it isn’t fully compatible. If the output is not what you expect, consider generating a `db/schema.rb` using the methods described above (e.g., `rails db:schema:dump`) and then parsing that file.


---
title: SQLite
---

Currently, SQLite is supported through the tbls integration. While direct SQLite support is not yet implemented, you can use tbls as a workaround to generate schema documentation for your SQLite database.

## Using tbls with SQLite

1. First, install tbls by following the [installation instructions](https://github.com/k1LoW/tbls?tab=readme-ov-file#install)

2. Use tbls to generate a schema.json file from your SQLite database:

```bash
tbls out -t json -o schema.json "sqlite:///path/to/dbname.db"
```

Replace `/path/to/dbname.db` with the path to your SQLite database file.

3. Use the generated schema.json with Liam:

```bash
npx @liam-hq/cli erd build --format=tbls --input schema.json
```

For more details about using tbls format, see the [tbls documentation](/docs/parser/supported-formats/tbls#using-tbls-json-output).

## Direct SQLite Support

Direct SQLite support is planned but not yet implemented. If you're interested in this feature, please follow or contribute to the discussion on [GitHub](https://github.com/liam-hq/liam/discussions/364).


---
title: tbls
---

import { Tab, Tabs } from "fumadocs-ui/components/tabs";

[tbls](https://github.com/k1LoW/tbls) is a CI-friendly tool for documenting a database schema.
If you're using tbls, in most cases you can automatically generate a useful ER diagram with Liam ERD. This page provides instructions and tips for generating an ER diagram in a tbls project.

## Using tbls JSON Output

First, generate a JSON schema file using tbls:

```bash
tbls out -t json schema.json
```

Then use Liam CLI to build an ER diagram from the JSON file:

```package-install
npx @liam-hq/cli erd build --format tbls --input schema.json
```

If the command runs successfully, an ER diagram will be generated in the `dist` directory.

## Integration with CI/CD

You can integrate tbls and Liam ERD in your CI/CD pipeline to automatically generate and deploy ER diagrams. Here's an example GitHub Actions workflow:

```yaml
name: Generate ERD from tbls

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup tbls
        uses: k1low/setup-tbls@v1

      - name: Generate tbls JSON
        run: tbls out -t json schema.json

      - name: Generate ER Diagram
        run: npx @liam-hq/cli erd build --input schema.json --format tbls

      # Deploy (example using GitHub Pages)
      - name: Deploy to GitHub Pages
        uses: actions-gh-pages/action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: dist
```

For more information about CI/CD integration, see [CI/CD Integration](/docs/cli/ci-cd).

## Under the Hood

Liam ERD utilizes tbls's JSON schema output format ([schema definition](https://github.com/k1LoW/tbls/blob/main/spec/tbls.schema.json_schema.json)) to convert database structures into Liam's internal format.


---
title: Troubleshooting Parser
---

TBD


---
title: Browsing Your Schema
description: Explains the interactive diagram features that help users drill down into their schema, including panning, zooming, filtering, and highlighting.
---

TBD


---
title: UI Features
---

---
title: Sharing & Query Parameters
---

## The Importance of Sharing

ER diagrams are most valuable when used collaboratively within a team. They serve as essential tools for:
- Aligning understanding across team members
- Onboarding new team members
- Documenting and discussing database design decisions

## URL-Based Sharing in Liam ERD

Liam ERD makes sharing specific views of your database schema seamless by reflecting almost all UI configurations in URL query parameters. This means you can share:

- Filtered views showing only relevant tables
- Specific table details
- Custom visualization settings

![Share](/images/content/docs/ui-features/sharing-and-query-params/share.gif)

## Available URL Parameters

| Parameter | Values | Description |
|-----------|--------|-------------|
| showMode | 'ALL_FIELDS' / 'TABLE_NAME' / 'KEY_ONLY' | Controls the level of detail shown in the ER diagram |
| active | string | The currently selected table name (opens detail pane) |
| hidden | string | Compressed array of hidden table names |


---
title: Liam ERD Web
---

Liam ERD Web is an online tool hosted by [@liam-hq](https://github.com/liam-hq) that allows you to explore real-world ER diagrams without needing to install a CLI! 🛸💫

It enables you to view ER diagrams generated from publicly available schema files, such as `db/schema.rb`, `prisma.schema`, or SQL files derived from `pg_dump`.

## How to Explore

Inserting `liambx.com/erd/p/` into your browser's address bar will generate an ER diagram for your schema file.

![Inserting Animation](/images/content/docs/web.gif)

For example, if the schema file you want to explore is hosted at the following URL:

```
# A public repo's schema file
https://github.com/docusealco/docuseal/blob/master/db/schema.rb
```

You can generate an ER diagram by inserting `liambx.com/erd/p/` into the URL:

```
https://liambx.com/erd/p/github.com/docusealco/docuseal/blob/master/db/schema.rb
      👾^^^^^^^^^^^^^^^^^👾
```

It's so easy! Isn't it? 🚀

## Tips & Tricks

### Bookmarklet for Quick Access

You can create a bookmarklet to quickly open schema files in Liam ERD. Here's how:

1. Create a new bookmark in your browser
2. Set the following JavaScript code as the URL:

```javascript
javascript:(function(){var u=window.location.href;var newUrl="https://liambx.com/erd/p/" + u.replace(/^https?:\/\//, '');window.open(newUrl,'_blank');})();
```

Now, when viewing a schema file (like `schema.rb`) on GitHub, simply click the bookmarklet to open it directly in Liam ERD! 🎯

## Appendix: Schema Format Options

### Schema Format

Liam ERD automatically detects the schema format (see [Format Auto-Detection](/docs/parser/supported-formats#format-auto-detection)). If needed, you can override the detected format using the `format` query parameter:

```
https://liambx.com/erd/p/public.example.net/path/to/file?format=schemarb
```

For more details about format detection and supported formats, check [**/docs/parser/supported-formats**](/docs/parser/supported-formats).


{
  "pages": ["troubleshooting"]
}


---
title: Troubleshooting Web Version
---

## Loading Schema Files Hosted Outside GitHub

Liam ERD Web supports loading schema files hosted on GitHub by default. When you specify a GitHub URL (e.g., `github.com/username/repo/blob/branch/path/to/schema.rb`), Liam ERD automatically converts it to a raw content URL (`raw.githubusercontent.com/username/repo/branch/path/to/schema.rb`).

However, when loading schema files hosted on platforms other than GitHub, please note the following:

### Important Notes for Files Hosted Outside GitHub

- Liam ERD Web does not perform URL conversion for non-GitHub sources
- You must provide a direct link to the raw content file, not an HTML page
- The URL should point to a page that returns only the schema file content without HTML markup

### Examples

✅ **Correct URL Format (Raw Content)**
```
https://gist.githubusercontent.com/username/gistid/raw/commitsha/filename.yml
https://gitlab.com/username/repo/-/raw/main/db/schema.rb
https://bitbucket.org/username/repo/raw/main/prisma.schema
```

❌ **Incorrect URL Format (HTML Pages)**
```
https://gist.github.com/username/gistid
https://gitlab.com/username/repo/-/blob/main/db/schema.rb
https://bitbucket.org/username/repo/src/main/prisma.schema
```