Overview
Before loading or querying data, it helps to understand what is already in your database. The discovery commands introspect any connected SQLite, PostgreSQL, or ClickHouse database and build a detailed 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 and can be browsed anytime — useful for AI agents that need database context without manual documentation.
Discover Database Structure
Run discovery against any configured connection:
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 — first rows from each table
- Read-only status — auto-detected (PostgreSQL replicas, read-only filesystems, ClickHouse
readonly setting)
The result is automatically 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). Note: ClickHouse does not support foreign keys, so FK discovery returns empty results.
LLM Enrichment
Add human-readable descriptions to your catalog using an LLM:
anysite db discover mydb --with-llm
Requires the LLM extra: pip install "anysite-cli[llm]" and a configured LLM provider (anysite llm setup).
| 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 |
to_context_string().
Filtering Tables
Control which tables to discover:
# 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: 3)
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 | 3 |
--with-llm | Enrich with LLM-generated descriptions | Off |
Browse Saved Catalogs
After discovery, catalogs are saved at ~/.anysite/catalogs/<connection>.yaml and can be browsed anytime:
# 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 format includes all tables, columns, relationships, and LLM descriptions — everything an agent needs to understand your data.
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
