# Liam Erd
> Documentation for Liam Erd
---
# Liam Erd Documentation
Source: https://liambx.com/docs/llms-full.txt
---
---
# 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 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:
```npm
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 schema.
### Why is Hosting the Latest ER Diagram Important?
- **Streamlined Onboarding**
When new or cross-functional team members need to understand the schema, 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
# You can specify a custom output directory with --output-dir option if needed
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
```
You can use either `npx @liam-hq/cli erd build` or `liam erd build` (if installed globally) to run the Liam ERD CLI.
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 (or the directory specified by `--output-dir` option) is created with the following structure. Here, `index.html` acts as the single entry point for your **single-page application (SPA)**:
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:
```npm
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
# You can specify a custom output directory with --output-dir option if needed
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:
```npm
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:
```npm
npx @liam-hq/cli erd build --input
```
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. Also, output directory can be specified by `--output-dir` option.
Once the ERD is generated, you can view it by serving the files using a local HTTP server:
```npm
npx serve dist/ # or your custom output directory
```
The server will start and provide you with a local URL (typically http://localhost:3000) 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 to your schema file or URL
- `--format `: (Optional) Override the auto-detected schema format
- `--output-dir `: (Optional) Specify the output directory for generated files (default: "dist")
### 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.
```npm
npx @liam-hq/cli erd build --input https://github.com/user/repo/blob/main/examples/schema.sql --format postgres
```
```npm
npx @liam-hq/cli erd build --input https://raw.githubusercontent.com/user/repo/main/examples/schema.sql --format postgres
```
### 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 (or the directory specified by `--output-dir` option).
To view the generated ERD, serve the output directory using any HTTP server:
```npm
npx serve dist/ # or your custom output directory
```
## 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=en&_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
### Ruby on Rails
- [ERๅณ่ชๅ็ๆใฎใใใซLiam ERDใ่ฉฆ้จๅฐๅ
ฅใใฆใฟใพใใ๏ผ](https://tech.gree-x.com/automated-er-diagram-generation/index.html)
- May 2025 โข tech.gree-x.com โข [translated](https://tech-gree--x-com.translate.goog/automated-er-diagram-generation/index.html?_x_tr_sl=auto&_x_tr_tl=en&_x_tr_hl=ja&_x_tr_pto=wapp)
- A practical guide to generating ER diagrams from Ruby on Rails `schema.rb` files using Liam ERD.
- Covers CLI usage, Docker-based hot-reload setup, and automated S3 deployment with GitHub Actions.
## Cloud Deployment
- [Liam ERDใง็ๆใใERๅณใCloud Run on GCSใงๅ
ฌ้ใใ](https://zenn.dev/sikeda107/articles/8da7d91277f9aa)
- August 2025 โข zenn.dev โข [translated](https://zenn-dev.translate.goog/sikeda107/articles/8da7d91277f9aa?_x_tr_sl=auto&_x_tr_tl=en&_x_tr_hl=ja&_x_tr_pto=wapp&_x_tr_hist=true)
- A step-by-step guide to deploying Liam ERD-generated diagrams on Google Cloud Platform
- Covers Cloud Storage setup, Cloud Run deployment with Nginx, and public URL configuration
## Articles Featuring Liam ERD
- [6 ะฟัะธะฝัะธะฟะพะฒ ะฐัั
ะธัะตะบัััั ะะ ะดะปั ััะฐััะฐ ะฟัะพะตะบัะฐ](https://habr.com/ru/articles/888266/)
- March 2025 โข habr.com โข [translated](https://habr-com.translate.goog/ru/articles/888266/?_x_tr_sl=auto&_x_tr_tl=en&_x_tr_hl=ru&_x_tr_pto=wapp)
- Uses Liam ERD as an example of self-descriptive code and architecture principles
- Shows how auto-generating interactive database documentation creates living architecture documentation
- [Top 4 Free, Open Source Database Schema Diagram Tools to Visualize Database Easier in 2025](https://www.bytebase.com/blog/top-database-schema-diagram-tools/)
- May 2025 โข bytebase.com
- Compares Liam ERD with DrawDB, ChartDB, and Azimutt as top open-source schema visualization tools
- Highlights Liam ERD's zero-setup approach for Rails, Prisma, and PostgreSQL schemas
## 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: 20241003 - Use CSS Modules for Styling
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
Frontend styling approaches significantly impact development efficiency, maintainability, and performance. Our project required a styling solution that meets the following requirements:
1. **Design System Consistency** - Effective management of design tokens for a unified UI
2. **Implementation Efficiency** - Leveraging Figma style export to accelerate development
3. **AI Utilization** - Maximizing AI-assisted coding support
4. **Code Quality** - Preventing conflicts through scoped styling
We considered the following options to meet these requirements:
- CSS Modules
- Tailwind CSS
- CSS in JS
## Decision
We have decided to adopt CSS Modules as our styling approach. The key factors behind this decision are:
### 1. Stability and Future-Proofing with Standard Technologies
- **Standard CSS Specification** - Most stable styling approach using direct CSS
- **Immediate Access to New CSS Features** - Seamless utilization of features like CSS Variables
- **Tool Chain Compatibility** - Standard support in major bundlers (Webpack, Vite)
- **Technology Longevity** - Long-term viability independent of frameworks
### 2. Efficient Design System Implementation
- **Consistent Design Token Management** - Global variable management via CSS Variables
- **Direct Figma Integration** - Efficient conversion from design to CSS
- **Easy Theme Switching** - Simplified dark mode implementation through variable changes
- **Rapid Design Change Propagation** - Changes in one place affect the entire system
### 3. Team Development Optimization
- **Parallel Development via Component Isolation** - Independent work areas through scoping
- **Automatic Name Collision Avoidance** - Component-level CSS modularization
- **Minimal Learning Curve** - Development possible with standard CSS knowledge only
- **Code Review Simplification** - Improved readability through separation of styles and logic
### 4. High Compatibility with AI-Assisted Coding
- **High-Precision Generation Based on Standard Specifications** - Improved code generation accuracy
- **Abundant Reference Information** - Leveraging global information as learning data
- **Predictable Structure** - Streamlined debugging and modifications
- **Adaptation to Future AI Technology Evolution** - Continuous improvement expected for standard technologies
### 5. Balance Between Performance and Quality
- **Build-Time Optimization** - Reduced runtime overhead
- **Easy Code Splitting** - Component-level code splitting
- **Caching Strategy** - Efficient caching design
- **Bundle Size Optimization** - Automatic elimination of unnecessary styles
## Consequences
### Positive Impacts
1. **Design Quality and Consistency**
- UI unification through design tokens
- Visual coherence between components
- Simplified multi-theme support
2. **Development Productivity**
- Accelerated implementation from direct Figma export
- Enhanced development efficiency through AI assistance
- Parallel development at component level
3. **Code Quality**
- Prevention of style conflicts through scoping
- Clear responsibility separation at component level
- Predictable style application
4. **Technical Stability**
- Long-term maintainability through standard technologies
- Tool chain compatibility
- Performance optimization
### Negative Impacts
1. **UI Component Library**
- Lack of compatibility with Tailwind CSS-based libraries (shadcn/ui, etc.)
- Development and maintenance costs of custom UI component libraries
- Additional effort for third-party integration
2. **Style Sharing and Global Management**
- Complexity in designing shared styles between components
- Need for special management of global styles
- Construction of style override strategies
3. **Team Adaptation Costs**
- CSS Modules convention adoption
- Promoting understanding of the design token system
- Maintaining consistent implementation style
### Technical Flexibility
1. **Possibility of Gradual Evolution**
- Room for combining with other technologies in the future
- Tolerance for different approaches in specific components
- Natural adaptation to standard CSS evolution
2. **Development Environment Interoperability**
- Integration with TypeScript
- Standard integration with CI/CD environments
- Compatibility with existing tool chains
---
title: 20241112 - Use React Flow for ERD Visualization
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
For our Entity Relationship Diagram (ERD) implementation, we needed a solution that meets the following requirements:
- Ability to render 100+ tables efficiently
- Interactive navigation features (pan, zoom)
- Programmatic focus on specific nodes
- Auto-formatting capabilities for table layouts
Two main implementation approaches were considered:
1. Using React Flow (@xyflow/react)
2. Custom implementation using Canvas API
Performance with large datasets was a primary concern, as was the ability to deliver a smooth user experience with features like panning, zooming, and automatic layout optimization.
## Decision
We have decided to adopt React Flow as our ERD visualization engine.
The decision was based on successful performance testing showing that React Flow can handle 100+ tables with acceptable rendering performance. While we initially experienced some performance issues with edge animations (using stroke-dasharray), we were able to optimize this by implementing custom animated edges using SVG elements.
React Flow also satisfies our UX requirements:
- Built-in pan and zoom functionality
- Support for programmatic node focusing
- Integration with ELK.js for automatic layout formatting
## Consequences
### Positive
- Faster development time compared to building a custom Canvas-based solution
- Built-in support for essential features like pan, zoom, and node selection
- Strong TypeScript support ensuring type safety across our implementation
- Active community and robust documentation
- Extensible architecture allowing for custom nodes and edges
- Performance optimization capabilities when needed (as demonstrated with our edge animation improvements)
### Negative
- We depend strongly on React Flow and call the API directly
- But even if the React Flow is not optimal for us, we have decided that it is faster to rewrite everything.
- Some performance tuning was necessary for optimal results with large datasets
- Limited by React Flow's architecture and update cycle for future features
### Neutral
- Team needed to learn React Flow's API and concepts
- Integration with ELK.js for auto-layout required additional development effort, but would have been necessary regardless of the chosen solution
Our implementation has proven that React Flow, with appropriate optimizations, can efficiently handle our ERD visualization needs while providing an excellent user experience.
---
title: 20241128 - Use Fumadocs for Documentation Site
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
The Liam project required a documentation site framework that would provide a high-quality developer and user experience while being cost-effective and maintainable by the team. We needed a solution that would:
- Support static site generation for optimal performance
- Provide robust search capabilities
- Allow for customization and extension
- As a design-focused team, we wanted the ability to create impactful UI components for our documentation
- Offer a good developer experience for both code contributors and documentation writers
We evaluated several popular documentation frameworks to determine the best fit for our needs, focusing on [Fumadocs](https://fumadocs.vercel.app/), [Nextra](https://nextra.site/), and [Mintlify](https://mintlify.com/).
## Decision
We have decided to adopt Fumadocs as our documentation site framework.
The decision was based on a comprehensive evaluation of multiple factors:
### Feature Comparison
| Feature | Fumadocs | Nextra | Mintlify |
| -------------------------- | -------------------------------------- | -------------------- | -------------------------------------- |
| Static Generation | โ
| โ
| โ
|
| Caching | โ
| โ
| โ
|
| Light/Dark Mode | โ
| โ
| โ
|
| Syntax Highlighting | โ
| โ
| โ
|
| Table of Contents | โ
| โ
| โ
|
| Full-Text Search | โ
Free, with Algolia migration option | โ
FlexSearch only | โ
|
| Internationalization | โ
| โ
| โ
|
| Last Edit Date | โ
| โ
| โ
|
| Page Icons | โ
| โ
| โ
|
| React Server Components | โ
App Router support | โ Pages Router only | - (Users manage MDX only) |
| Remote Sources | โ
| โ
| โ
|
| SEO | โ
| โ
| โ
|
| Built-in Components | โ
Rich variety | โ
| โ Limited |
| Custom Components | โ
| โ
| โ |
| OpenAPI Integration | โ
| โ | โ
|
| TypeScript Docs Generation | โ
| โ | โ |
| TypeScript Twoslash | โ
| โ
| โ |
| Styling | โ
Flexible | โ
Flexible | โ Paid for custom CSS/JS |
| Web Editor | โ | โ | โ
In development |
| Thumbs up feedback | โ | โ | โ
|
| Pricing | โ
Free | โ
Free | โ $150/month + $100/month for preview |
### Key Adoption Factors
- **Cost Efficiency**: Fumadocs is open-source and free to use, aligning with our resource constraints
- **Design Quality**: Provides high-quality UI components with minimal code requirements
- **Functionality**: Offers comprehensive features needed for Liam documentation (full-text search, built-in components, theme switching)
- **Extensibility**: Being Next.js-based allows for extension with custom React components
- **Hosting and Operations**: Leverages our team's existing Next.js expertise for hosting and maintenance
- **Marketing Opportunity**: Potential visibility through listing on the [Fumadocs showcase](https://fumadocs.vercel.app/showcase)
### Why Other Options Were Not Selected
- **Mintlify**:
- Prohibitively expensive pricing model
- Usage-based billing for AI chat features beyond 250 queries with no apparent way to disable
- Slower deployment process
- **Nextra**:
- Lacks App Router and React Server Components support
- Limited search capabilities (FlexSearch only)
- Fumadocs addresses these limitations while maintaining Nextra's positive attributes
## Consequences
### Positive
- No licensing fees, reducing project costs
- Modern documentation site with excellent UX for our users
- Integration with our existing Next.js knowledge and tooling
- Flexibility to customize and extend as our documentation needs evolve
- App Router and RSC support enables better performance and development experience
- Rich built-in components accelerate documentation creation
### Negative
- Tailwind-based styling differs from Liam's [CSS Modules approach](https://liambx.com/docs/contributing/adr/20241003-use-css-modules-for-styling), creating some inconsistency
- Requires self-hosting and domain management (though this is also an advantage for control)
- As a newer framework, the community and ecosystem are smaller than more established alternatives
### Neutral
- Regular maintenance will be required to keep the documentation site updated
- The team will need to develop expertise in Fumadocs-specific features and configurations
---
title: 20241128 - Use libpg-query for PostgreSQL SQL Parsing
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
We needed a robust and efficient SQL parser for PostgreSQL to integrate into our system. Several parsing options were evaluated, including Azimutt, ANTLR, and ``libpg-query``. While each had its advantages, we prioritized parsing accuracy, performance, and maintainability.
## Decision
We chose to use ``pg-query-emscripten``, which is a WebAssembly-compiled version of ``libpg-query``. This decision was based on the following factors:
**Parsing Speed**: Benchmarks showed that ``libpg-query`` (including its WebAssembly variant) outperformed alternatives like ANTLR in terms of parsing speed.
**PostgreSQL Compatibility**: Since ``libpg-query`` is based on PostgreSQL's internal parser, it provides the highest accuracy and support for PostgreSQL-specific syntax and extensions.
## Consequences
### Positive Impacts
- High Accuracy: Ensures correct parsing of PostgreSQL-specific syntax.
- Performance: Faster than alternatives, reducing query parsing overhead.
- Lightweight & Portable: WebAssembly eliminates the need for native binaries.
### Negative Impacts
- Limited to PostgreSQL: Unlike ANTLR, which supports multiple SQL dialects, ``libpg-query`` is PostgreSQL-specific.
- WebAssembly Dependency: Requires handling WebAssembly execution within our environment.
### Neutral Impacts
- Potential for Future Expansion: While ANTLR remains a viable option for broader SQL dialect support, ``libpg-query`` meets our immediate PostgreSQL needs effectively.
---
title: 20241203 - Use Prism for schema.rb Parsing
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
As part of our [Node.js-based unified database schema parsing approach](https://liambx.com/docs/contributing/adr/20241206-node-js-based-unified-db-schema-parsing), Liam needs a specific parser for Ruby's `schema.rb` files. This ADR focuses on the selection of the appropriate Ruby parser that would work within our Node.js environment.
We evaluated several parser options to determine the best fit for our needs, focusing primarily on [PEG.js](https://github.com/pegjs/pegjs) and [Prism](https://github.com/ruby/prism).
## Decision
We have decided to adopt Prism as our parser for processing Ruby's `schema.rb` files.
The decision was based on a comprehensive evaluation of multiple factors:
### Parser Comparison
| Feature | Prism | PEG.js |
| ----------------------- | ----------------------------------------- | ----------------------------------------- |
| Parser Type | Dedicated Ruby parser | General parser generator |
| Development | By Shopify for Ruby | Community-maintained general tool |
| Error Tolerance | โ
High (designed for editor integration) | โ Limited |
| Learning Curve | โ
Low for TypeScript developers | โ Higher (requires grammar definition) |
| TypeScript Support | โ
Full TypeScript definitions | โ Limited |
| AST Traversal | โ
Built-in Visitor pattern | โ Manual implementation needed |
| npm Package | โ
Available | โ
Available |
| Ruby-specific Features | โ
Native understanding of Ruby syntax | โ Requires custom grammar implementation |
| Implementation Effort | โ
Lower (ready to use for Ruby) | โ Higher (needs custom grammar) |
| Community/Documentation | โ
Growing, backed by Shopify | โ
Established |
### Key Adoption Factors
#### 1. Development Efficiency
- **Lower Learning Curve**: Prism doesn't require writing custom grammar definitions
- **Intuitive for TypeScript Developers**: The AST can be manipulated directly using familiar TypeScript patterns
- **Ready for Ruby**: Built specifically for parsing Ruby code, eliminating the need for custom grammar development
#### 2. Type Safety
- TypeScript definitions provided out-of-the-box
- Enhanced IDE support with autocompletion and type checking
- Reduced risk of runtime errors through compile-time type checking
#### 3. Implementation Pattern Unification
- Using AST-based parsing approach creates consistency across the project
- Visitor pattern for AST traversal promotes clean, maintainable code
- Reusable patterns can be established for various parsing needs
#### 4. Contribution Accessibility
- Lower barrier to entry for TypeScript developers to contribute
- Clear documentation and typing makes the codebase more approachable
- Potential for contribution back to the Prism ecosystem
#### 5. Marketing Opportunities
- Novel use case of Prism in Node.js environments
- Potential for conference presentations (e.g., RubyKaigi)
- Opportunity to showcase Liam's innovative approach to Ruby tooling
## Consequences
For broader implications regarding our Node.js-based parsing approach, including WASM considerations and performance concerns, see the [Node.js-Based Unified DB Schema Parsing ADR](https://liambx.com/docs/contributing/adr/20241206-node-js-based-unified-db-schema-parsing).
### Prism-Specific Consequences
#### Positive
- Faster development cycle due to lower learning curve and TypeScript integration
- Improved code quality through static typing and better IDE support
- Lower barrier to entry for TypeScript developers to contribute
#### Negative
- Limited control over the underlying parser implementation compared to a custom grammar
- Dependency on Prism's development roadmap and feature support
---
title: 20241206 - Node.js-Based Unified DB Schema Parsing
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
Liam ERD needs to handle multiple database schema formats (e.g., PostgreSQL DDL, Rails `schema.rb`, and Prismaโs `schema.prisma`) and convert them into a unified internal structure for generating ER diagrams. The goal is to minimize user setup requirementsโideally enabling them to prepend a specific URL (for example, `liambx.com/erd/p/`) to a schema fileโs location and immediately render an ER diagram.
Many existing ER diagram tools introduce high operational overhead or require multiple dependencies (Java runtime, Graphviz, or issuing DML commands on a database). To achieve the desired ease of use and portability, Liam ERD must avoid these external dependencies whenever possible.
However, multiple languages and formats complicate the parsing process. Each format may require its own parsing logic. Relying on multiple language runtimes (e.g., Ruby, PHP) increases complexity. The team prefers to keep the entire parsing and rendering workflow in a single environmentโNode.jsโpotentially using WASM parsers to handle different schemas while avoiding extra runtime installations.
## Decision
We will perform all DB schema parsing within a Node.js environment. Specifically:
1. **Node.js as the Server-Side Runtime**
- Use Node.js exclusively on the server side to perform schema parsing and ER diagram generation.
- Deliver the rendered ER diagrams to the client via our web application (e.g., React Server Components) without running Node.js in the browser.
2. **Existing Parsers**
- For Prisma schemas (`schema.prisma`), we can leverage existing Node.js libraries.
- For Railsโ `schema.rb`, we plan to use [ruby/prism](https://github.com/ruby/prism) in a form that can run under Node.js (e.g., via WASM).
- For PostgreSQL DDL, we aim to use a WASM-compatible SQL parser tailored to PostgreSQL syntax.
3. **Unified Data Model**
- Map every schema format to a common `Schema` type so that subsequent ER diagram generation remains format-agnostic.
4. **Future Growth**
- If new formats emerge, we will first look for a WASM or JavaScript solution. Only if absolutely necessary will we consider introducing new runtimes or custom parser generators.
## Consequences
- **Positive Impacts**
- **Simplicity**: Users only need to modify the URL (e.g., prepend `liambx.com/erd/p/`) to get a rendered ER diagram, avoiding additional installs.
- **Consistent Tech Stack**: All parsing and server-side code is in Node.js, reducing learning and operational overhead.
- **Testability**: We can write tests using familiar tooling (e.g., Vitest), and integrate easily with CI/CD pipelines.
- **Extensibility**: A unified internal model (`Schema`) makes it simpler to add support for new formats later.
- **Negative Impacts**
- **Parser Maintenance**: Each new format or language feature may require a dedicated parser and integration work.
- Even for unsupported formats or languages, users can migrate their schema to PostgreSQL and use `pg_dump` as a workaround for standardized parsing.
- **WASM Overhead**: Using WASM-based parsers may incur performance overhead under high load or large schemas, although this is not currently a major concern.
- **Dynamic Code Limitation**: Static parsing only - cannot execute dynamic features (variables, loops, conditionals) in schema files. Affects Rails' `schema.rb` and other ORM schemas that use runtime execution.
---
title: 20250116 - Use DMMF for Prisma Schema Parsing
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
We need to parse Prisma schema files to extract schema information. Several approaches were considered:
1. JavaScript parsers (e.g., Acorn, Babel)
2. Custom parsers using parser generators (e.g., PEG.js)
3. [DMMF (Data Model Meta Format)](https://github.com/prisma/prisma/blob/main/ARCHITECTURE.md#the-dmmf-or-data-model-meta-format) from @prisma/internals
Each approach has different implications for maintenance, accuracy, and development effort. JavaScript parsers were immediately ruled out as they are designed for parsing JavaScript code, not Prisma's custom schema format.
## Decision
We will use DMMF from @prisma/internals to parse Prisma schema files. DMMF is Prisma's internal representation format used for schema parsing and validation. Using DMMF is more reliable and accurate for parsing Prisma schema files compared to custom parsers.
Key factors in this decision:
- Official support from Prisma team
- Comprehensive parsing of models, fields, and relationships
- Built-in validation and type safety
- Automatic compatibility with future Prisma updates
- De facto stability demonstrated by widespread usage in the Prisma ecosystem
## Consequences
### Positive
- Reliable and accurate parsing of Prisma schemas
- Reduced development and maintenance effort (no need to implement custom parsers)
- Future-proof against Prisma syntax changes
- Proven stability through widespread usage in other tools
- [Prisma Editor](https://github.com/mohammed-bahumaish/prisma-editor)
- [Prisma ERD Visualizer](https://github.com/skn0tt/prisma-erd)
- [prisma-uml](https://github.com/emyann/prisma-uml)
- [DBML Generator](https://github.com/notiz-dev/prisma-dbml-generator)
- [Prismaliser - Visualise your Prisma schema models and relations](https://prismaliser.app/)
- [Prisma Editor - A powerful tool to visualize and edit Prisma Schema](https://github.com/mohammed-bahumaish/prisma-editor)
### Negative
- Additional dependency on @prisma/internals
- No official recommendation to use @prisma/internals
- ref: [Discussion about @prisma/sdk rename to @prisma/internals](https://github.com/prisma/prisma/issues/13877)
### Neutral
- Need to transform DMMF output to match our internal schema format
- Learning curve for working with DMMF API
---
title: 20250205 - Use fuse.js
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
To implement the Command Palette (triggered via โ-K / Ctrl-K), there is a requirement to enable cross-searching of table names and column names within the ER diagram.
Liam ERD currently has both a web version (erd-web) and a CLI version. At least initially, we want them to operate on the same codebase. Therefore, the solution should run on the client side rather than relying on a Node.js runtime.
We considered the following technologies as the primary tools for browser-based search functionality:
1. fuse.js
2. Orama
In Pull Request [#652](https://github.com/liam-hq/liam/pull/652), we created a prototype search box using radix-ui (as used in fumadocs) and tested the speed and user experience using a benchmark project (mastodon/mastodon).
While Orama's pre-indexing offers high-speed performance, we observed that fuse.js, despite its O(n) search complexity, delivered comparable search speeds. Please refer to Pull Request [#652](https://github.com/liam-hq/liam/pull/652) for detailed performance metrics.
## Decision
We will adopt fuse.js, at least for the initial implementation.
See the positive aspects listed below for the rationale behind this decision.
## Proof of Concept (PoC) Summary
In our PoC (Pull Request [#652](https://github.com/liam-hq/liam/pull/652)), we compared **fuse.js** and **Orama** for client-side search functionality. The key findings are as follows:
> - **fuse.js** provides efficient fuzzy search capabilities out-of-the-box, without needing additional configuration for stemming or indexing.
> - **Orama** excels in search speed due to pre-built inverted indexes and offers O(1) search performance, while fuse.js operates with O(n) complexity.
> - Despite the theoretical performance differences, practical benchmarks on a project of Mastodon's scale (99 tables) revealed that both libraries deliver comparable performance, with search times ranging from 0.1ms to 1.0ms.
> - Orama's pre-indexing time was approximately 30ms-100ms, initiated upon loading the application. fuse.js does not require pre-indexing, leading to simpler integration and faster initial load times.
> - Both libraries successfully handled partial matches during live typing. However, Orama struggled with exact matches for incorrectly typed queries (e.g., "expire_at" instead of "expires_at").
Based on these observations, **fuse.js** was chosen for its ease of implementation and sufficient performance, especially for initial deployments where the data scale is moderate.
## Consequences
### Positive
- Simple configuration
- Enables easy fuzzy search
- No need for stemming configuration
### Negative
- Search speed may become an issue when handling larger RDBMS table sizes
- Search performance might degrade when dealing with a more diverse set of searchable items
---
title: 20250421 - Apply RLS to All Tables with Organization-based Policies
---
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
We have considered enhancing the security of our application by leveraging Supabase's Row-Level Security (RLS) feature.
Currently, the application accesses Supabase using the anon key on the client side, which poses a risk: tables without RLS enabled can be accessed regardless of user authentication.
Furthermore, the application is built with a multi-tenant architecture, requiring **authorization control based on organizations**.
Many tables are several relationships away from the central organization_id. This creates a challenge where RLS policies must traverse multiple tables through foreign key relationships to reach the organization_id.
For example, a policy might need to include multiple nested SELECT statements to verify that a record belongs to the user's organization.
As a result, authorization policies can become complex. If RLS is only partially applied, alternative access paths through related tables may remain, creating potential security loopholes.
## Decision
**Enable Row-Level Security (RLS) on all tables** and apply **organization-based policies** by default.
- **Basic rules**:
- Each authorized table must have an organization_id column used as a condition in the RLS policy
- Authenticated users should only access data associated with their own organization
- **Tables requiring special treatment**:
- Tables like user information, which may relate to multiple organizations, will have flexible, custom policies
- For external service integrations (e.g., GitHub), where edits or deletions should be restricted, access will be limited to read-only as necessary
- **Backend exceptions**:
- For system jobs or backend operations that do not go through user authentication, access beyond RLS restrictions will be needed. This will be handled by using specific authorization tokens or dedicated connection roles, allowing restricted access.
### Example Implementation
The projects table already implements this approach with the following policies:
```sql
-- Enable RLS on the projects table
ALTER TABLE "public"."projects" ENABLE ROW LEVEL SECURITY;
-- Policy for SELECT operations
CREATE POLICY "authenticated_users_can_select_org_projects" ON "public"."projects"
FOR SELECT TO "authenticated"
USING (("organization_id" IN (
SELECT "organization_members"."organization_id"
FROM "public"."organization_members"
WHERE ("organization_members"."user_id" = "auth"."uid"())
)));
-- Similar policies exist for INSERT, UPDATE, and DELETE operations
```
These policies ensure that users can only access projects belonging to organizations they are members of, by joining through the organization_members table.
## Consequences
### Positive
- Greatly reduces security risks by consistently enforcing RLS on all tables
- Prevents configuration oversights at the table level and eliminates dependency on manual enforcement
- Unified authorization policy simplifies development and operations, improving implementation efficiency
### Negative
- **Increased implementation cost on the application side**:
- All INSERT/UPDATE operations must accurately inject the correct organization_id
- Requires architectural review and standardization to consistently access organization_id when needed
- Some tables will require custom policy design (e.g., external integrations, user data)
### Neutral
- Performance impact is expected to be minimal. PostgreSQL's RLS evaluation is relatively fast (milliseconds to tens of milliseconds), and deep JOINs are unlikely to pose significant issues
---
title: Architecture Decision Records
description: Documented architecture decisions for the Liam project
navigation: 2
---
import { source } from "../../../../lib/source"
import { DocsCategory } from "fumadocs-ui/page"
---
title: ADR Template
---
This template is based on [Documenting architecture decisions - Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).
Please include the following sections in each ADR file.
---
---
# \{YYYYMMDD\} - \{TITLE\}
## Status
- [ ] Proposed
- [x] Accepted
- [ ] Rejected
- [ ] Deprecated
- [ ] Superseded
## Context
Describe the background and issues that led to this decision.
## Decision
Describe what was decided.
## Consequences
Describe the tradeoffs (positive, negative, and neutral impacts) of this decision.
---
title: Contributing
description: Learn how to contribute to Liam ERD
---
import { source } from "../../../lib/source"
import { DocsCategory } from "fumadocs-ui/page"
---
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
- **Trigger.dev**: Framework for running background jobs and workflows
## 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
- **Background Jobs**: Deployed with Trigger.dev
- **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
โ โโโ schema/ # Schema parser (@liam-hq/schema)
โ โ โโโ src/
โ โ โ โโโ parser/
โ โ โ โโโ utils/
โ โ โโโ package.json
โ โโโ github/ # GitHub API integration (@liam-hq/github)
โ โ โโโ src/
โ โ โ โโโ api.browser.ts # Browser-side GitHub API
โ โ โ โโโ api.server.ts # Server-side GitHub API
โ โ โ โโโ types.ts # GitHub related types
โ โ โโโ 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
### Schema Package (`@liam-hq/schema`)
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
### GitHub Package (`@liam-hq/github`)
GitHub API integration package primarily designed to support the main web application (`@liam-hq/app`). This package centralizes all GitHub-related operations required for the app's pull request review features.
**Key Responsibilities:**
- GitHub App authentication
- Pull Request operations
- Repository management
- Webhook handling
**Tech Stack:**
- Octokit
- GitHub Apps API
- GitHub REST API
**Current Usage:**
- Exclusively used by `@liam-hq/app` for handling GitHub integrations
### 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
---
title: Parser
---
import { source } from "../../../lib/source"
import { DocsCategory } from "fumadocs-ui/page"
---
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: ClickHouse
---
TBD
---
title: Cloud Spanner
---
TBD
---
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
---
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; // For package-install code blocks
If you're using [Drizzle ORM](https://orm.drizzle.team/), you can automatically generate an ER diagram from your schema files. This page provides instructions and tips for generating an ER diagram in a Drizzle project.
## Drizzle and Schema Files
Drizzle ORM defines database schemas using TypeScript files, typically located in files like `src/db/schema.ts`. The schema files use Drizzle's type-safe API to define tables, columns, relations, and constraints.
When using Liam CLI, specify `--format drizzle` and `--input path/to/schema.ts` as follows:
```npm
npx @liam-hq/cli erd build --format drizzle --input src/db/schema.ts
```
If the above command runs without issue, you should see an ER diagram generated.
### Handling Multiple Drizzle Schema Files
If your Drizzle schema is split across multiple TypeScript files, you can generate the ER diagram by specifying a glob pattern to include all schema files in the directory.
For example, if you have multiple schema files in the `src/db/schema/` directory, use the following command:
```npm
npx @liam-hq/cli erd build --format drizzle --input "src/db/schema/*.ts"
```
This allows you to generate the ER diagram from all schema files in the specified directory.
## Database Type Support
Drizzle support in Liam ERD automatically detects whether you're using PostgreSQL or MySQL based on your imports:
- **PostgreSQL**: Uses imports from `drizzle-orm/pg-core` (e.g., `pgTable`, `pgEnum`)
- **MySQL**: Uses imports from `drizzle-orm/mysql-core` (e.g., `mysqlTable`, `mysqlEnum`)
The parser supports common Drizzle features including tables, columns, relationships, indexes, and constraints. However, some advanced features like multiple database schemas may not be fully supported yet.
## Under the Hood
Liam CLI analyzes your TypeScript schema files using a custom parser that:
- Automatically detects the database type (PostgreSQL or MySQL) from your imports
- Extracts table definitions, column types, and relationships
- Supports Drizzle-specific features like enums, indexes, and constraints
- Handles complex type definitions and default values
Note: Drizzle support is currently marked as experimental. While it works reliably for most use cases, please [report any issues](https://github.com/liam-hq/liam/issues) you encounter to help us improve the parser.
---
title: Amazon DynamoDB
---
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) | โ
| โ
| `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/schema/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: MariaDB
---
TBD
---
title: MongoDB
---
TBD
---
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:
```npm
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 schema is typically described in `schema.prisma`.
When using Liam CLI, specify `--format prisma` and `--input path/to/schema.prisma` as follows:
```npm
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:
```npm
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 schema 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:
```npm
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):
```npm
npx @liam-hq/cli erd build --format postgres --input db/structure.sql
```
### When Associations Donโt Appear in the ER Diagram
Please note that this approach can be somewhat complicated or may not work as expected.
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`
Please note that this approach can be somewhat complicated or may not work as expected.
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: Amazon Redshift
---
TBD
---
title: Snowflake
---
TBD
---
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:
```npm
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 schemas into Liam's internal format.
---
title: Troubleshooting Parser
---
TBD
---
title: Browsing Your Schema
description: >
Explore your database schema with ease using intuitive navigation tools like panning, zooming, filtering, and highlighting.
Liam ERD helps you interact with complex structures efficiently and clearly.
---
## Pan and Zoom
The diagram interface supports smooth pan and zoom operations, allowing you to understand the overall structure while focusing on specific areas.
You can control diagram movement and zoom in the following ways:
- **Pan (Move) Operations**:
- Press space key + drag to move the view
- **Zoom Operations**:
- `Ctrl` + scroll up to zoom in, scroll down to zoom out
- Pinch in/out on trackpad for smooth zooming
- Use `+`/`-` buttons in the toolbar to zoom in/out
## Tidy Up
The auto-layout feature helps optimize table placement.
- Automatically align tables with one click
- Optimal placement considering relationships
- Manual layout adjustments also possible
## Zoom to Fit
Display the entire diagram to fit within the screen.
- Automatically adjust to show all tables
- Set optimal zoom level based on visible tables
## Filtering Related Tables
Make complex relationships easier to understand by displaying only tables related to specific ones.
- Select a table and switch to related tables view from the right panel when highlighted
## Relation Highlights
Visually confirm and emphasize relationships between tables in your schema.
- Highlight related relations when hovering or clicking on tables
- Visual distinction through color highlighting
## Show Hide Each Table
Simplify complex schemas by showing only necessary tables.
- Toggle visibility of individual tables
- Toggle individual table visibility using the show/hide icon button in the left panel
---
title: Command Palette
description: >
Quickly navigate to any table in your schema using the Command Palette.
Search and jump to tables instantly with keyboard shortcuts and real-time preview.
---
## Overview
The Command Palette is a powerful search interface that allows you to quickly find and navigate to any table in your database schema. It's especially useful when working with large schemas containing many tables, providing instant access without manual scrolling or browsing.
## Opening the Command Palette
You can open the Command Palette in two ways:
- **Keyboard shortcut**: Press `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux)
- **Click**: Use the search icon in the top-right corner of the interface
## Basic Usage
### Searching for Tables
1. **Open the Command Palette** using one of the methods above
2. **Type the table name** or part of it in the search field
3. **Browse results** as they appear in real-time
4. **Select a table** using keyboard navigation or mouse clicks
The search supports fuzzy matching, so you don't need to type the exact table name. For example, typing "user" will find tables like "users", "user_roles", "user_profiles", etc.
### Keyboard Navigation
- **Arrow Keys**: Use `โ` and `โ` to navigate through search results
- **Enter**: Navigate to the selected table in the current view
- **Cmd/Ctrl + Enter**: Open the selected table in a new tab
- **Escape**: Close the Command Palette
### Mouse Navigation
- **Click**: Navigate to the table in the current view
- **Cmd/Ctrl + Click**: Open the table in a new tab
## Table Preview
When you select a table in the search results, the Command Palette displays a real-time preview of the table structure on the right side. This preview shows:
- Table name and structure
- Column names and types
- Primary keys and constraints
- Visual representation identical to the main ERD view
This preview helps you confirm you're selecting the correct table before navigating, especially when dealing with similarly named tables.
## Features
### Fuzzy Search
The Command Palette uses fuzzy search powered by [Fuse.js](https://fusejs.io/), which means:
- **Partial matches**: Type any part of the table name
- **Case insensitive**: Works regardless of capitalization
- **Typo tolerance**: Handles minor spelling mistakes
- **Real-time results**: Updates as you type
### URL Integration
When you navigate to a table using the Command Palette, the URL is updated with the appropriate query parameters. This means:
- **Shareable links**: The URL reflects the current table selection
- **Browser history**: You can use back/forward buttons
- **Bookmarkable**: Save direct links to specific tables
## Use Cases
The Command Palette is particularly useful for:
- **Large schemas**: Quickly finding tables in databases with hundreds of tables
- **Partial recall**: When you remember only part of a table name
- **Efficient navigation**: Avoiding manual scrolling through long table lists
- **Presentation mode**: Quickly jumping between tables during demos or reviews
- **Development workflow**: Fast access to relevant tables during code reviews
## Tips and Best Practices
- **Use partial names**: You don't need to type the full table name
- **Try different keywords**: Search for functional terms that might appear in table names
- **Use keyboard shortcuts**: `Cmd/Ctrl+K` is faster than clicking the search icon
- **Preview before navigating**: Use the preview pane to confirm the correct table
- **Open in new tabs**: Use `Cmd/Ctrl+Enter` when comparing multiple tables
---
title: UI Features
description: Overview of user interface features in Liam ERD
---
import { source } from "../../../lib/source"
import { DocsCategory } from "fumadocs-ui/page"
---
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
## 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.
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).
---
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
```