{"id":51013285,"url":"https://github.com/heptau/pg_dbml","last_synced_at":"2026-06-21T06:30:54.797Z","repository":{"id":352287080,"uuid":"1210143684","full_name":"heptau/pg_dbml","owner":"heptau","description":"💾 CLI utility to export PostgreSQL schemas to DBML format. Leverage pure SQL introspection to generate declarative data blueprints. Ideal for feeding LLMs, allowing AI to quickly and cheaply understand complex database structures without live querying.","archived":false,"fork":false,"pushed_at":"2026-06-12T10:39:49.000Z","size":598,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T12:16:16.210Z","etag":null,"topics":["ai","cli","database","dbml","documentation","llm","postgres","postgresql","schema"],"latest_commit_sha":null,"homepage":"https://pg_dbml.80.cz","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heptau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"custom":["https://revolut.me/zbynekvanzura","https://wise.com/pay/me/zbynekv17","https://app.binance.com/uni-qr/DbrFdVHA"]}},"created_at":"2026-04-14T06:04:55.000Z","updated_at":"2026-06-12T10:39:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heptau/pg_dbml","commit_stats":null,"previous_names":["heptau/pg_dbml"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/heptau/pg_dbml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heptau%2Fpg_dbml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heptau%2Fpg_dbml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heptau%2Fpg_dbml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heptau%2Fpg_dbml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heptau","download_url":"https://codeload.github.com/heptau/pg_dbml/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heptau%2Fpg_dbml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34597337,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","database","dbml","documentation","llm","postgres","postgresql","schema"],"created_at":"2026-06-21T06:30:54.040Z","updated_at":"2026-06-21T06:30:54.792Z","avatar_url":"https://github.com/heptau.png","language":"Shell","funding_links":["https://revolut.me/zbynekvanzura","https://wise.com/pay/me/zbynekv17","https://app.binance.com/uni-qr/DbrFdVHA"],"categories":[],"sub_categories":[],"readme":"# pg_dbml\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CLI Tool](https://img.shields.io/badge/Interface-CLI%20Wrapper-green.svg)](pg_dbml)\n\nA powerful command-line utility built around PostgreSQL introspection. `pg_dbml` extracts the complete database schema and exports it directly into the standardized DBML (Database Markup Language) format.\n\nThis tool leverages PostgreSQL's system catalogs and metadata to perform deep, pure SQL introspection, while providing a user-friendly CLI wrapper for execution.\n\n## 💡 Why use DBML for AI \u0026 LLMs?\n\nDatabase schemas are often complex to parse. Directly querying a live production database for schema knowledge is slow, resource-intensive, and requires intricate SQL expertise. DBML solves this by providing a human-readable, declarative, and highly structured blueprint of your data.\n\n**Benefit for AI:** By consuming a DBML file, Large Language Models (LLMs) like Claude or ChatGPT can rapidly and cost-effectively familiarize themselves with your data model. They can instantly understand relationships, table structures, and constraints without needing to run time-consuming queries against the live database. It transforms complex relational metadata into highly token-efficient text.\n\n## ✨ Features\n\n*   **CLI Driven:** Simple, single-command interface for schema export (`pg_dbml`).\n*   **Pure SQL Foundation:** Zero dependencies on Node.js or third-party parsers. The core logic is a highly optimized SQL query (`pg_dbml.sql`).\n*   **Complete Schema Extraction:** Captures schemas, table definitions, column names, data types, and nullability constraints.\n*   **Constraint Mapping:** Automatically detects and maps Primary Keys (PK), Unique constraints, and Foreign Key relationships.\n*   **Metadata Richness:** Includes table and column comments retrieved directly from PostgreSQL metadata (crucial for AI context).\n\n## 🚀 Installation\n\n### Option A: macOS / Linux via Homebrew (Recommended)\n\nThe easiest and most reliable way to install `pg_dbml` is using Homebrew. This automatically handles the `psql` dependencies and correctly sets up the path for the underlying SQL files.\n\n```bash\n# Install the tool\nbrew install heptau/tap/pg-dbml\n```\n\n### Option B: Manual Installation\n\nIf you prefer not to use Homebrew, you can install the script manually.\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/heptau/pg_dbml.git\ncd pg_dbml\n```\n\n2. Make the script executable:\n```bash\nchmod +x pg_dbml\n```\n\n3. *Optional:* Symlink it to your path so you can use it anywhere (ensure `pg_dbml.sql` stays in the same directory):\n```bash\nln -s $(pwd)/pg_dbml /usr/local/bin/pg_dbml\n```\n\n*Note: Manual installation requires `psql` (PostgreSQL client) to be installed and available in your system PATH.*\n\n## ⚙️ Usage\n\nThe primary way to use this project is via the `pg_dbml` command-line script.\n\n**Basic Execution:**\nIf you want to export the schema from a database named `my_production_db` running on your local machine:\n\n```bash\npg_dbml -d my_production_db -o schema.dbml\n```\n\n**Using a Connection String:**\nYou can also pass a standard PostgreSQL connection URI:\n\n```bash\npg_dbml postgresql://postgres:password@localhost:5432/my_production_db\n```\n\n**Arguments Reference:**\n\n| Argument | Short | Description | Required | Default |\n| :--- | :---: | :--- | :---: | :--- |\n| `--dbname` | `-d` | Name of the target database. | Yes* | N/A |\n| `--host` | `-h` | PostgreSQL host address. | No | `localhost` |\n| `--port` | `-p` | PostgreSQL port. | No | `5432` |\n| `--user` | `-U` | Database user name. | No | `postgres` |\n| `--output` | `-o` | Path where the `.dbml` file will be saved. | No | `[DBNAME].dbml` |\n| `--quiet` | `-q` | Suppress success message. | No | |\n| `--dry-run` | | Preview output without writing file. | No | |\n| `--version`| `-v` | Show script version. | No | |\n| `--help` | | Show help message. | No | |\n\n*\\* Required unless provided via a connection string.*\n\n**Examples:**\n\n```bash\npg_dbml -d mydb\npg_dbml -d mydb -q\npg_dbml postgresql://postgres:password@localhost:5432/mydb --dry-run\n```\n\n## 📚 Technical Architecture\n\nThe architecture consists of two files to maximize developer experience and maintainability:\n\n1.  **`pg_dbml` (Bash orchestrator):** Parses command-line arguments, safely handles database connections via `psql`, and writes the final stream to the DBML file.\n2.  **`pg_dbml.sql` (Core Engine):** A complex, pure SQL query that queries PostgreSQL's internal `pg_catalog` and `information_schema` tables. By keeping this in a separate file, contributors benefit from full syntax highlighting and standard SQL debugging.\n\n## 🛠 Development\n\nRun tests and build artifacts using `make`:\n\n```bash\nmake         # Show help\nmake test    # Run tests\nmake build   # Build release artifacts (archive + Homebrew formula)\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.\n\n## ⚖️ License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheptau%2Fpg_dbml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheptau%2Fpg_dbml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheptau%2Fpg_dbml/lists"}