CLAUDE.md

Overview

PostgreSQL database documentation system for LLM querying across multiple databases. Documentation structured as markdown files for schemas/tables.

Structure

Databases defined in db.yml. Hierarchy:

host/database/schema/table.md

Queries are stored in sql Results stored in results Procedures stored in plan

Table Documentation Format

Columns

column_name: data_type [NOT NULL] [DEFAULT value] [COMMENT 'desc']

Indexes

index_name: type (columns) [WHERE condition] [COMMENT 'desc']

Relationships

name: fk_column -> table (column) [ON DELETE/UPDATE action] [COMMENT 'desc']

Implicit Relationships

CRITICAL: Manual relationships not in DB schema. NEVER remove without explicit instruction.

name: column -> table (column) [COMMENT 'desc']

Notes

CRITICAL: Contains LLM hints, cross-database relationships, query patterns. NEVER remove without explicit instruction.

Records can have # comments for context.

Database Access

Read-only access: user ro, role ro. Password in ~/.pgpass, hostname in db.yml.

Querying

Before querying, read the relevant schema files.

Simple queries:

psql -h [host] -p [port] -U ro -d [database]

Complex queries - create SQL file in sql/ directory, format with npx sql-formatter, execute:

psql -h [host] -p [port] -U ro -d [database] -f [file.sql]

Guidelines

1. Preserve "Implicit Relationships" and "Notes" sections when refreshing schemas
2. Keep documentation terse
3. Read-only access only - never modify data
4. Store results in results/ directory. Use the same filename as the query file.

Finding Schemas

Use tree -P "*.md" --prune [host]/ to quickly see all table schemas organized by host/database/schema/table.md