# @kequtech/tenon-orm 中文文档

规范地址：https://npmcn.com/package/%40kequtech/tenon-orm/

版本：0\.4\.7
npm 元数据更新时间：2026-11-01T14:01:26.796Z
中文译文更新时间：2026-11-01T15:30:05.350Z
软件包许可：ISC

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40kequtech/tenon-orm
原文对照：https://npmcn.com/package/%40kequtech/tenon-orm/?lang=original
项目主页：https://github.com/kequtech/tenon-orm#readme
源码仓库：https://github.com/kequtech/tenon-orm

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：366 kB，115 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：2 个
- 首次发布：2026-10-23T23:43:04.833Z
- 最新版本发布：2026-11-01T14:01:26.626Z
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

一个PostgreSQL ORM设计用于编码代理，具有显式SQL，类型化查询和迁移

## 安装

```sh
npm install @kequtech/tenon-orm
```

也可以使用：`pnpm add @kequtech/tenon-orm`、`yarn add @kequtech/tenon-orm`、`bun add @kequtech/tenon-orm`

## README

# 榫ORM

一个PostgreSQL ORM设计的编码代理。为Node.js和TypeScript构建。

Tenon以编码代理可以读、写和检查的形式保持数据库工作：显式SQL，普通 TypeScript函数和SQL迁移。查询带有它们的结果类型和执行选项 这样，代理和审查其工作的人就可以在一个地方看到操作的效果。

```sh
npm install @kequtech/tenon-orm
```

