lakutata 3.0.0 → 3.1.0

package/doc/zh/DTOValidation.md

@@ -1,6 +1,6 @@
 # Lakutata DTO 与数据校验
 
-**DTO**（数据传输对象）是用校验规则声明属性的类。框架用它们校验对象的选项（`@Configurable`）、方法的参数和返回值（`@Accept`、`@Return`）以及控制器动作的输入。`DTO` 由 `lakutata` 导出，相关装饰器由 `lakutata/decorator/dto` 导出；校验引擎是框架自带的，API 与 joi 相同（并扩展了 bigint 和下文的数值类型）。
+**DTO**（数据传输对象）是用校验规则声明属性的类。框架用 DTO 校验对象的选项（`@Configurable`）、方法的参数和返回值（`@Accept`、`@Return`）以及控制器动作的输入。`DTO` 由 `lakutata` 导出，相关装饰器由 `lakutata/decorator/dto` 导出；校验引擎是框架自带的，API 与 joi 相同（并扩展了 bigint 和下文的数值类型）。
 
 ## 1. 定义 DTO
 
@@ -40,23 +40,35 @@ class CustomerDTO extends DTO {
 
 校验规则由 `DTO` 的静态方法构建：`DTO.String()`、`DTO.Number()`、`DTO.BigInt()`、`DTO.Boolean()`、`DTO.Date()`、`DTO.Binary()`、`DTO.Symbol()`、`DTO.Object()`、`DTO.Array()`、`DTO.Alternatives()`、`DTO.Any()`、`DTO.Function()`、`DTO.AsyncFunction()`、`DTO.Class()`、`DTO.InstanceOf()`、`DTO.Cron()`、`DTO.Glob()`、`DTO.Ref()`、`DTO.Link()` 等。规则方法与 joi 相同（`.required()`、`.optional()`、`.default()`、`.valid()`、`.min()`、`.max()`、`.pattern()`、`.email()`、`.uri()` 等）。
 
-- **默认严格**：类型不对的值会被拒绝，而不是被转换（字符串 `'5'` 不是数字 5）。需要转换时调用 `.strict(false)`，例如 HTTP 的查询参数和路由参数总是字符串。
+- **默认严格**：类型不对的值会被拒绝，而不是被转换（字符串 `'5'` 不是数字 5）。需要转换时调用 `.strict(false)`，例如 HTTP 的查询参数和路由参数，它们总是字符串。
 - **数值类型**：`DTO.Number()` 提供整数类型 `int8`、`uint8`、`int16`、`uint16`、`int32`、`uint32`、`int64` 和 `uint64`（64 位类型限于 JavaScript 的安全整数范围），以及浮点类型 `float`（32 位范围）和 `double`。
-- **校验选项**：默认在遇到第一个错误时停止（`abortEarly`），并移除未知字段（`stripUnknown`）。DTO 作为校验规则使用时，可用 `MyDTO.options({...})` 指定其他选项。
+- **校验选项**：默认在遇到第一个错误时停止（`abortEarly`），并移除未知字段（`stripUnknown`）。`MyDTO.options({...})` 返回使用其他选项的 DTO 校验规则。
 - **DTO 类作为校验规则**：`MyDTO.Schema()` 是它的对象校验规则，`MyDTO.required()` 和 `MyDTO.optional()` 是标记为必填或可选的同一规则。凡是需要校验规则的地方（`@Accept`、`@Return`、动作装饰器）都可以直接使用 DTO 类。
 
 ## 2. 校验
 
 ```typescript
+import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
+
+class CustomerDTO extends DTO {
+    @Expect(DTO.String().min(2).required())
+    public name: string
+
+    @Expect(DTO.Number().integer().min(0).default(0))
+    public credit: number
+}
+
 //构造时校验：填充默认值，移除未知字段 "note"；数据不合法时抛出 InvalidValueException
-const customer: CustomerDTO = new CustomerDTO({name: 'Ada', email: 'ada@example.com', address: {city: 'London'}, note: 'vip'})
+const customer: CustomerDTO = new CustomerDTO({name: 'Ada', note: 'vip'})
 
 //DTO 实例会校验对其属性的每次修改：不合法的修改会抛出异常并被撤销
 customer.credit = 10
 
-//不创建实例直接校验：返回校验后的值，或抛出 InvalidValueException
-const data: CustomerDTO = CustomerDTO.validate({name: 'Ada', email: 'ada@example.com', address: {city: 'London'}})
-const later: CustomerDTO = await CustomerDTO.validateAsync({name: 'Ada', email: 'ada@example.com', address: {city: 'London'}})
+//不创建实例直接校验：返回校验后的数据（普通对象），或抛出 InvalidValueException
+const received: any = JSON.parse('{"name": "Ada"}')
+const data: CustomerDTO = CustomerDTO.validate(received)
+const later: CustomerDTO = await CustomerDTO.validateAsync(received)
 
 //只检查，不抛出异常
 const valid: boolean = CustomerDTO.isValid({name: ''})
@@ -72,11 +84,11 @@ const port: number = DTO.validate(8080, DTO.Number().port().required())
 | 装饰器 | 作用对象 | 效果 |
 |---|---|---|
 | `@Expect(schema)` | DTO 的属性 | 声明属性的校验规则 |
-| `@IndexSignature(schema)` | DTO 类 | 保留没有 `@Expect` 规则的字段并按该规则校验，而不是移除它们 |
+| `@IndexSignature(schema)` | DTO 类 | 保留没有 `@Expect` 规则的字段，并按这条规则校验它们，而不是移除 |
 | `@Accept(...schemas)` | 方法 | 每次调用时按位置校验参数；失败时抛出 `InvalidMethodAcceptException` |
 | `@Return(schema)` | 方法 | 每次调用时校验返回值（异步方法会等待其结果）；失败时抛出 `InvalidMethodReturnException` |
 
-`@Accept` 和 `@Return` 把校验后的值交给方法（或调用方）：已填充默认值、已移除未知字段。用 DTO 类校验参数或返回值时，得到的是普通对象，而不是该类的实例。缺少的参数会被接受，除非它的规则是必填的（`MyDTO.required()`）。
+`@Accept` 和 `@Return` 把校验后的值交给方法（或调用方）：默认值已填充，未知字段已移除。用 DTO 类校验参数或返回值时，得到的是普通对象，而不是该类的实例。缺少的参数会被接受，除非它的规则是必填的（`MyDTO.required()`）。
 
 ```typescript
 import {Component, DTO} from 'lakutata'
@@ -124,8 +136,8 @@ class Bank extends Component {
 
 ## 4. 框架中的 DTO
 
-- **对象选项**：`@Configurable(schema)`（来自 `lakutata/decorator/di`）校验组件、提供者或模块的选项；见 [Core](Core.md)。
-- **控制器动作**：传给 `@GET`、`@POST`、`@CLIAction`、`@ServiceAction` 等的 DTO 校验动作的输入；输入不合法时以状态码 400 响应。见 [ActionPattern](ActionPattern.md)。
+- **对象选项**：`@Configurable(schema)`（来自 `lakutata/decorator/di`）校验组件或提供者的选项；见 [Injection](Injection.md)。
+- **控制器动作**：传给 `@GET`、`@POST`、`@CLIAction`、`@ServiceAction` 等的 DTO 校验动作的输入；输入不合法时以状态码 400 响应。见 [Controllers](Controllers.md)。
 - **分页**（`lakutata/dtos`）：`PaginationSearchDTO` 和 `PaginationResultDTO` 是分页动作的输入和结果，`paginator` 负责计算分页；`FlexibleDTO` 是接受任意字段的 DTO。
 - **校验消息**：错误消息支持多语言；`lakutata` 中的 `registerValidationMessages`、`runInValidationLanguage` 和 `currentValidationLanguage` 管理其语言，I18n 组件的语言中间件为每个请求设置语言（见 [I18n](I18n.md)）。
 
@@ -137,36 +149,54 @@ DTO 和校验规则可以与 JSON Schema（draft 04、06、07、2019-09 和 2020
 
 ```typescript
 import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
 import {toJsonSchema} from 'lakutata/dtos'
 
+class UserDTO extends DTO {
+    @Expect(DTO.Number().integer().required())
+    public id: number
+
+    @Expect(DTO.String().required())
+    public name: string
+}
+
 UserDTO.toJsonSchema()                  //JSON Schema 2020-12（默认）
 UserDTO.toJsonSchema('draft-07')        //'draft-2020-12' | 'draft-2019-09' | 'draft-07' | 'draft-04'
 UserDTO.toOpenAPIJsonSchema()           //OpenAPI 3.1（默认），或 '3.0'
 toJsonSchema(DTO.String().email(), {target: 'openapi-3.0'})   //任意校验规则，或 DTO 类
 ```
 
-- 生成的 JSON Schema 描述的是校验规则在不做转换时接受的值，因此 ajv（配合 ajv-formats）等校验器接受的值与之完全一致；JSON Schema 无法表达的内容（自定义规则、对其他值的引用、类型转换）会被丢弃，所以 JSON Schema 接受的值只会更多，不会更少。
-- 未知字段遵循校验选项：在 lakutata 的默认选项（`allowUnknown`、`stripUnknown`）下，对象接受未知字段；使用其他选项时通过 `preferences` 传入。
-- 数值类型转换为整数边界（`int8` 到 `uint64`）和浮点范围；OpenAPI 还会给出 `int32`、`int64`、`float` 和 `double` 格式名。
+- 生成的 JSON Schema 描述的是校验规则在不做转换时接受的值，ajv（配合 ajv-formats）等校验器接受的也是这些值。JSON Schema 无法表达的内容（自定义规则、对其他值的引用、类型转换）会被省略，所以 JSON Schema 可能接受原规则拒绝的值，但不会拒绝原规则接受的值。
+- 未知字段遵循校验选项：在 lakutata 的默认选项（`allowUnknown`、`stripUnknown`）下，对象接受未知字段；要按其他选项转换，通过 `preferences` 传入这些选项。
+- 数值类型转换为整数边界（`int8` 到 `uint64`）和浮点范围；在 OpenAPI 中还会带上 `int32`、`int64`、`float` 和 `double` 格式。
 
 ### 5.2 导入
 
 ```typescript
-import {DTO} from 'lakutata'
+import {readFileSync} from 'node:fs'
+import {DTO, type JSONSchema} from 'lakutata'
 import {fromJsonSchema} from 'lakutata/dtos'
 
-const schema = fromJsonSchema({type: 'object', properties: {id: {type: 'integer'}}, required: ['id']})
+const userJsonSchema: JSONSchema = {
+    type: 'object',
+    properties: {id: {type: 'integer'}, name: {type: 'string'}},
+    required: ['id']
+}
+
+//校验规则
+const schema = fromJsonSchema(userJsonSchema)
 DTO.validate({id: 1}, schema)
 
-//生成 DTO 类，它是调用该方法的类的子类
+//生成 DTO 类，它是调用 fromJsonSchema() 的那个类的子类
 const UserDTO = DTO.fromJsonSchema(userJsonSchema)
 const user = new UserDTO({id: 1, name: 'Alice'})
 
 //OpenAPI 文档中各对象 schema（components.schemas）对应的 DTO 类，按名称取用
+const openApiDocument: Record<string, unknown> = JSON.parse(readFileSync('openapi.json', 'utf8'))
 const {Pet, Person} = DTO.fromOpenAPI(openApiDocument)
 ```
 
-- 导入的校验规则按 JSON Schema 的语义校验：不转换值（`convert: true` 时转换），未知字段遵循 `additionalProperties`，格式校验与 ajv-formats 一致，并会填充默认值。
+- 导入的校验规则按 JSON Schema 的语义校验：不转换值（除非传入 `convert: true`），未知字段遵循 `additionalProperties`，格式校验与 ajv-formats 一致，并会填充默认值。
 - 引用通过 JSON pointer、`$anchor` 和 `$id` 解析（其他文档通过 `schemas` 传入，OpenAPI 文档通过 `document` 传入）；支持递归引用。
 - 版本从 `$schema` 读取，或通过 `dialect` 指定（默认 2020-12）。
-- 对 lakutata 的校验规则而言，JSON Schema 会丢失信息（自定义规则、类型转换）：要原样存储并恢复校验规则，请保存它的 `describe()` 输出（不含函数时是一个 JSON 值），再用 `DTO.Build(description)` 重建。
+- 把 lakutata 的校验规则转换为 JSON Schema 会丢失信息（自定义规则、类型转换）：要原样存储并恢复校验规则，请保存它的 `describe()` 输出（不含函数时是一个 JSON 值），再用 `DTO.Build(description)` 重建。

package/doc/zh/Database.md

@@ -0,0 +1,175 @@
+# Lakutata 数据库
+
+lakutata 的数据库层是 `@lakutata/orm` 包，基于 [TypeORM](https://typeorm.io) 1 构建。TypeORM 的源码已经包含在这个包里，所以不会再安装 `typeorm` 包。`lakutata` 通过四个子路径重新导出它：
+
+| 子路径 | 提供的内容 |
+|---|---|
+| `lakutata/com/database` | `Database` 组件（整个应用共享的连接）和 `buildDatabaseOptions` |
+| `lakutata/provider/database` | `Database` 提供者（每次解析都有自己的连接） |
+| `lakutata/decorator/orm` | 实体的装饰器（`@Entity`、`@Column`、各种关系……） |
+| `lakutata/orm` | TypeORM 的 API：仓储、实体管理器、查询操作符、迁移、错误 |
+
+数据库驱动需要另外安装，见 [DatabaseDrivers](DatabaseDrivers.md)。实体、查询和事务见 [Entities](Entities.md)，表结构的变更见 [Migrations](Migrations.md)。
+
+## 1. Database 组件
+
+`buildDatabaseOptions` 用 TypeORM 的连接选项声明一个 `Database` 组件：
+
+```typescript
+import {Application, Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {buildDatabaseOptions, Database} from 'lakutata/com/database'
+import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+
+@Entity('users')
+class User {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column({type: 'varchar', length: 100})
+    public name: string
+
+    @Column({unique: true})
+    public email: string
+}
+
+class Users extends Component {
+    //声明为 "db" 的组件
+    @Inject('db')
+    protected readonly db: Database
+
+    public async register(name: string, email: string): Promise<User> {
+        return await this.db.getRepository(User).save({name: name, email: email})
+    }
+
+    public async find(id: number): Promise<User | null> {
+        return await this.db.getRepository(User).findOneBy({id: id})
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'users.app',
+        name: 'Users',
+        components: {
+            db: buildDatabaseOptions({
+                type: 'postgres',
+                url: process.env.DATABASE_URL,
+                entities: [User],
+                //只用于开发：表结构跟随实体变化。生产环境请使用迁移
+                synchronize: true
+            }),
+            users: {class: Users}
+        },
+        bootstrap: ['db']
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const users: Users = await app.getObject<Users>('users')
+        await users.register('Ada', 'ada@example.com')
+    })
+```
+
+- 组件在创建时连接数据库。列在 `bootstrap` 里时，它在应用启动过程中连接，连接失败会让启动失败；否则在第一次被用到时才连接。
+- 应用停止时，它会断开连接。
+- 其他对象按名字注入它（`@Inject('db')`），或者用 `getObject('db')` 获取。
+
+## 2. 连接选项
+
+这些选项就是 TypeORM 的选项，会原样交给 TypeORM。各驱动特有的选项见 [DatabaseDrivers](DatabaseDrivers.md)，通用的选项有：
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `type` | 必填 | 驱动：`'postgres'`、`'mysql'`、`'better-sqlite3'`…… |
+| `entities` | | 实体类、`EntitySchema`，或者编译后文件的 glob（`'build/entities/*.js'`） |
+| `synchronize` | `false` | 每次连接时按实体更新表结构。只用于开发 |
+| `logging` | `false` | TypeORM 记录什么：`true`，或者 `'query'`、`'error'`、`'schema'`、`'warn'`、`'info'`、`'log'` 组成的列表 |
+| `logger` | | TypeORM 的日志写到哪里：`'advanced-console'`、`'simple-console'`、`'file'`、`'debug'`，或者自己实现的日志记录器 |
+| `maxQueryExecutionTime` | | 记录比这个时间（毫秒）慢的查询 |
+| `poolSize` | | 连接池的连接数 |
+| `extra` | | 传给驱动客户端的选项 |
+| `migrations`、`migrationsRun`、`migrationsTableName`、`migrationsTransactionMode` | | 迁移（见 [Migrations](Migrations.md)） |
+| `subscribers` | | 实体订阅者 |
+| `namingStrategy` | | 表、列和索引的命名方式 |
+| `cache` | | 查询结果的缓存：`true`（存在数据库的一张表里），或者 `{type: 'redis', options}` |
+| `invalidWhereValuesBehavior` | `{null: 'ignore', undefined: 'ignore'}` | where 条件中的 `null` 和 `undefined` 如何处理（见下文） |
+
+**条件中的 `null` 和 `undefined`。** 默认情况下，where 条件中值为 `null` 或 `undefined` 的属性会被忽略，这与 TypeORM 0.3 相同；TypeORM 1 的默认行为则是抛出错误。所以 `findOneBy({id: undefined})` 会查到表里的第一行：用请求中的值查询之前要先检查它们，或者设置 `invalidWhereValuesBehavior: {undefined: 'throw'}`，让这类值抛出错误（给出的每个键会替换它的默认值）。
+
+**用 TypeORM 0.3 创建的数据库。** 如果表名或列名中有非 ASCII 字符，TypeORM 1 给它们的索引和约束起的名字会不同，生成的迁移就会重命名它们。`namingStrategy: new NamingStrategyV03()`（来自 `lakutata/orm`）可以保持 TypeORM 0.3 的命名。
+
+**存在 Redis 中的查询缓存**（`cache: {type: 'redis'}` 或 `'ioredis'`）需要安装 `redis` 或 `ioredis` 包。
+
+## 3. 组件提供的功能
+
+组件提供 TypeORM 数据源的 API：
+
+| 方法或属性 | 作用 |
+|---|---|
+| `getRepository(Entity)` | 实体的仓储（在 MongoDB 上是 `MongoRepository`） |
+| `getMongoRepository(Entity)`、`getTreeRepository(Entity)` | MongoDB 的仓储、树形实体的仓储 |
+| `manager` | 实体管理器 |
+| `transaction(fn)`、`transaction(isolationLevel, fn)` | 在事务中执行一个函数 |
+| `query(sql, parameters)` | 执行 SQL；占位符在 PostgreSQL 上是 `$1, $2…`，在 MySQL 和 SQLite 上是 `?` |
+| `createQueryBuilder(Entity, alias)` | 查询构造器 |
+| `createQueryRunner(mode)` | 连接池中的一个连接，用来手动控制事务；`'slave'` 从副本读取 |
+| `synchronize()` | 按实体更新表结构 |
+| `runMigrations()`、`undoLastMigration()`、`showMigrations()` | 执行、回退和列出迁移 |
+| `hasMetadata(Entity)`、`getMetadata(Entity)` | 是否认识某个实体，以及它的元数据 |
+
+## 4. Database 提供者
+
+`lakutata/provider/database` 中的 `Database` 有同样的 API，但它是**瞬态**的：每次解析（`@Inject`、`getObject()`）都会创建一个新实例，打开自己的连接池；它随创建它的对象或容器一起销毁时，连接池也会关闭。它适合短时的任务（一个作业、一个脚本、每个客户一个数据库），而应用中的请求共享组件。
+
+```typescript
+import {Application} from 'lakutata'
+import {buildDatabaseOptions, Database} from 'lakutata/provider/database'
+import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+
+@Entity('reports')
+class Report {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column()
+    public title: string
+}
+
+Application
+    .run(() => ({
+        id: 'reports.app',
+        name: 'Reports',
+        providers: {
+            reports: {
+                ...buildDatabaseOptions({type: 'postgres', url: process.env.REPORTS_URL}),
+                //加到连接选项的实体中
+                entities: [Report]
+            }
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        //在这里打开连接，随应用一起关闭
+        const database: Database = await app.getObject<Database>('reports')
+        console.log(await database.getRepository(Report).count())
+    })
+```
+
+## 5. 多个数据库
+
+每个数据库都是一个独立的组件，按各自的名字注入：
+
+```typescript
+import {Application} from 'lakutata'
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+Application.run(() => ({
+    id: 'shop.app',
+    name: 'Shop',
+    components: {
+        db: buildDatabaseOptions({type: 'postgres', url: process.env.DATABASE_URL, entities: []}),
+        analytics: buildDatabaseOptions({type: 'mysql', url: process.env.ANALYTICS_URL, entities: []})
+    },
+    bootstrap: ['db', 'analytics']
+}))
+```
+
+一个实体可以属于多个数据库。它的仓储来自调用 `getRepository()` 的那个数据库。

package/doc/zh/DatabaseDrivers.md

@@ -0,0 +1,261 @@
+# Lakutata 数据库驱动
+
+数据库的 `type` 选项决定使用哪个驱动。安装 `lakutata` 时不会安装驱动包：根据你的数据库，另外安装对应的驱动。
+
+| 数据库 | `type` | 需要安装 |
+|---|---|---|
+| PostgreSQL | `postgres` | `pg`（8.5 或更高） |
+| CockroachDB | `cockroachdb` | `pg` |
+| MySQL、MariaDB | `mysql`、`mariadb` | `mysql2`（3.15.3 或更高） |
+| SQLite | `better-sqlite3` | `better-sqlite3`（12） |
+| WebAssembly 版的 SQLite | `sqljs` | `sql.js`（1.4 或更高） |
+| Microsoft SQL Server | `mssql` | `mssql`（12） |
+| Oracle | `oracle` | `oracledb`（6.3 或更高，或 7） |
+| MongoDB | `mongodb` | `mongodb`（7） |
+| 嵌入应用内的 MongoDB | `mongo-embedded` | `mingo`（7.2 或更高）和 `bson`（7）；见 [MongoEmbedded](MongoEmbedded.md) |
+| SAP HANA | `sap` | `@sap/hana-client`（2.14 或更高） |
+| Google Cloud Spanner | `spanner` | `@google-cloud/spanner`（8） |
+| 通过 Data API 访问的 Amazon Aurora | `aurora-mysql`、`aurora-postgres` | `typeorm-aurora-data-api-driver`（3） |
+
+```bash
+npm install lakutata pg
+```
+
+没有 `sqlite` 这个类型：SQLite 文件使用 `better-sqlite3`；在无法运行原生模块的环境中使用 `sqljs`。TypeORM 还有面向移动平台的驱动（`capacitor`、`cordova`、`expo`、`nativescript`、`react-native`），lakutata 不以这些平台为目标。
+
+## 所有驱动通用的规则
+
+- 连接选项会原样交给 TypeORM，TypeORM 不会检查它们：缺少主机或密码时，由驱动在连接数据库时报错。
+- `extra` 会传给驱动的客户端（连接池、连接），放在其他选项之后：用它设置 TypeORM 没有提供选项的配置。
+- `driver` 直接给出驱动模块本身（`driver: require('pg')`），不由 lakutata 去加载驱动包。
+- 下面的每个示例都声明一个 `Database` 组件。`Database` 提供者的选项相同（见 [Database](Database.md)）。
+
+## PostgreSQL
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'postgres',
+    host: 'localhost',
+    port: 5432,
+    username: 'app',
+    password: process.env.DB_PASSWORD,
+    database: 'app',
+    //或者一次给出全部：url: 'postgres://app:secret@localhost:5432/app'
+    entities: []
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `url` | | 连接 URL，代替下面这些选项 |
+| `host`、`port`、`username`、`password`、`database` | | 服务器和数据库；`password` 可以是函数（同步或异步），用于读取会轮换的密钥 |
+| `ssl` | | `true`，或 Node.js 的 TLS 选项（`{ca, rejectUnauthorized}`） |
+| `schema` | 服务器的 `search_path`（通常是 `public`） | 表所在的 schema |
+| `poolSize` | 10（`pg` 的默认值） | 连接池的连接数 |
+| `connectTimeoutMS` | 不限 | 连接的超时时间 |
+| `applicationName` | | 在服务器活动列表中显示的名字 |
+| `uuidExtension` | `'uuid-ossp'` | UUID 列使用的扩展：`'uuid-ossp'` 或 `'pgcrypto'` |
+| `replication` | | `{master, slaves}`：读操作发往副本 |
+
+- **`bigint` 和 `numeric` 列以字符串返回**，以保持精度（`'9007199254740993'`、`'12.50'`）。如果数字就够用，可以用列的 `transformer` 转换。`parseInt8: true` 会让 `bigint` 列返回数字，但它修改的是 `pg` 在整个进程中的设置。
+- 安装了 `pg-native` 时会使用 `pg` 的原生客户端。流式查询（查询构造器的 `stream()`）需要 `pg-query-stream`。
+
+**CockroachDB** 使用同一个驱动，`type: 'cockroachdb'`，连接选项相同。必须给出它的 `timeTravelQueries` 选项（读操作是否使用 follower reads）；因冲突失败的事务会重试 5 次（`maxTransactionRetries`）。
+
+## MySQL 与 MariaDB
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'mysql',
+    host: 'localhost',
+    port: 3306,
+    username: 'app',
+    password: process.env.DB_PASSWORD,
+    database: 'app',
+    charset: 'utf8mb4',
+    entities: []
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `url`、`host`、`port`、`username`、`password` | | 服务器 |
+| `database` | | 数据库。必填，除非每个实体都指定了自己的数据库 |
+| `socketPath` | | 用 unix socket 代替主机和端口 |
+| `ssl` | | TLS 选项，或 TLS 配置文件的名字 |
+| `charset` | `'UTF8_GENERAL_CI'` | 字符集和排序规则：要支持完整的 Unicode（包括 emoji），用 `'utf8mb4'` |
+| `timezone` | `'local'` | 日期如何读写：`'local'`、`'Z'` 或偏移量（`'+08:00'`） |
+| `poolSize` | 10（`mysql2` 的默认值） | 连接池的连接数 |
+| `connectTimeout`、`acquireTimeout` | `10000` | 连接的超时时间，以及从连接池获取连接的超时时间 |
+| `replication` | | `{master, slaves}`：读操作发往副本 |
+
+- MariaDB 使用 `type: 'mariadb'`，选项相同。MariaDB 从 10.7 开始支持 `uuid` 列类型。
+- **`bigint` 和 `decimal` 列以字符串返回**，与 PostgreSQL 相同。
+- 一张表最多有一个自增列。在 TypeORM 的表结构同步中，MySQL 不支持 check 约束。
+- 只支持 `mysql2`，不支持旧的 `mysql` 包。
+
+## SQLite：better-sqlite3
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'better-sqlite3',
+    //一个文件（会自动创建它所在的目录），或 ':memory:'
+    database: 'data/app.sqlite',
+    enableWAL: true,
+    entities: []
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `database` | 必填 | 数据库文件，或 `':memory:'` |
+| `enableWAL` | `false` | 预写日志（WAL）：读操作不再等待写操作 |
+| `timeout` | `5000` | 语句等待被其他连接锁住的数据库的时间，单位毫秒 |
+| `readonly`、`fileMustExist` | `false` | 以只读方式打开文件；文件不存在时报错 |
+| `key` | | 加密密钥，用于带 SQLCipher 的 SQLite |
+| `prepareDatabase` | | `(db) => …`，连接打开后用 better-sqlite3 的连接调用它：设置 pragma、注册函数 |
+| `nativeBinding` | | 编译好的模块 `better_sqlite3.node` 的路径 |
+
+- 外键约束是生效的（`PRAGMA foreign_keys = ON`）。只有一个连接：不支持 `poolSize`。
+- **`bigint` 列以数字返回**：超过 2^53 的值会丢失精度。这类值请存在文本列中。
+- `better-sqlite3` 是原生模块，针对某个 Node.js 版本编译。Electron 应用需要针对它的 Electron 版本的构建（`electron-rebuild`，或 better-sqlite3 为 Electron 提供的预编译文件）；Bun 无法加载它（在 Bun 上使用 `sqljs`）。
+
+## SQLite：sql.js
+
+`sql.js` 是编译成 WebAssembly 的 SQLite：没有原生模块，所以在 Node.js、Bun、Electron 和浏览器中的表现都一样。整个数据库保存在内存中，发生变化时写入文件。
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'sqljs',
+    //连接时加载（如果文件存在），每次变化后写入
+    location: 'data/app.sqlite',
+    autoSave: true,
+    entities: []
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `location` | | 加载和保存的文件（在浏览器中是 `localStorage` 的键） |
+| `autoSave` | `false` | 每次变化后保存。需要 `location` 或 `autoSaveCallback` |
+| `autoSaveCallback` | | `(data: Uint8Array) => …`，代替写入 `location` |
+| `database` | | 要加载的数据库内容（`Uint8Array`），代替 `location` |
+| `useLocalForage` | `false` | 在浏览器中保存到 IndexedDB（通过 `localforage`），而不是 `localStorage` |
+| `sqlJsConfig` | | sql.js 初始化的选项（用 `locateFile` 指定它的 `.wasm` 文件） |
+
+- 没有 `autoSave` 时，在调用实体管理器（`SqljsEntityManager`）的 `saveDatabase()` 之前，什么都不会写到磁盘。有 `autoSave` 时，事务中的变化在事务提交后保存。
+- 每次保存都会写入整个文件：sql.js 适合小型数据库。
+- 与 better-sqlite3 相同，外键约束生效，`bigint` 列以数字返回。
+
+## Microsoft SQL Server
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'mssql',
+    host: 'localhost',
+    port: 1433,
+    username: 'sa',
+    password: process.env.DB_PASSWORD,
+    database: 'app',
+    options: {
+        //服务器使用自签名证书，比如开发环境
+        trustServerCertificate: true
+    },
+    entities: []
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `url`、`host`、`port`、`username`、`password`、`database` | | 服务器和数据库 |
+| `authentication` | | 用户名密码以外的认证方式：`{type: 'ntlm', ...}`、`{type: 'azure-active-directory-default', ...}`…… |
+| `schema` | 用户的默认 schema | 表所在的 schema |
+| `options.encrypt` | `true` | 加密连接 |
+| `options.trustServerCertificate` | `false` | 接受不是由受信任机构签发的证书 |
+| `options.instanceName` | | 命名实例 |
+| `pool` | | 连接池：`max`、`min`、`idleTimeoutMillis`（默认 30000）……（不支持 `poolSize`） |
+| `connectionTimeout`、`requestTimeout` | `15000` | 连接的超时时间，以及查询的超时时间 |
+
+- 由于 `encrypt` 默认开启，使用自签名证书的服务器（本地服务器、容器）会拒绝连接，除非 `trustServerCertificate` 为 `true`。
+- 事务不能嵌套。
+
+## Oracle
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'oracle',
+    host: 'localhost',
+    port: 1521,
+    serviceName: 'FREEPDB1',
+    username: 'app',
+    password: process.env.DB_PASSWORD,
+    entities: []
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `host`、`port`、`username`、`password` | | 服务器 |
+| `serviceName` 或 `sid` | | 数据库服务 |
+| `connectString` | 由上面的选项生成 | 连接字符串（`'localhost:1521/FREEPDB1'`、TNS 条目），代替上面的选项 |
+| `thickMode` | `false` | `oracledb` 的 thick 模式（使用 Oracle Client 库）：`true`，或 `{libDir, configDir}` |
+| `useUTC` | `false` | 以 UTC 读写日期 |
+| `poolSize` | | 连接池的连接数 |
+
+- `oracledb` 6 及以后的版本默认运行在 thin 模式下，不需要 Oracle Client。需要 thick 模式的功能时再设置 `thickMode`。
+- 表在用户自己的 schema 中。`useUTC` 会设置整个进程所有会话的时区（环境变量 `ORA_SDTZ`）。
+
+## MongoDB
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+import {Column, Entity, ObjectIdColumn} from 'lakutata/decorator/orm'
+import type {ObjectId} from 'lakutata/orm'
+
+@Entity('users')
+export class User {
+    @ObjectIdColumn()
+    public id: ObjectId
+
+    @Column()
+    public name: string
+}
+
+export const db = buildDatabaseOptions({
+    type: 'mongodb',
+    url: 'mongodb://localhost:27017/app',
+    entities: [User]
+})
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `url` | | 连接 URL |
+| `host`、`port`、`username`、`password`、`database` | `127.0.0.1`、`27017` | 没有 `url` 时的服务器 |
+| `authSource`、`replicaSet`、`tls`、`readPreference`、`writeConcern`…… | | MongoDB 客户端的选项 |
+| `poolSize` | | 最大连接数（`maxPoolSize`） |
+
+- 实体要有一个 `@ObjectIdColumn()`，即它的 `_id`。它的类型是 `lakutata/orm` 中的 `ObjectId`：在 ES 模块中 `import {ObjectId} from 'bson'` 得到的是另一个类，实体的 id 不是它的实例。
+- `getRepository()` 返回 `MongoRepository`，它带有 MongoDB 的方法（使用 MongoDB 操作符的 `find`、`aggregate`、`createCursor`……）。
+- TypeORM 对 MongoDB 不支持：查询构造器、`query()`、关系和级联、树形仓储、流式查询。**`transaction()` 会在没有事务的情况下执行它的函数**：函数失败时，已经写入的内容不会撤销。
+- `synchronize` 只创建索引。迁移需要手写（见 [Migrations](Migrations.md)）。
+
+## SAP HANA、Google Cloud Spanner 与 Amazon Aurora
+
+这些驱动原样来自 TypeORM：
+
+- **SAP HANA**（`sap`）：`host`、`port`、`username`、`password`、`database`、`schema`，加密连接的 `encrypt` 以及 `key`、`cert`、`ca`，还有 `pool`（`maxConnectedOrPooled`，默认 10）。
+- **Google Cloud Spanner**（`spanner`）：`projectId`、`instanceId`、`databaseId`，以及 `credentials`（`client_email`、`private_key`），不给出时使用运行环境中的凭据。它的类型中从 MySQL 复制来的其他选项不会被读取。
+- **通过 Data API 访问的 Amazon Aurora**（`aurora-mysql`、`aurora-postgres`）：`region`、`secretArn`、`resourceArn` 和 `database` 为必填；查询通过 AWS 的 HTTP API 发送，而不是通过数据库连接。