@morlay/rdbkit 0.0.0-stage → 0.0.1-alpha.3

package/dist/index.d.mts

@@ -0,0 +1,518 @@
+/** 支持的方言。 */
+type DialectName = "sqlite" | "postgres";
+/** 现有结构的一小块：迁移只关心「有没有这张表 / 这一列 / 这个索引」。 */
+interface TableShape {
+  columns: ReadonlySet<string>;
+  indexes: ReadonlySet<string>;
+}
+/** 一个方言：类型映射、标识符、DDL 片段，以及读现有结构的查询。 */
+interface Dialect {
+  readonly name: DialectName;
+  /** 标识符引用（表名 / 列名 / 索引名）。 */
+  quote(identifier: string): string;
+  /** 带 schema 的表名（sqlite 忽略 schema）。 */
+  tableName(table: string, schema?: string): string;
+  /** 列类型（含自增主键的特殊写法）。 */
+  columnType(column: ColumnDef): string;
+  /** 读现有表的列与索引；表不存在返回 undefined。 */
+  readShape(database: ShapeReader, table: string, schema?: string): Promise<TableShape | undefined>;
+}
+/** 读结构所需的最小执行面（`database/wrap.ts` 的 `shapeReader` 把 `Database` 包成它）。 */
+interface ShapeReader {
+  query<T>(text: string, params?: readonly unknown[]): Promise<T[]>;
+}
+export declare function createDialect(name: DialectName): Dialect;
+/** 一列的定义 SQL（`"name" TEXT NOT NULL ...`）。 */
+declare function columnSql$1(dialect: Dialect, name: string, column: ColumnDef): string;
+/** 建表语句（IF NOT EXISTS；列与表级约束都由定义算出来）。 */
+export declare function createTableSql(dialect: Dialect, table: TableDef, schema?: string): string;
+/** 索引语句（`unique` 时是唯一索引）。 */
+export declare function createIndexSql(dialect: Dialect, table: TableDef, name: string, columns: readonly string[], unique?: boolean): string;
+/** 删列（只在显式允许破坏性变更时用）。 */
+export declare function dropColumnSql(dialect: Dialect, table: string, name: string): string;
+/** 删索引（只在显式允许破坏性变更时用）。 */
+export declare function dropIndexSql(dialect: Dialect, name: string): string;
+/** 加列语句（启动迁移只做「缺列则补」，不改类型、不删列）。 */
+export declare function addColumnSql(dialect: Dialect, table: string, name: string, column: ColumnDef): string;
+/**
+ * 片段里的一步：要么是一段 SQL 文本，要么是一个绑定参数。
+ * 参数不在片段里决定占位符——渲染时按方言给 `?` 或 `$n`。
+ */
+type FragPart = {
+  readonly text: string;
+  readonly only?: DialectName;
+} | {
+  readonly param: unknown;
+  readonly only?: DialectName;
+};
+/**
+ * SQL 片段是**惰性的迭代器**（与 Golang `sqlfrag` 的 `iter.Seq2[string, []any]` 对齐）：
+ * 组合时不拼字符串，只有渲染 / 执行时才逐段展开。可重复消费（每次调用重新生成）。
+ */
+type Fragment = () => Iterable<FragPart>;
+/**
+ * 把 `?` 占位符与参数列表编成片段（便捷构造；我们生成的 SQL 只含占位符，不含字面量 `?`）。
+ */
+export declare function fragment(sql: string, params?: readonly unknown[]): Fragment;
+/** 按顺序拼接（`separator` 只在两个非空片段之间插入，片段内部的各步不拆开）。 */
+export declare function concat(fragments: readonly (Fragment | string)[], separator?: string): Fragment;
+/** 渲染成某方言的 SQL：SQLite 保持 `?`，PostgreSQL 用 `$1..$n`。 */
+export declare function render(fragment: Fragment, dialect: DialectName): {
+  text: string;
+  params: unknown[];
+};
+declare namespace expr_d_exports {
+  export { ColumnRef, Condition, ExprOperand, Operand, OperandInput, Value, add, always, and, between, coalesce, column, columnSql, countIf, eq, excluded, exists, expr, gt, gte, inList, inSubquery, isDistinctFrom, isNotNull, isNull, jsonInt, jsonText, like, localDay, lower, lt, lte, maxOf, ne, never, not, notInList, notInSubquery, notNull, operandSql, or, raw, toInt, value };
+}
+/** 列引用：查询构建器统一用双引号（两种方言都认）；`__value` 只做类型携带。 */
+interface ColumnRef<T = unknown> {
+  readonly kind: "column";
+  readonly table?: string;
+  readonly name: string;
+  readonly __value?: T;
+}
+/** 字面参数（值走绑定，不拼字符串）。 */
+interface Value {
+  readonly kind: "value";
+  readonly value: unknown;
+}
+/** 表达式操作数（聚合、函数调用这类不是列也不是字面量值的东西）。 */
+interface ExprOperand<T = unknown> {
+  readonly kind: "expr";
+  readonly sql: string;
+  readonly params: readonly unknown[];
+  /** 方言相关的表达式（JSON 提取、本地日这类）用片段表达；给了它就不用 `sql` / `params`。 */
+  readonly fragment?: Fragment;
+  readonly __value?: T;
+}
+/** 列、值或表达式。 */
+type Operand = ColumnRef | Value | ExprOperand;
+/** 条件里可以直接写原始值（自动包成绑定参数）；`null` 走 IS NULL / IS NOT NULL。 */
+type OperandInput = Operand | string | number | boolean | bigint | null;
+/** 一个条件（可再组合的片段）。 */
+type Condition = Fragment;
+export declare function column<T = unknown>(name: string, table?: string): ColumnRef<T>;
+export declare function value(input: unknown): Value;
+/** 列名引用成 SQL：`"表"."列"` 或 `"列"`。 */
+declare function columnSql(ref: ColumnRef): string;
+/** 把操作数渲染成片段（投影 / 赋值里复用）。 */
+export declare function operandSql(ref: Operand): Fragment;
+/** 表达式操作数的便捷构造（如 `expr('"f_count" + 1')`）。 */
+export declare function expr(sql: string, params?: readonly unknown[]): ExprOperand;
+export declare const eq: (left: OperandInput, right: OperandInput) => Condition;
+export declare const ne: (left: OperandInput, right: OperandInput) => Condition;
+export declare const gt: (left: OperandInput, right: OperandInput) => Condition;
+export declare const gte: (left: OperandInput, right: OperandInput) => Condition;
+export declare const lt: (left: OperandInput, right: OperandInput) => Condition;
+export declare const lte: (left: OperandInput, right: OperandInput) => Condition;
+export declare const like: (left: OperandInput, right: OperandInput) => Condition;
+/** `BETWEEN ? AND ?`。 */
+export declare const between: (ref: OperandInput, low: OperandInput, high: OperandInput) => Condition;
+/** `列 IN (子查询)`。 */
+export declare function inSubquery(ref: Operand, subquery: Fragment): Condition;
+/** `列 NOT IN (子查询)`。 */
+export declare function notInSubquery(ref: OperandInput, subquery: Fragment): Condition;
+/** 恒真条件（占位用，避免业务侧写 `raw("1 = 1")`）。 */
+declare function always(): Condition;
+/** 恒假条件。 */
+declare function never(): Condition;
+/** `COALESCE(a, b, …)`：值走绑定参数，列/表达式原样渲染。 */
+declare function coalesce(...inputs: OperandInput[]): ExprOperand;
+/** `lower(x)`（表达式位置用）。 */
+declare function lower(input: OperandInput): ExprOperand;
+/** `x IS NOT NULL` 的表达式形式（投影 / 分组位置用）。 */
+declare function notNull(input: OperandInput): ExprOperand;
+/** `a IS DISTINCT FROM b`（NULL 也参与比较，不会退化成 `IS NULL`）。 */
+declare function isDistinctFrom(left: OperandInput, right: OperandInput): Condition;
+/** `EXISTS (子查询)`。 */
+export declare function exists(subquery: Fragment): Condition;
+/** `NOT (...)`。 */
+export declare const not: (condition: Condition) => Condition;
+/**
+ * 显式逃生口：少数表达不了的片段（窗口函数、方言专属函数）才用它。
+ * 占位符仍只由 `?` + 参数生成，避免把值拼进文本。
+ */
+export declare function raw(sql: string, params?: readonly unknown[]): Condition;
+/** `a + b`（列自增、upsert 累加）。 */
+export declare function add(left: OperandInput, right: OperandInput): ExprOperand<number>;
+/** upsert 冲突时的「新值」引用：`excluded."列"`（只用于 `upsertExpr` 的赋值）。 */
+export declare function excluded(name: string): ExprOperand;
+/** 条件渲染成整数列的值（`CASE WHEN cond THEN 1 ELSE 0 END`，两方言同一份）。 */
+export declare function toInt(condition: Condition): ExprOperand<number>;
+/** 条件计数：`SUM(CASE WHEN cond THEN 1 ELSE 0 END)`（投影 / 分组位置用）。 */
+export declare function countIf(condition: Condition): ExprOperand<number>;
+/** 只增不减：`max(a, b)` 的方言无关写法（NULL 视作 0，两方言同一份 CASE）。 */
+export declare function maxOf(first: OperandInput, ...rest: readonly OperandInput[]): ExprOperand<number>;
+/** JSON 文本提取：SQLite `json_extract(列, 路径)`、PostgreSQL `列::json #>> '{a,b}'`。 */
+export declare function jsonText(input: OperandInput, path: string): ExprOperand<string | null>;
+/** JSON 整数提取：文本提取后再转整数（SQLite 的 `json_extract` 本身就按类型给值）。 */
+export declare function jsonInt(input: OperandInput, path: string): ExprOperand<number | null>;
+/**
+ * 毫秒时间戳 → 本地日（`YYYY-MM-DD`）。
+ *
+ * 按**数据库所在机器的本地时区**算（SQLite `localtime` / PG 会话时区），两方言口径一致。
+ */
+export declare function localDay(input: OperandInput): ExprOperand<string>;
+export declare const isNull: (ref: Operand) => Condition;
+export declare const isNotNull: (ref: Operand) => Condition;
+/** `IN (?, ?, …)`；空列表渲染成恒假（`1 = 0`），避免拼出 `IN ()`。 */
+export declare function inList(left: OperandInput, values: readonly unknown[]): Condition;
+/** `NOT IN (...)`；空列表恒真。 */
+export declare function notInList(left: OperandInput, values: readonly unknown[]): Condition;
+export declare const and: (...conditions: readonly Condition[]) => Condition;
+export declare const or: (...conditions: readonly Condition[]) => Condition;
+/** 一个按表名解析的 catalog（装配层注册一次，业务按名字取表）。 */
+interface CatalogIndex {
+  get(name: string): TableDef | undefined;
+  has(name: string): boolean;
+  names(): string[];
+}
+/** 把表定义列表编成索引（重复表名 fail loud）。 */
+export declare function indexCatalog(catalog: Catalog): CatalogIndex;
+/**
+ * 注入给业务的库句柄：只回答「哪张表」与「怎么读/写/开事务」；不暴露连接与 SQL。
+ * `dialect` 只给迁移 / 日志这类基础层用，业务查询不需要它。
+ * 连接生命周期由创建它的一方（装配层）管理，业务拿到的是这个接口。
+ */
+interface Database<C extends Catalog = Catalog> {
+  /** 迁移 / 日志用；业务不需要读它。 */
+  readonly dialect: Dialect;
+  /** 装配层注册的 catalog（按表名解析；没注册时只能传定义）。 */
+  readonly catalog: CatalogIndex;
+  /** 按表名取（catalog 里有定义时保留强类型）。 */
+  table<K extends C[number]["name"] & string>(name: K): TableHandle<Extract<C[number], {
+    name: K;
+  }>>;
+  /** 直接传定义（catalog 未注册时）。 */
+  table<T extends TableDef>(definition: T): TableHandle<T>;
+  /** 主读路径：按行流式迭代（与 Golang 的 `iter.Seq2` 对齐，不一次性物化大结果）。 */
+  iterate<T>(query: Fragment): AsyncIterable<T>;
+  /** 便捷读：把迭代器收成数组（报表 / 迁移读取用）。 */
+  read<T>(query: Fragment): Promise<T[]>;
+  /** 写入并拿回行（`RETURNING`；没有 RETURNING 的语句返回空数组）。 */
+  write<T>(query: Fragment): Promise<T[]>;
+  run(query: Fragment): Promise<void>;
+  transaction<T>(fn: (database: Database<C>) => Promise<T>): Promise<T>;
+  /** 现有的表与视图名（迁移探测旧表、拒绝别人的库都要它）。 */
+  objectNames(): Promise<string[]>;
+  /** 回收空间与统计（SQLite `VACUUM` / PostgreSQL `VACUUM ANALYZE`）；不得在事务内调用。 */
+  vacuum(): Promise<void>;
+  /** 读 SQLite 的 `PRAGMA`（其它方言直接报不支持）。 */
+  sqlitePragma(name: SqlitePragmaName): Promise<string | number | undefined>;
+  /** 写 SQLite 的 `PRAGMA`（值只允许安全字面量，见 `assertPragmaValue`）。 */
+  setSqlitePragma(name: SqlitePragmaName, value: string | number): Promise<void>;
+  close(): Promise<void>;
+}
+/** 业务侧用得到的 SQLite PRAGMA（库身份与日志模式；其余不开口子）。 */
+type SqlitePragmaName = "user_version" | "application_id" | "journal_mode";
+type OpenConfig = {
+  dialect: "sqlite";
+  path: string;
+  journalMode?: "wal" | "delete" | "truncate" | "persist";
+  busyTimeout?: number;
+  /** SQLite 页缓存（KB，负数表示 KB 数；不传用 SQLite 默认）。 */
+  cacheSizeKb?: number;
+  /** mmap 窗口（字节；0 关闭）。 */
+  mmapSize?: number;
+  /** 是否在打开时立即设置 `journal_mode`（默认 true；需要先校验库再切的调用方传 false）。 */
+  applyJournalMode?: boolean;
+} | {
+  dialect: "postgres";
+  connectionString: string;
+  schema?: string;
+  /** 事务隔离级别（session-rdb 的写路径要 `serializable`）。 */
+  isolationLevel?: "read committed" | "repeatable read" | "serializable";
+};
+/** 一条已执行语句的观测（日志 / 慢查询 / 耗时统计）。 */
+interface QueryEvent {
+  readonly dialect: DialectName;
+  readonly sql: string;
+  readonly params: readonly unknown[];
+  readonly durationMs: number;
+  readonly error?: unknown;
+}
+/** 打开时可带 catalog 与查询观测钩子。 */
+type OpenConfigWithCatalog<C extends Catalog = Catalog> = OpenConfig & {
+  catalog?: C;
+  onQuery?: (event: QueryEvent) => void;
+};
+/**
+ * 一列对外的 TS 值类型：文本 → string、布尔 → boolean、64 位整数（`bigint`）→ JS `bigint`（精确，
+ * 对应 Go 的 int64 / uint64；不能用 number，超过 `2^53` 会丢精度）、其余 → number。
+ * 非 NOT NULL 允许 null。
+ */
+type ColumnValue<C extends ColumnDef> = C["type"] extends "text" ? string : C["type"] extends "boolean" ? boolean : C["type"] extends "bigint" ? bigint : number;
+type RowOf<T extends TableDef> = { [K in keyof T["columns"]]: T["columns"][K] extends {
+  notNull: true;
+} ? ColumnValue<T["columns"][K]> : T["columns"][K] extends {
+  type: "serial";
+} ? ColumnValue<T["columns"][K]> : ColumnValue<T["columns"][K]> | null; };
+/** 写入时 `bigint` 列也接受 number（安全整数范围内两者等价）。 */
+type Writable<T> = T extends bigint ? bigint | number : T;
+/**
+ * 写入行：列可选（有默认值 / 自增列不必给）。值允许 number 写进 `bigint` 列，业务不必到处写 `n` 后缀；
+ * 读回来仍然是 `bigint`（不丢精度）。
+ */
+type InsertRow<Row> = Partial<{ [K in keyof Row]: Writable<Row[K]>; }>;
+/** 更新时的值：普通值（绑定参数）或表达式（`expr('"f_revision" + 1')` 等）。 */
+type UpdatePatch<Row> = { [K in keyof Row]?: Writable<Row[K]> | Operand; };
+/** 列名（字符串键）。 */
+type ColumnName<Row> = Extract<keyof Row, string>;
+/**
+ * 聚合表达式（`count()` / `sum(col)`）：投影与条件里都能用。
+ *
+ * 值是 64 位整数：PostgreSQL 给 `bigint`、SQLite 给 number，业务要 number 时显式 `Number(x)`。
+ */
+type Aggregate<T = number | bigint> = ExprOperand<T>;
+/** 投影：别名 → 列引用或聚合。结果类型由它推导。 */
+type Projection = Record<string, ColumnRef<any> | Aggregate<any>>;
+/** 投影的强类型结果。 */
+type Projected<P extends Projection> = { [K in keyof P]: P[K] extends ColumnRef<infer T> ? T : P[K] extends Aggregate<infer T> ? T : never; };
+/** COUNT(*)，投影里写 `{ n: count() }`。 */
+export declare function count(): Aggregate<number | bigint>;
+/**
+ * SUM(列)；多表查询时传表名避免歧义。
+ *
+ * PostgreSQL 的 `SUM(bigint)` 返回 `numeric`（驱动给字符串），SQLite 返回整数——统一 cast 回 int8，
+ * 声明的 `number | bigint` 才成立。列类型只有 integer / bigint，所以这个 cast 不丢小数。
+ */
+export declare function sum(name: string, table?: string): Aggregate<number | bigint>;
+/** 一个查询：实现 `AsyncIterable`，`for await` 直接消费（对应 Golang 的 `iter.Seq2`）。 */
+interface SelectQuery<T> extends AsyncIterable<T> {
+  where(condition: Condition): this;
+  /** `cross` 不需要 ON；`alias` 给被 join 的表起别名（投影里用 `column(名字, 别名)`）。 */
+  join(table: TableDef, on?: Condition, kind?: "inner" | "left" | "right" | "full" | "cross", alias?: string): this;
+  /** `WITH "name" AS (<query>)`，多条按顺序拼。 */
+  with(name: string, query: Fragment, options?: {
+    recursive?: boolean;
+    columns?: readonly string[];
+  }): this;
+  /** 分组：列名（主表）、带表名的列引用或表达式。 */
+  groupBy(...columns: GroupByItem[]): this;
+  having(condition: Condition): this;
+  distinct(): this;
+  orderBy(column: string | ColumnRef | ExprOperand, direction?: "asc" | "desc"): this;
+  limit(count: number): this;
+  offset(count: number): this;
+  /** 行锁（PostgreSQL 生效，SQLite 渲染时丢弃）。 */
+  forUpdate(options?: {
+    of?: readonly string[];
+    noWait?: boolean;
+    skipLocked?: boolean;
+  }): this;
+  toFragment(): Fragment;
+}
+/** `groupBy` 的入参：列名、带表名的列引用或表达式。 */
+type GroupByItem = string | ColumnRef | ExprOperand;
+/** 列访问器：`t.f_domain` 就是这一列的引用（带值类型）。 */
+type ColumnAccessors<Row> = { readonly [K in ColumnName<Row>]: ColumnRef<Row[K]>; };
+/** 一张表的业务面：投影查询 + 写入，调用方不接触方言与 SQL。 */
+type TableHandle<T extends TableDef> = TableHandleBase<T> & ColumnAccessors<RowOf<T>>;
+interface TableHandleBase<T extends TableDef> {
+  readonly name: string;
+  readonly definition: T;
+  /** 拿一列（带值类型的引用），投影 / 条件里用。 */
+  column<K extends ColumnName<RowOf<T>>>(name: K): ColumnRef<RowOf<T>[K]>;
+  /** 投影省略时取全部列（结果按列名原样）。 */
+  select<P extends Projection = Record<string, ColumnRef>>(projection?: P): SelectQuery<Projected<P>>;
+  /** 插入；传 `returning` 时拿回这些列（`RETURNING`，两方言都支持）。 */
+  insert(row: InsertRow<RowOf<T>>, returning?: readonly ColumnName<RowOf<T>>[]): Promise<RowOf<T>[]>;
+  insertIgnore(row: InsertRow<RowOf<T>>, conflict: readonly ColumnName<RowOf<T>>[]): Promise<void>;
+  /** `INSERT … SELECT`：把一条查询的结果按列顺序插进来（Go 的 `InsertFrom`）。 */
+  insertFromSelect(columns: readonly ColumnName<RowOf<T>>[], source: Fragment, options?: {
+    conflict?: readonly ColumnName<RowOf<T>>[];
+    update?: readonly ColumnName<RowOf<T>>[];
+  }): Promise<void>;
+  /** 批量插入；传 `conflict` / `update` 时是批量 upsert（`ON CONFLICT … DO UPDATE`）。 */
+  insertMany(rows: readonly InsertRow<RowOf<T>>[], options?: {
+    conflict?: readonly ColumnName<RowOf<T>>[];
+    update?: readonly ColumnName<RowOf<T>>[];
+  }): Promise<void>;
+  upsert(row: InsertRow<RowOf<T>>, conflict: readonly ColumnName<RowOf<T>>[], update?: readonly ColumnName<RowOf<T>>[]): Promise<void>;
+  update(patch: UpdatePatch<RowOf<T>>, condition?: Condition, returning?: readonly ColumnName<RowOf<T>>[]): Promise<RowOf<T>[]>;
+  /** `ON CONFLICT ... DO UPDATE SET 列 = 表达式`（如自增计数）。 */
+  upsertExpr(row: InsertRow<RowOf<T>>, conflict: readonly ColumnName<RowOf<T>>[], assignments: Record<string, Operand>): Promise<void>;
+  /** 删除；传 `returning` 时拿回被删行的这些列（`RETURNING`）。 */
+  delete(condition?: Condition, returning?: readonly ColumnName<RowOf<T>>[]): Promise<RowOf<T>[]>;
+}
+export declare function createTableHandle<T extends TableDef>(database: Database, definition: T): TableHandle<T>;
+/** 列类型：只保留跨方言能一一映射的那几种。 */
+type ColumnTypeName = "serial" | "integer" | "bigint" | "text" | "boolean";
+/** 外键的删除动作（与 SQL 的 ON DELETE 同名）。 */
+type DeleteAction = "cascade" | "set null" | "restrict" | "no action";
+/** 一列的定义。 */
+interface ColumnDef {
+  type: ColumnTypeName;
+  notNull?: boolean;
+  /** 单列主键；复合主键写在表级的 `primaryKey` 上。 */
+  primaryKey?: boolean;
+  default?: string | number;
+  unique?: boolean;
+  references?: {
+    table: string;
+    column: string;
+    onDelete?: DeleteAction;
+  };
+}
+/** 表级约束与索引。 */
+interface CheckDef {
+  expression: string;
+}
+interface UniqueDef {
+  columns: string[];
+}
+interface IndexDef {
+  columns: string[];
+}
+/** 一张表的完整定义。 */
+interface TableDef {
+  name: string;
+  columns: Record<string, ColumnDef>;
+  /** 复合主键（按顺序）；单列主键用列上的 `primaryKey`。 */
+  primaryKey?: readonly string[];
+  checks?: Record<string, CheckDef>;
+  uniques?: Record<string, UniqueDef>;
+  indexes?: Record<string, IndexDef>;
+}
+/** 一组表定义（一个库的结构）。 */
+type Catalog = readonly TableDef[];
+/** `defineTable` 的返回值：表定义 + 操作钩子（`users.table(database)` 直接拿句柄）。 */
+type Table<T extends TableDef> = T & {
+  table(database: Database): TableHandle<T>;
+};
+/** 声明一张表（形状原样保留，另挂一个取句柄的钩子）。 */
+export declare function defineTable<const T extends TableDef>(def: T): Table<T>;
+/** 声明一组表。 */
+export declare function defineCatalog<const T extends readonly TableDef[]>(tables: T): T;
+/** 打开一个库；这是连接创建的唯一入口（实际 connect 在 `sqlite.ts` / `postgres.ts`，业务只拿 `Database`）。 */
+export declare function openDatabase<const C extends Catalog = Catalog>(config: OpenConfigWithCatalog<C>): Promise<Database<C>>;
+/** 把「已有执行面」包成 rdbkit 的 `Database`（宿主自己管连接与事务时用）。 */
+export declare function wrapDatabase(dialectName: DialectName, ports: {
+  iterate(text: string, params: readonly unknown[]): AsyncIterable<unknown>;
+  run(text: string, params: readonly unknown[]): Promise<void>;
+  /** 宿主自己管事务时提供：把当前事务的执行面做成 scoped `Database`（对应 Go 的 `Tx(ctx, fn)`）。 */
+  transaction?: <T>(fn: (scoped: Database) => Promise<T>) => Promise<T>;
+  close?(): Promise<void>;
+}): Database;
+/** 结构迁移读取现状用的最小查询面。 */
+export declare function shapeReader(database: Database): {
+  query<T>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+};
+/** 一条结构变更（按顺序执行）。 */
+interface SchemaChange {
+  readonly table: string;
+  readonly kind: "create-table" | "add-column" | "create-index" | "drop-column";
+  readonly statement: string;
+}
+interface EnsureSchemaOptions {
+  /** PostgreSQL 的 schema（默认 `public`）；SQLite 忽略。 */
+  schema?: string;
+  /** 允许删掉定义里已经不存在、且确实多出来的列（默认关闭：升级不丢数据）。 */
+  allowDestructive?: boolean;
+  /** 需要看到实际执行的语句时（排查 / 测试）。 */
+  onStatement?: (statement: string) => void;
+}
+/**
+ * 结构差异（纯函数）：缺表建表、缺列补列、缺索引补索引。
+ *
+ * 默认只做「增」（缺表建表、缺列补列、缺索引补索引），不改类型、不删索引；删多出来的列只由
+ * `allowDestructive: true` 显式打开（旧库升级默认不丢数据）。
+ * @param dialect - 目标方言。
+ * @param catalog - 表定义（唯一事实来源）。
+ * @param shapes - 现有结构（表名 → 列 / 索引；不存在则 undefined）。
+ * @param options - schema 名。
+ * @returns 需要执行的变更，按依赖顺序（表 → 列 → 索引）。
+ */
+export declare function planSchema(dialect: Dialect, catalog: Catalog, shapes: ReadonlyMap<string, TableShape | undefined>, options?: {
+  schema?: string;
+  allowDestructive?: boolean;
+}): SchemaChange[];
+/** 让库结构与表定义对齐，并返回实际执行的语句。 */
+export declare function ensureSchema(database: Database, catalog: Catalog, options?: EnsureSchemaOptions): Promise<string[]>;
+/** 一条 CTE：`"name" AS (<query>)`；`recursive` 时由 `withCtes` 渲染成 `WITH RECURSIVE` 前缀。 */
+interface Cte {
+  readonly name: string;
+  readonly query: Fragment;
+  readonly recursive?: boolean;
+  readonly columns?: readonly string[];
+}
+/** 把一条 CTE 拼在 `WITH` 之后（调用方负责逗号）。 */
+export declare function cteSql(cte: Cte): Fragment;
+/** 组装 `WITH [RECURSIVE] cte, … SELECT …`。 */
+export declare function withCtes(ctes: readonly Cte[], query: Fragment): Fragment;
+/** `UNION` / `UNION ALL`。 */
+export declare function union(left: Fragment, right: Fragment, options?: {
+  all?: boolean;
+}): Fragment;
+/** `INTERSECT`。 */
+export declare function intersect(left: Fragment, right: Fragment): Fragment;
+/** `EXCEPT`。 */
+export declare function except(left: Fragment, right: Fragment): Fragment;
+/** 行锁：只有 PostgreSQL 认，SQLite 渲染时整段丢掉（分隔符也不能漏出来）。 */
+export declare function forUpdate(options?: {
+  of?: readonly string[];
+  noWait?: boolean;
+  skipLocked?: boolean;
+}): Fragment;
+/** 表别名（join / CTE 里用）。 */
+export declare function aliasedTable(table: TableDef, alias: string): string;
+/** 数据库错误的可判定类别（调用方据此决定重试 / 上报 / 走业务分支）。 */
+type DbErrorKind = "unique" | "foreign-key" | "not-null" | "check" | "timeout" | "connection" | "unknown";
+/** 统一的数据库错误：`kind` 是方言无关的判定，原始错误在 `cause`。 */
+export declare class DbError extends Error {
+  readonly kind: DbErrorKind;
+  constructor(kind: DbErrorKind, message: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * 把驱动错误翻译成 {@link DbErrorKind}：SQLite 用错误文本前缀，PostgreSQL 用 SQLSTATE。
+ * @param error - 驱动抛出的错误。
+ * @param dialect - 产生它的方言。
+ * @returns 已分类的错误（原错误在 `cause`）。
+ */
+export declare function classifyError(error: unknown, dialect: DialectName): DbError;
+/** 内置迁移账本：一条已执行的数据迁移一行（`f_id` 唯一）。 */
+export declare const schemaMigrations: Table<{
+  readonly name: "t_schema_migrations";
+  readonly columns: {
+    readonly f_id: {
+      readonly type: "text";
+      readonly primaryKey: true;
+      readonly notNull: true;
+    };
+    readonly f_applied_at: {
+      readonly type: "bigint";
+      readonly notNull: true;
+    };
+  };
+}>;
+/** 一条数据迁移：`id` 唯一且按字典序执行；`up` 在事务里跑，抛错则整条不记。 */
+interface Migration {
+  readonly id: string;
+  /**
+   * 返回 `false` 表示这次无需执行（例如旧表还不存在），**不记账**——下次打开还会再试。
+   * 返回其它值（含 `undefined`）表示已执行，记账。
+   */
+  readonly up: (database: Database) => Promise<boolean | void>;
+}
+/** 迁移注册表：业务把自己的迁移登记进来，打开库时一起执行。 */
+export declare class MigrationRegistry {
+  #private;
+  register(migration: Migration): this;
+  list(): readonly Migration[];
+}
+/** 打开库时做的事：结构（catalog diff）+ 数据迁移（注册表）。 */
+interface RunMigrationsOptions {
+  /** 业务表定义（`ensureSchema` 用）。 */
+  catalog?: Catalog;
+  migrations: readonly Migration[] | MigrationRegistry;
+}
+/**
+ * 先按 catalog 对齐结构（建表 / 补列 / 补索引），再执行未应用的数据迁移。
+ *
+ * 账本是 rdbkit 内置的 `t_schema_migrations`：每条迁移在**同一个事务**里执行并记账，
+ * 失败即回滚，重跑时只跑没记过的。返回本次实际执行了哪些 `id`。
+ */
+export declare function runMigrations(database: Database, options: RunMigrationsOptions): Promise<readonly string[]>;
+export { type Aggregate, type Catalog, type CatalogIndex, type CheckDef, type ColumnDef, type ColumnName, type ColumnRef, type ColumnTypeName, type ColumnValue, type Condition, type Cte, type Database, type DbErrorKind, type DeleteAction, type Dialect, type DialectName, expr_d_exports as E, type EnsureSchemaOptions, type ExprOperand, type Fragment, type IndexDef, type InsertRow, type Migration, type OpenConfig, type Operand, type OperandInput, type Projected, type Projection, type QueryEvent, type RowOf, type RunMigrationsOptions, type SchemaChange, type SelectQuery, type SqlitePragmaName, type Table, type TableDef, type TableHandle, type TableShape, type UniqueDef, columnSql as columnRefSql, columnSql$1 as columnSql };