> ## 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 Database 工具。

HeavenBase 的 SQL 系列后端现在使用原生 `heavenbase.utils.db.Database` 门面来管理连接生命周期、schema 检查、表变更、注释、统计、采样和执行结果。旧工具栈只作为参考材料，不再是主包包依赖。

## 支持的 provider

`Database` 从 `src/heavenbase/resources/configs/default.yaml` 读取提供商 (Provider) 配置；bootstrap 配置只在配置仓库初始化前使用。当前预设包括 SQLite、DuckDB、PostgreSQL、MySQL 兼容引擎、SQL Server、Oracle、Trino，以及使用 MySQL wire 协议的 StarRocks。

`sqlalchemy>=2.0` 是 HeavenBase 主依赖。非 SQLite provider 仍需要安装对应驱动，例如 `psycopg2`、`pymysql`、`pymssql`、`oracledb` 或 `trino`。

## 执行行为

* 配置 bootstrap 会先读取文件配置，然后通过 `Database` 打开配置仓库。
* Engine 按解析后的 database spec 共享，并显式记录 disposed 状态。相同 provider/database/pool 参数的两个 `Database` 实例会使用同一个 SQLAlchemy engine 和 pool。
* 首次访问 engine 时会 best-effort autocreate。若 superuser 或建库凭据不可用，HeavenBase 会继续尝试直连，以便已有数据库仍能使用。
* 显式删除使用 `db.drop_database(force=True)`。SQLite/DuckDB 删除文件，PostgreSQL/MySQL/MSSQL/StarRocks 删除 database，Oracle 删除目标 user/schema 但不删除 PDB service。Trino catalog 由 connector 管理，因此不会自动创建或删除 catalog。
* `readonly` 是显式语义。默认是 `readonly=False`；传 `readonly=True` 会拒绝不能确信为只读的语句。只有传 `readonly=None` 时才启用保守自动推断，用于决定 commit/rollback。
* 原始 SQL 会在执行前规范化占位符。支持 `:name`、`?`、`%s`、`%(name)s`、`$name` 和 `$1`，参数可用 dict、位置 tuple/list、list-of-dicts batch，以及驱动支持时的 list-of-tuples batch。裸 `?` 只会在传入位置参数时重写，因此 PostgreSQL JSON 操作符 `payload ? 'key'`、`?|` 和 `?&` 会保持有效；`?::int` 这类 PostgreSQL cast 也会在占位符重写后保留。
* `safe=True` 会把执行错误转成 `SQLResponse(ok=False)`。在活动事务里，safe failure 会把事务标记为失败，context 退出时回滚，除非调用方显式 `rollback()` 后继续处理。`execute_many(..., safe=True)` 默认在第一条失败语句处停止并回滚；`autocommit=True` 表示显式选择逐条提交的 best-effort 行为。
* SQL healing 仍是未来工作，并单独跟踪。当前 API 返回或抛出原始数据库错误，不调用 LLM 修复路径。

## 工具接口

`Database` 提供 schema 列表、表/视图/列检查、建表和表变更、方言支持时的注释、精确分位数、字符串长度统计、无需假设 `id` 列的确定性采样，以及 `SQLResponse` 导出 helper：dict/list、pandas、NumPy、PyArrow 和紧凑表格显示。

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

db = hb.Database(provider="sqlite", database="workspace.db")
db.execute("create table if not exists items (id text primary key, name text)")
db.execute("insert into items (id, name) values (:id, :name)", {"id": "a", "name": "alpha"})
db.execute("insert into items (id, name) values (?, ?)", ("b", "beta"))

db.tables()
db.columns("items")
db.n_rows("items")

rows = db.execute("select id, name from items", readonly=True)
rows.to_dicts(columns=["id"])
rows.table_display()
```

只有在确实希望 HeavenBase 推断语句是否只读时才使用 `readonly=None`。未知语句会按可写语句处理。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
db.execute("with input(id) as (select 'c') select id from input", readonly=True)
db.execute("select count(*) from items", readonly=None)
```

数据库生命周期 helper 是显式的：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
db = hb.Database(provider="postgres", database="workspace_demo")
db.execute("select 1")  # first engine access may autocreate the database
db.drop_database(force=True)
```

唯一支持的 Database API 是 canonical 命名模型。使用 `tables()`、`columns()`、`pks()`、`fks()`、`n_rows()`、`sample()`、`create_table()`、`add_table_col()`、`clear_table()` 和 `drop_table()`；不保留旧兼容别名，例如 `db_tabs`、`tab_cols`、`row_sample` 和 `create_tab`。

如果包装层刻意保持得比 SQLAlchemy 小，可以直接使用公开 engine 或 ORM 执行路径：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from sqlalchemy import select

db.engine
db.orm_execute(select(my_table.c.id), readonly=True)
```

`SQLResponse` 默认校验投影列。只有在希望缺失列渲染为 `None` 的宽松导出/显示代码中，才传 `check=False`。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
rows.to_dicts(columns=["missing"], check=False)
hb.table_display(rows, columns=["name"])
```

<br />