要求Node.js 24+, PostgreSQL 16+， ESM。TypeScript应用需要TypeScript 6+和Node.js 打字。PostgreSQL驱动程序， [pgclear](https://github.com/kequtech/pgclear)，包括在内。

## SQL查询

这个例子假设 `public.users` 带整数的表 `id` 和文本 `email` 列和a `main` 导出到 [共享配置](https://npmcn.com/package/%40kequtech/tenon-orm/docs/configuration.md)：

```ts
import { createTenon, sql } from '@kequtech/tenon-orm';
import { main } from './tenon.config.ts';

const db = createTenon(main);

try {
  const email = 'reader@example.test';
  const user = await db.query(
    sql<{ id: number; email: string }>`
      SELECT id, email FROM public.users WHERE email = ${email}
    `,
    { returns: 'oneOrNone' },
  );
  // user: { id: number; email: string } | undefined
} finally {
  await db.close();
}
```

`${email}` 变成了 `$1` 在SQL中，分别传递值。 `sql<Row>` 描述了一个 返回的行。 `returns` 选择Tenon如何归还这些排；

| `returns` | 你收到 | 需要行 |
| --- | --- | --- |
| `many` | `readonly Row[]` | 任何数量 |
| `oneOrNone` | `Row | undefined` | 0或1 |
| `one` | `Row` | 一个 |
| `native` (默认) | 驱动结果 `rows`， `rowCount`, `fields` | 任何数量 |

行数不匹配会引发。模式没有添加 `LIMIT` 或者更改SQL。在服务器中，重用一个 数据库实例，并在关机期间关闭它。通过应用程序提供环境变量； 榫不加载 `.env` 文件。

## 为编码代理设计

Tenon的API为编码代理提供了具体的代码和明确的契约：

-   **可读的SQL。** 所选列、连接、筛选器和冲突处理在查询中可见。 代理可以直接检查操作并使用PostgreSQL现有的词汇表。
-   **普通的打印稿。** 可重用查询是函数。代理可以跟随导入，更改a 函数，并将相同的查询代码传递给数据库或事务客户端。
-   **显式写入限制。** 查询可以只需要一个受影响的行，也可以设置一个最大值。榫 如果违反了该界限，则回滚操作。
-   **可操作的检查。** 生成的表类型描述存储契约； `tenon check` 报告 可恢复的SQL和声明的类型之间的矛盾。新鲜度检查捕获不新鲜的生成 声明和数据库测试验证结果和效果。

指南和变更日志随包一起发布，为已安装的程序提供代理文档 的版本。对于现有项目中的工作，从 [代理指南](https://npmcn.com/package/%40kequtech/tenon-orm/docs/agent-guide.md).

## Tenon是如何组合在一起的

-   **SQL定义操作。** 直接使用PostgreSQL的join， aggregate， constraints和upserts。 对普通函数重用查询；当SQL的某些部分需要变化时，使用片段。
-   **TypeScript描述这些值。** 声明查询投影。 `sql<Row>`． 选择生成 表的读/插入/更新类型 `tenon generate`． 捕获一个版本控制 [模式指纹](https://npmcn.com/package/%40kequtech/tenon-orm/docs/schema-inspection.md) 与 `tenon schema` 对于应用程序拥有的守卫。
-   **事务定义一起提交的内容。** 使用 `db.transaction(async (tx) => { ... })` 和运行 每个参与查询 `tx`.
-   **写保护检查受影响的行。** `{ affectedRows: { exact: 1 } }` 回滚写操作，除非 只有一行受到了影响。 `{ max: 1 }` 允许0或1。
-   **迁移会改变模式。** Tenon的可选运行程序应用编号的SQL文件。你可以继续 现有的模式和迁移运行程序。

对于对象输入， `sql.insertValues(input)` 和 `sql.assignments(patch)` 构建列/值 声明的部分内容。表、条件、表达式和冲突行为保留在SQL中。 没有模型实例或隐式关系加载。

查询类型是声明。Tenon不验证返回的数据 `Row` 在执行期间。 可选 `tenon check` 命令将可恢复的源查询与TypeScript类型和 PostgreSQL的元数据。保持数据库测试的实际结果和写入效果。

一些PostgreSQL值需要注意：bigint列和 `count(*)` 读取精确字符串，数字和 时间值也默认为字符串，JSON/数组输入使用显式编码助手。命令 `rowCount` 是一个数字或null。看到 [值的映射](https://npmcn.com/package/%40kequtech/tenon-orm/docs/schema-types.md#value-mappings) 之前 选择应用程序类型。

## 与CLI共享配置

运行 `tenon init` 创建 `tenon.config.ts`． 将连接设置和编解码器放在其 `main` 出口, 然后重用该对象 `createTenon(main)`． 初始化保持惰性，因此构建只导入 数据库实例不需要凭据。

CLI对迁移使用相同的配置， `tenon generate`、新鲜度检查； `tenon check`, `tenon describe query.sql`． 对于多个数据库，添加命名导出并选择一个带有 `--database`. 看到 [共享配置](https://npmcn.com/package/%40kequtech/tenon-orm/docs/configuration.md) 以获得完整的设置。

## 文档

从……开始 [开始](https://npmcn.com/package/%40kequtech/tenon-orm/docs/human-guide.md) 获取完整的表到查询示例。然后选择 任务指南：

| 指南 | 它涵盖了什么 |
| --- | --- |
| [共享配置](https://npmcn.com/package/%40kequtech/tenon-orm/docs/configuration.md) | 运行时/CLI连接设置、编解码器、命令默认值和覆盖 |
| [编写查询](https://npmcn.com/package/%40kequtech/tenon-orm/docs/sql.md) | 参数、可重用函数、连接、聚合、分页和片段 |
| [写数据](https://npmcn.com/package/%40kequtech/tenon-orm/docs/mutations.md) | insert、patch、default、upserts、JSON、arrays和batch |
| [模式类型和值](https://npmcn.com/package/%40kequtech/tenon-orm/docs/schema-types.md) | 生成、读/写类型、编解码器和域验证 |
| [迁移](https://npmcn.com/package/%40kequtech/tenon-orm/docs/migrations.md) | 创建、应用、检查和回滚SQL迁移 |
| [连接和驱动访问](https://npmcn.com/package/%40kequtech/tenon-orm/docs/connections.md) | 池配置、关机、自定义编解码器和本机特性 |
| [检查查询类型](https://npmcn.com/package/%40kequtech/tenon-orm/docs/query-checking.md) | 源感知检查及其支持的SQL组合 |
| [检查和测试查询](https://npmcn.com/package/%40kequtech/tenon-orm/docs/query-inspection.md) | PostgreSQL元数据和真实行为的测试 |
| [采用榫](https://npmcn.com/package/%40kequtech/tenon-orm/docs/adoption-guide.md) | 替换ORM并转移迁移所有权 |
| [代理指南](https://npmcn.com/package/%40kequtech/tenon-orm/docs/agent-guide.md) | 现有项目的简短实现工作流 |
| [API和CLI参考](https://npmcn.com/package/%40kequtech/tenon-orm/docs/reference.md) | 签名、选项、错误、命令和故障排除 |

README、指南和 [更新日志](https://npmcn.com/package/%40kequtech/tenon-orm/CHANGELOG.md) 随NPM包一起发布。阅读文档 用于升级时安装的版本。图书馆维护费用包括在 [CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md).

[ISC许可](https://npmcn.com/package/%40kequtech/tenon-orm/LICENSE)． 维护的 [Kequtech](https://github.com/kequtech).

## 常见问题

### @kequtech/tenon-orm 是什么？

一个PostgreSQL ORM设计用于编码代理，具有显式SQL，类型化查询和迁移

### 如何安装 @kequtech/tenon-orm？

在项目目录运行 npm install @kequtech/tenon-orm，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 tenon，可以用 npx tenon 直接运行。

### @kequtech/tenon-orm 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @kequtech/tenon-orm 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @kequtech/tenon-orm 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @kequtech/tenon-orm 可以商用吗？

@kequtech/tenon-orm 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @kequtech/tenon-orm 还在维护吗？

最新版本 0\.4\.7 发布于 2026/11/01（1 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/10/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。