@hankanman/postgres-to-docs v3.0.1
Postgres to Docs
Make your database documentation smooth by generating markdown for your schema. You need to get a quick and easy overview of your database schema but don't want to...
- Open the source code and find the model definitions
- Start your database and service, install dependencies, have a proper configuration, and open an external tool like TablePlus or DBeaver
- Read through your migrations directory to find the latest version of your schema
- Look through external documentation that might be out of date
Features
postgres-to-docs generates comprehensive documentation for your PostgreSQL database schema:
Documentation Elements
- Tables
- Primary Keys
- Foreign Keys
- Nullable fields
- Default values
- Column comments
- Views
- Column definitions
- View comments
- User-defined Types
- Composite types
- Enums
- Functions
- Full signatures
- Arguments and return types
- Function definitions
- Language and volatility
- Row Level Security (RLS) Policies
- Policy definitions
- USING expressions
- WITH CHECK expressions
- Applicable roles
- Entity Relationship Diagrams
- Mermaid.js format
- Visual representation of relationships
- Table structure visualization
Output Formats
- Markdown
- Clean, readable documentation
- Table of Contents
- Hyperlinked references
- Optional pure markdown mode (no HTML)
- LLM-optimized JSON
- Structured schema information
- Complete metadata
- Optimized for AI consumption
- Includes schema statistics
Configuration Options
- Output Control
folder
: Output directory (default: "docs")fileName
: Base name for output files (default: "schema")pureMarkdown
: Generate clean markdown without HTMLllmFormat
: Generate additional LLM-friendly JSON format
- Content Filtering
includeTables
: List of tables to includeexcludeTables
: List of tables to excludeincludeTypes
: Include user-defined typesincludeRLS
: Include RLS policiesincludeFunctions
: Include function definitionsincludeDiagram
: Include ER diagramincludeToc
: Include table of contents
- Database Connection
- Support for connection string or individual parameters
- Environment variable support through
.env
files
Usage
Install through npm
npm install @hankanman/postgres-to-docs
Define a
postgrestodocs.json
config file{ "host": "localhost", "port": 5432, "user": "user", "password": "password", "database": "database", "schema": "public", "folder": "docs", "fileName": "schema", "includeTables": [], "exludeTables": [], "includeTypes": true, "pureMarkdown": false, "includeRLS": true, "includeToc": true, "includeFunctions": true, "includeDiagram": true, "llmFormat": false }
- Run the tool
postgres-to-docs
Environment Variables
You can use environment variables to avoid storing sensitive database credentials in your configuration file. The tool supports both .env
and .env.local
files, with .env.local
taking precedence.
Create a .env
or .env.local
file or add the following to your existing .env
file:
# Database connection string
DB_STRING=postgresql://user:password@localhost:5432/database
The tool will:
1. Look for .env.local
first (good for local development overrides)
2. Then look for .env
(good for team-shared defaults)
3. Use DB_STRING to override the connection parameters if found
4. Fall back to the explicit values in the config file if DB_STRING is not found
Best Practice: Add .env.local
to your .gitignore
file to keep sensitive credentials out of version control:
.env.local
CLI Options
All configuration options can be overridden via CLI arguments:
postgres-to-docs --folder=my-docs --fileName=my-schema --llmFormat=true
Development
Clone the repo, then:
npm install
npm run start:dev
How to contribute
See our guide on contributing.
Release History
See our changelog.
License
Copyright © 2021 Klarna Bank AB
Contributors:
For license details, see the LICENSE file in the root of this project.