# sql 快速参考

`@ts-grm/sql` 提供驱动、执行、事务与模式创建。

## newSqlClient

```ts
newSqlClient(driver, options): SqlClient
```

**驱动**：`SqliteDriver(DB)`、`PostgresDriver(pool)`、`MySqlDriver(pool)`、`OracleDriver / Oracle12Drivier(pool)`、`SqlServerDriver / SqlServer2012Driver(pool)`（均来自 `@ts-grm/sql` 顶层或 `transaction` 命名空间）。

**主要选项**（详见「驱动接入」）：

| 选项 | 默认 | 说明 |
|---|---|---|
| `strategy` | `spi.UPPER_SNAKE_CASE_DATABASE_NAMING_STRATEGY` | 命名策略 |
| `defaultBatchSize` / `defaultListBatchSize` | 128 / 16 | 批加载上限 |
| `maxJoinFetchDepth` / `maxJoinFetchOffset` | 5 / 0 | join 取形限制 |
| `sqlLogger` | `{ pretty: false, parameter: "PLACEHOLDER" }` | 日志（`COMMENT`/`INLINE` 可选） |
| `filterManager` / `entityManager` | — | 过滤器 / 模型发现 |
| `isUnorderedPaginationDisabled` | false | 无序分页控制 |
| `executorCreator` | 恒等 | 事务执行器包装 |

## SqlClient 方法

| 方法 | 用途 |
|---|---|
| `findOne / findOneOrNull / findOneOrUndefined(view, criteria)` | 便捷单行查询 |
| `findMany(view, options)` / `findRange` / `findPage` | 批量查询 |
| `createQuery(model, cb)` | 命令式查询（返回查询对象） |
| `execute(...)` | 事务（传播/隔离/超时，见「事务」） |
| `save(input, obj, options?)` | 变更 API（**上游尚未实现**，见「变更 API」章） |
| `createSchema()` | 生成建表/删表 DDL（沙盒内勿 execute） |

**查询对象收尾**：`fetchList / fetchRequired / fetchOptional / fetchPage / fetchRange / fetchCount`（无 `fetchOne`）。

## 事务

```ts
execute(fn)                       // REQUIRED
execute(propagation, fn)          // 6 传播级别
execute(isolation, fn)            // 4 隔离级别
execute({propagation, isolation, timeout(ms)}, fn)
```

## 工具

- `FilterManager`（过滤器类型与注册）；`sqlerr`（`@ts-grm/sql` 错误族）；
- `spi` 命名空间：驱动/执行层 SPI（一般用于扩展层）。

## 版本适配说明

- 本文按 `@ts-grm/core` / `@ts-grm/sql` **0.0.x** 适配；发版后对照 `docs/upstream-issues.md` 核销已知缺陷；
- 保存/Input DTO 相关 API 以「变更 API」章为准（设计预览）。