> ## 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
# 数据库连接

为数据存储配置 SQLite、PostgreSQL 和 ClickHouse 连接

## 概述

Anysite CLI 可以将提取到的数据直接加载到指定的数据库连接中。它支持 **SQLite**（内置）、**PostgreSQL**
和 **ClickHouse**（通过可选依赖包）。连接信息保存在 `~/.anysite/connections.yaml` 中，并在所有 CLI
命令中通过名称引用。

## 支持的数据库

| 数据库 | 所需可选依赖包 | 适用场景 |
|----------|---------------|----------|
| **SQLite** | 无（内置） | 本地开发、单用户工作流、原型验证 |
| **PostgreSQL** | `pip install "anysite-cli[postgres]"` | 生产环境、多用户、大规模数据集 |
| **ClickHouse** | `pip install "anysite-cli[clickhouse]"` | 分析场景、列式存储、大规模聚合 |

> 
  `anysite db add` 也接受 `--type mysql` 和 `--type duckdb` — `mysql` 对应可安装的
  `anysite-cli[mysql]` 扩展，`duckdb` 对应数据集管道内部使用的格式。但在当前 CLI 版本中，这两者都没有
  可用的数据库适配器：除 `db add` 之外的任何命令（`db test`、`db insert`、`db query`、
  `db discover` 等）都会报错 `Unsupported database type`。目前请仅使用 `sqlite`、`postgres` 和
  `clickhouse`。

## 添加连接

  
#### SQLite

    SQLite 连接接受一个文件 **path（路径）**，而不是 `--database`：
    ```bash
    anysite db add mydb --type sqlite --path ./data/mydata.db
    ```
    如果文件不存在会自动创建。
  
  
#### PostgreSQL

    ```bash
    pip install "anysite-cli[postgres]"
    ```
    ```bash
    anysite db add pg --type postgres \
      --host localhost \
      --port 5432 \
      --database mydb \
      --user app \
      --password-env PGPASS
    ```
    或者使用环境变量中的连接 URL：
    ```bash
    anysite db add pg --type postgres --url-env DATABASE_URL
    ```
  
  
#### ClickHouse

    ```bash
    pip install "anysite-cli[clickhouse]"
    ```
    ```bash
    anysite db add ch --type clickhouse \
      --host ch.example.com \
      --port 8443 \
      --database analytics \
      --user app \
      --password-env CH_PASS \
      --ssl
    ```
    省略时端口默认为 `8123`（HTTP）；SSL 不会根据端口号自动启用 — 需要显式传入 `--ssl`。
  
  
#### Read-Only

    ```bash
    anysite db add replica --type postgres \
      --host replica.example.com \
      --database mydb \
      --user readonly_user \
      --password-env REPLICA_PASS \
      --read-only
    ```
    `--read-only` 强制将连接设为只读模式，会阻止写操作（`db insert`、`db upsert`、
    `db create-table`、`dataset load-db`）。发现命令（`db discover`）也会独立自动检测只读状态。
  

> 
  请使用 `--password-env ` 引用环境变量，而不是直接在命令行上传入 `--password`。`--password`
  和 `--password-env` 互斥，不能同时使用。

## 管理连接

```bash
# List all connections
anysite db list

# Show details for one connection
anysite db info mydb

# Test a connection
anysite db test pg

# Remove a connection (asks for confirmation unless --force)
anysite db remove pg --force
```

## 连接参考

| 选项 | 适用对象 | 描述 |
|--------|------------|-------------|
| `--type`, `-t` | 所有类型 | `sqlite`、`postgres` 或 `clickhouse`（其他可接受但未实现的取值见上方提示） |
| `--path` | sqlite | 数据库文件路径 |
| `--host`, `-h` | postgres、clickhouse | 数据库主机 |
| `--port`, `-p` | postgres、clickhouse | 数据库端口（除 ClickHouse 会回退到 `8123` 外，CLI 层没有默认值） |
| `--database`, `-d` | postgres、clickhouse | 数据库/模式名称 |
| `--user`, `-u` | postgres、clickhouse | 用户名 |
| `--password` | postgres、clickhouse | 密码，以明文存储在 `connections.yaml` 中（建议改用 `--password-env`） |
| `--password-env` | postgres、clickhouse | 存放密码的环境变量名称 |
| `--url-env` | postgres、clickhouse | 存放完整连接 URL 的环境变量 |
| `--ssl` | clickhouse | 启用 SSL |
| `--read-only` | 所有类型 | 强制连接为只读，阻止写操作 |

> 
  ClickHouse 通过 [clickhouse-connect](https://clickhouse.com/docs/en/integrations/python) 使用
  HTTP 协议。

## 后续步骤

  
#### Database Discovery

    自动发现数据库结构并浏览已保存的目录
  
  
#### Database Operations

    对数据库进行插入、查询和同步操作