{"slug": "show-hn-llmschema-dump-your-database-schema-as-compact-markdown-for-ai-agents", "title": "Show HN: LLMSchema – Dump your database schema as compact Markdown for AI agents", "summary": "Developer tordrt released LLMSchema, an open-source Go CLI that extracts schemas from PostgreSQL, MySQL, and SQLite into compact Markdown documentation for AI coding agents. The tool captures tables, columns, types, indexes, constraints, and relationships into a single portable document by default, with optional per-table files, and supports table filtering via -t and -e flags plus CI integration through a Makefile target. LLMSchema is intended for development databases to aid AI-assisted coding, not for production-critical documentation.", "body_md": "**Simple database schema docs for LLMs and AI agents.**\n\nLLMSchema extracts database schemas from PostgreSQL, MySQL, and SQLite into\nsimple, concise Markdown documentation. [See example output](#output-format).\n\nAI coding agents need an accurate understanding of your database schema to work effectively on your application. Without dedicated schema documentation, they often have to reconstruct it from application code and migration histories, which is a slower and less reliable use of context.\n\nLLMSchema extracts tables, columns, types, indexes, constraints, and relationships into concise Markdown. It produces a single portable document by default, with optional per-table files.\n\nThis gives AI agents a clear and concise understanding of your data model without overwhelming their context window with irrelevant details.\n\n**Note:** This tool is intended for development databases to aid AI-assisted coding. Do not rely on it for production-critical documentation.\n\n**With Go installed:**\n\n```\n# Run the latest or a pinned version directly\ngo run github.com/tordrt/llmschema/cmd/llmschema@latest --version\n\n# Or install the CLI\ngo install github.com/tordrt/llmschema/cmd/llmschema@latest\n```\n\nFor reproducible automation, replace `@latest` with a version such as `@v1.4.1`.\n\n**Quick install (macOS/Linux):**\n\n```\ncurl -fsSL https://raw.githubusercontent.com/tordrt/llmschema/main/install.sh | sh\n```\n\nYou can also just give your AI coding agent this repository's URL and ask it to install LLMSchema and set it up for your project.\n\n```\ngo get github.com/tordrt/llmschema\n```\n\nSet `DATABASE_URL`:\n\n```\nexport DATABASE_URL=\"postgres://user:pass@localhost:5432/mydb\"\nllmschema -o schema.md\n```\n\nOr pass the connection string directly:\n\n```\nllmschema --db-url \"postgres://user:pass@localhost:5432/mydb\" -o schema.md\n```\n\nThis writes the complete schema to one Markdown file, beginning with a linked\nindex of its tables. Without `--output`, LLMSchema writes the same document to\nstdout. An explicit `--db-url` takes precedence over `DATABASE_URL`.\n\n| Database | Format | \n|---|---|\n| **PostgreSQL** | `postgres://username:password@host:port/db-name` | \n| **MySQL** | `mysql://username:password@host:port/db-name` | \n| **SQLite** | `sqlite://path/to/db-name.db` | \n\nReplace `db-name` with the name of the database you want to document. For\nSQLite, use the path to that database's file. MySQL also accepts the Go driver\nform, `mysql://username:password@tcp(host:port)/db-name`.\n\nThese examples assume `DATABASE_URL` is set as shown in the quick start.\n\n**Filter Specific Tables**\n\n```\nllmschema -o schema.md -t \"users,posts,comments\"\n```\n\n**Exclude Tables**\n\n```\nllmschema -o schema.md -e \"migrations,audit_logs\"\n```\n\n**Print to stdout**\n\n```\nllmschema\n```\n\n**Omit the Table Index**\n\n```\nllmschema -o schema.md --no-table-index\n```\n\n**Create Focused Single-file Documents**\n\n```\nllmschema -o schema-core.md -e \"audit_logs,analytics_events\"\nllmschema -o schema-analytics.md -t \"analytics_events,dashboards,reports\"\n```\n\nTable filters let you maintain multiple purpose-specific schema documents when the complete schema would add unnecessary context.\n\n**Generate One File per Table**\n\n```\nllmschema -d docs/db-schema\n```\n\nMulti-file output creates an overview and one file per table so an agent can load only the tables relevant to its task. For complex schemas, it can be useful to generate both formats: keep the single-file schema for general context and use the per-table files for targeted, in-depth work.\n\n**Automated CI/Migration Integration**\nAdd to your `Makefile` or migration script to keep docs up-to-date:\n\n```\n.PHONY: migrate schema\n\nmigrate:\n\t# Example using Goose; replace with your project's migration command.\n\tgoose postgres \"$(DATABASE_URL)\" up\n\t$(MAKE) schema\n\nschema:\n\tgo run github.com/tordrt/llmschema/cmd/llmschema@latest -o schema.md\n```\n\n| Flag | Short | Description | Default | \n|---|---|---|---|\n| `--db-url` |  | Database connection string | `$DATABASE_URL` | \n| `--output` | `-o` | Output file for the single-file schema | stdout | \n| `--output-dir` | `-d` | Output directory for optional multi-file output | - | \n| `--tables` | `-t` | Comma-separated list of tables to extract | All tables | \n| `--exclude-tables` | `-e` | Comma-separated list of tables to exclude | - | \n| `--schema` | `-s` | Database schema name (PostgreSQL/MySQL) | `public` (PG) / Auto (MySQL) | \n| `--no-database-info` |  | Exclude database type, version, name, and schema from the output | `false` | \n| `--no-table-index` |  | Exclude the table index from single-file output | `false` | \n| `--version` |  | Print the LLMSchema version | - | \n| `--preserve-stale-files` |  | Keep table files generated by previous runs | `false` | \n\nTell your coding agent where the schema documentation is located in\n`AGENTS.md`, `CLAUDE.md`, or an equivalent instruction file:\n\n```\n## Database schema\n\nDatabase schema documentation is in `schema.md`.\n```\n\nFor multi-file output:\n\n```\nDatabase schema documentation is in `docs/db-schema/`. The directory contains\na schema overview and a separate file for each table.\n```\n\nUse `LLMSchema` programmatically in your Go applications.\n\n```\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    \"os\"\n\n    \"github.com/tordrt/llmschema\"\n)\n\nfunc main() {\n    schemaFile, err := os.Create(\"schema.md\")\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer schemaFile.Close()\n\n    err = llmschema.ExtractAndFormat(\n        context.Background(),\n        \"postgres://user:pass@localhost:5432/mydb\",\n        &llmschema.Options{\n            ExcludeTables: []string{\"migrations\"},\n        },\n        &llmschema.OutputOptions{\n            Writer: schemaFile,\n        },\n    )\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\nThis single-file example was generated from the checked-in PostgreSQL integration fixture:\n\n```\n# Database Schema\n\n**Database:** PostgreSQL 16.14 (Debian 16.14-1.pgdg13+1)\n**Name:** `testdb`\n\n**Conventions:** `PK` and `UNIQUE` identify unique keys; their backing indexes are omitted from Additional indexes.\n\n**Tables:**\n\n- [users](#users)\n- [orders](#orders)\n\n## users\n\n| Column | Type |\n|--------|------|\n| id | PK integer NOT NULL DEFAULT nextval('users_id_seq'::regclass) |\n| username | varchar(50) NOT NULL UNIQUE |\n| email | varchar(100) NOT NULL |\n| status | user_status (active, inactive, banned) DEFAULT 'active'::user_status |\n| created_at | timestamp DEFAULT CURRENT_TIMESTAMP |\n\n## orders\n\n| Column | Type |\n|--------|------|\n| id | PK integer NOT NULL DEFAULT nextval('orders_id_seq'::regclass) |\n| user_id | integer NOT NULL |\n| total_amount | numeric(10,2) NOT NULL |\n| order_date | timestamp DEFAULT CURRENT_TIMESTAMP |\n| status | order_status (pending, processing, shipped, delivered, cancelled) DEFAULT 'pending'::order_status |\n\n### Additional indexes\n\n- idx_status on (status)\n- idx_user_date on (user_id, order_date)\n\n### References\n\n- user_id → users.id (many orders to one users; ON DELETE CASCADE)\n```\n\nSections such as `Additional indexes` and `References` appear only when the\ntable has that metadata. Primary and unique keys are represented by `PK`,\n`UNIQUE`, and explicit composite-key lines, so their backing indexes are not\nrepeated under `Additional indexes`. Columns the database fills itself are\nmarked with `AUTO_INCREMENT`, `GENERATED ... AS IDENTITY`, or\n`GENERATED ALWAYS AS (expression)`; SQLite generated columns show `GENERATED`\nwithout the expression.\n\nFor schemas with many tables, or tables that are individually complex,\n`--output-dir docs/db-schema` instead creates an overview plus one Markdown\nfile per table:\n\n```\ndocs/db-schema/\n├── .llmschema-manifest.json\n├── _overview.md\n├── order_items.md\n├── orders.md\n├── products.md\n└── users.md\n```\n\nThe hidden manifest tracks files generated by LLMSchema so stale table files can be removed without touching supplemental files in the same directory.\n\nThe overview is intentionally small, so an AI agent can discover the available tables and load only the table files relevant to its task.\n\n```\n# Schema Overview\n\n**Database:** PostgreSQL 16.14 (Debian 16.14-1.pgdg13+1)\n**Name:** `testdb`\n\n**Conventions:** `PK` and `UNIQUE` identify unique keys; their backing indexes are omitted from Additional indexes.\n\nEach table has its own documentation file listed below.\n\n## Tables\n\n- **order_items** (file: `order_items.md`) (references: orders, products)\n- **orders** (file: `orders.md`) (references: users)\n- **products** (file: `products.md`)\n- **users** (file: `users.md`)\n```\n\nEach table file contains its columns and, when present, indexes and both outgoing and incoming relationships.\n\n```\n## orders\n\n| Column | Type |\n|--------|------|\n| id | PK integer NOT NULL DEFAULT nextval('orders_id_seq'::regclass) |\n| user_id | integer NOT NULL |\n| total_amount | numeric(10,2) NOT NULL |\n| order_date | timestamp DEFAULT CURRENT_TIMESTAMP |\n| status | order_status (pending, processing, shipped, delivered, cancelled) DEFAULT 'pending'::order_status |\n\n### Additional indexes\n\n- idx_status on (status)\n- idx_user_date on (user_id, order_date)\n\n### References\n\n- user_id → users.id (many orders to one users; ON DELETE CASCADE)\n\n### Referenced by\n\n- order_items.order_id → id (many order_items to one orders)\n```\n\nContributions are welcome! Feel free to open issues or submit pull requests for new features, database support, or bug fixes.\n\nSome useful areas to explore:\n\n- Views and materialized views across the supported databases\n- PostgreSQL triggers and their associated functions\n- Table and column comments in generated documentation\n\nFor larger features, consider opening an issue first.\n\nMIT License - see [LICENSE](https://github.com/tordrt/LLMSchema/blob/main/LICENSE) file for details.", "url": "https://wpnews.pro/news/show-hn-llmschema-dump-your-database-schema-as-compact-markdown-for-ai-agents", "canonical_source": "https://github.com/tordrt/LLMSchema", "published_at": "2026-10-08 09:13:35+00:00", "updated_at": "2026-10-08 09:19:08.129066+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "ai-infrastructure", "structured-data"], "entities": ["LLMSchema", "tordrt", "PostgreSQL", "MySQL", "SQLite", "Go", "GitHub", "Goose"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-llmschema-dump-your-database-schema-as-compact-markdown-for-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-llmschema-dump-your-database-schema-as-compact-markdown-for-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-llmschema-dump-your-database-schema-as-compact-markdown-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-llmschema-dump-your-database-schema-as-compact-markdown-for-ai-agents.jsonld"}}