> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anysite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 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:

```bash theme={null}
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** — 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.

<Tip>
  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.
</Tip>

## LLM Enrichment

Add human-readable descriptions to your catalog using an LLM:

```bash theme={null}
anysite db discover mydb --with-llm
```

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

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                       |

This context is saved in the catalog and can be injected into LLM prompts via `to_context_string()`.

## Filtering Tables

Control which tables to discover:

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

<Tip>
  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.
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="Database Operations" icon="arrows-rotate" href="/cli/database/operations">
    Insert, query, and sync data with your databases
  </Card>

  <Card title="Agent Protocol" icon="robot" href="/cli/agent-protocol">
    Structured JSON output for AI agent integration
  </Card>
</CardGroup>