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

# 数据连接

> 将现有 SQL 数据库接入 HeavenBase 工作区 (Workspace)，并以 db-* 实体 (Entity) 浏览 schema。

<Note>
  本工作坊是 `demos/enterprise/01_connect_and_ingest.py` 的文档转录。它使用仓库中已提交的 seed 数据库 `demos/data/warehouse.db`。
</Note>

你将启用可选的 `database` 扩展，把现有 SQLite 数据仓库摄取为可浏览的 `db-*` 行，并通过常规 HeavenBase 查询与卡片搜索发现表。

<br />

## 1. 前置条件

在已同步 SQL 额外依赖的 HeavenBase 源码检出目录中：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk bash scripts/sync-env.bash -- --extra sql
rtk uv run python demos/data/seed_warehouse.py   # only if warehouse.db is missing
```

<br />

## 2. 启用 Database 扩展

`database` 扩展注册六个 schema 实体：`db-database`、`db-table`、`db-column`、`db-enum`、`db-snippet` 与 `db-predicate`。从 Python 摄取时需显式启用：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb
import heavenbase.ext as hb_ext

ws = hb.HeavenBase("ent-01-warehouse", backends={"main": {"type": "inmem"}})
ws.enable_extension("database")
```

<br />

## 3. 摄取现有数据库

`hb.ext.ingest_database` 接受工作区 SQL 后端 (Backend) 名称、DSN、本地 SQLite 路径或 `hb.Database` 实例。它使用 SQLAlchemy 的 `inspect()`，并在存储行中脱敏凭证：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils.files import pj, get_file_dir

DEMOS = get_file_dir("demos", abs=True)
WAREHOUSE_DB = pj(DEMOS, "data", "warehouse.db", abs=True)

result = hb_ext.ingest_database(ws, WAREHOUSE_DB, name="warehouse")
database_id = result["database"][0]

db_row = ws.get(database_id, entity="db-database")
print(db_row["name"], db_row["dialect"])
print(db_row["dsn_summary"])  # credentials redacted
```

运行完整脚本：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk uv run python demos/enterprise/01_connect_and_ingest.py
```

<br />

## 4. 浏览 Schema 行

像查询其他任何实体一样查询已摄取的表与列：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tables = (
    ws.query("db-table")
    .where({"database_id": database_id})
    .select("table_name", "row_estimate")
    .execute()
)
print(tables.to_str())

customers = next(row for row in tables.rows() if row["table_name"] == "customers")
columns = (
    ws.query("db-column")
    .where({"table_id": customers["object_id"]})
    .select("column_name", "dtype")
    .execute()
)
print(columns.to_str())
```

通过文本搜索发现表：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
discovered = ws.query("db-table").where({"table_name": {"$match": "customer"}}).execute()
print([row["table_name"] for row in discovered.rows()])
```

<br />

## Summary

* `database` 扩展将外部 SQL 数据库内省为 HeavenBase 一等实体。
* 摄取过程会脱敏凭证；导入 manifest 后若需要实时连接元数据，请重新运行摄取。
* 在注册 SQL snippet 或暴露 MCP 工具之前，schema 行即可查询与搜索。

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [数据分析工作坊](/quickstart/data-analysis-workshop) — Snippet、predicate 与 Agent 分析
  * [数据库集成](/integrations/databases) — 后端 (Backend) 族与连接模式
  * [Enterprise 演示轨道](https://github.com/Magolor/HeavenBase/tree/master/demos/enterprise) — 完整可运行脚本
</Tip>

<br />