# 驱动接入与 SqlClient

`@ts-grm/sql` 的一切从 `newSqlClient(driver, options)` 开始。**driver** 决定方言与连接，**options** 调优执行行为：

```ts
// 在你的项目里（示例工作区已提供 client，见下）
import { newSqlClient, SqliteDriver, PostgresDriver } from '@ts-grm/sql'
import Database from 'better-sqlite3'
import { Pool } from 'pg'

// SQLite
const client = newSqlClient(new SqliteDriver(new Database('app.db')), {})

// PostgreSQL
const postgres = newSqlClient(
  new PostgresDriver(new Pool({ connectionString: process.env.DATABASE_URL })),
  { strategy: spi.UPPER_SNAKE_CASE_DATABASE_NAMING_STRATEGY },
)
```

## 驱动的六个选择

| 驱动 | 构造参数 | 说明 |
|---|---|---|
| `SqliteDriver` | `better-sqlite3` 实例 | 本地开发/测试最顺手 |
| `PostgresDriver` | `pg.Pool` | 生产首选 |
| `MySqlDriver` | `mysql2/promise` pool | MySQL 8 |
| `OracleDriver` / `Oracle12Drivier` | `OraclePool`（`oracledb`） | Oracle 12c 及以下用后者 |
| `SqlServerDriver` / `SqlServer2012Driver` | `SqlServerPool` | SQL Server（2012 走专门一版） |

各驱动对分页、锁、日期等的差异见[「方言差异」](../sql-backend/dialect)页。

## SqlClientOptions 速览

| 选项 | 默认 | 作用 |
|---|---|---|
| `strategy` | `UPPER_SNAKE_CASE_DATABASE_NAMING_STRATEGY` | 表/列/中间表命名策略（[「命名策略」](../sql-backend/naming)页） |
| `defaultBatchSize` / `defaultListBatchSize` | 128 / 16 | 关联批加载 IN 上限（主/集合方向） |
| `maxJoinFetchDepth` | 5 | join 取形最大嵌套深度（0~10） |
| `maxJoinFetchOffset` | 0 | 批加载退化为 join 的偏移阈值 |
| `sqlLogger` | `{ pretty: false, parameter: "PLACEHOLDER" }` | SQL 日志格式（[「SQL 日志与追踪」](../sql-backend/logging)页） |
| `filterManager` / `entityManager` | — | 过滤器 / 模型发现（[「模式创建与实体管理器」](../sql-backend/schema)页） |
| `isUnorderedPaginationDisabled` | false | 无序分页是否禁用 |
| `executorCreator` | 恒等 | 事务执行器包装点 |

构建时对非法值直接抛错（如 `defaultBatchSize < 2`、`maxJoinFetchDepth` 越界）。

## 示例工作区里的 client

示例工作区的 `infra/sql-client.ts`（只读）是上面接线方式的一份"已替你完成"样本。因此**在示例中直接使用 `sqlClient` 即可**，无需重复创建客户端；查看该文件（点开工作区 tab）可对照真实接线写法。

## 下一步

client 手里的第一件事是**怎么命名表与列**——下一节命名策略。