> ## Agent Instructions
>
> Base URL: https://api.anysite.io
> Authentication: send the `access-token` header. Do NOT use `Authorization: Bearer`.
> Full endpoint catalog: https://app.anysite.io/docs
# 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
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.

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

```bash
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 |

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

  
#### Database Operations

    Insert, query, and sync data with your databases
  
  
#### Agent Protocol

    Structured JSON output for AI agent integration