Database Discovery & Catalog

Auto-discover database structure, enrich with LLM descriptions, and browse saved catalogs

Overview

Before loading or querying data, it helps to understand what is already in your database. The discovery commands introspect a connected SQLite, PostgreSQL, or ClickHouse connection and build a structural catalog — tables, columns, types, indexes, foreign keys, row counts, and sample data. Optionally enrich the catalog with LLM-generated descriptions for instant context.

Discovered catalogs are saved locally at ~/.anysite/catalogs/<connection>.yaml and can be browsed anytime — useful for AI agents that need database context without manual documentation.

Discover Database Structure

anysite db discover mydb

This introspects the database and outputs:

Tables with row counts
Columns — name, type, nullability, defaults, primary keys
Indexes — name, columns, uniqueness
Foreign keys — source and target columns
Sample data — a small number of rows from each table (1 by default; see --sample-rows)
Read-only status — auto-detected (PostgreSQL replicas, read-only filesystems, ClickHouse readonly setting)

The result is saved as a catalog for future reference.

Discovery works with SQLite (via PRAGMAs), PostgreSQL (via information_schema and pg_catalog), and ClickHouse (via system.tables and system.columns). ClickHouse does not support foreign keys, so FK discovery returns empty results for it.

LLM Enrichment

anysite db discover mydb --with-llm

Requires the LLM extra: pip install "anysite-cli[llm]" and a configured LLM provider (anysite llm setup).

LLM enrichment adds four layers of context:

Layer	What It Generates
Table descriptions	Purpose and role of each table
Column descriptions	Semantic meaning of each column
Implicit relationships	Naming-pattern detection (e.g., `user_id` → `users.id`) beyond declared FKs
Database description	Overall summary of the database structure and purpose

--provider and --model override the default LLM provider/model for this run; --no-cache skips the LLM response cache.

Filtering Tables

# Discover specific tables only
anysite db discover mydb --tables users,posts,comments

# Exclude internal tables
anysite db discover mydb --exclude-tables _migrations,django_session

# Control sample data rows (default: 1)
anysite db discover mydb --sample-rows 10

Discovery Options

Option	Description	Default
`--tables`	Comma-separated list of tables to include	All tables
`--exclude-tables`	Comma-separated list of tables to skip	None
`--sample-rows`	Number of sample rows per table	`1`
`--with-llm`	Enrich with LLM-generated descriptions	Off
`--provider`	LLM provider override (`openai`/`anthropic`)	Configured default
`--model`	LLM model override	Configured default
`--no-cache`	Skip the LLM response cache	Off
`--quiet`, `-q`	Minimal console output	Off

Browse Saved Catalogs

# List all saved catalogs
anysite db catalog

# View a specific catalog
anysite db catalog mydb

# View a single table from the catalog
anysite db catalog mydb --table users

# JSON output (for agents and scripts)
anysite db catalog mydb --json

Use anysite db catalog mydb --json to pipe database context into AI agents. The JSON includes all tables, columns, relationships, and LLM descriptions.

Commands Reference

Command	Description
`anysite db discover <conn>`	Discover and save database structure
`anysite db discover <conn> --with-llm`	Discover with LLM-generated descriptions
`anysite db discover <conn> --tables t1,t2`	Discover specific tables only
`anysite db discover <conn> --exclude-tables t1`	Exclude tables from discovery
`anysite db discover <conn> --sample-rows N`	Control sample data rows
`anysite db catalog`	List all saved catalogs
`anysite db catalog <conn>`	View saved catalog for a connection
`anysite db catalog <conn> --table <name>`	View a specific table from catalog
`anysite db catalog <conn> --json`	Output catalog as JSON

Next Steps

Database Operations

Insert, query, and sync data with your databases

Agent Protocol

Structured JSON output for AI agent integration