# @aws/aurora-dsql-drizzle 中文文档

规范地址：https://npmcn.com/package/%40aws/aurora-dsql-drizzle/

版本：0\.2\.0
npm 元数据更新时间：2026-09-25T18:59:17.062Z
中文译文更新时间：2026-11-07T14:26:11.958Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws/aurora-dsql-drizzle
原文对照：https://npmcn.com/package/%40aws/aurora-dsql-drizzle/?lang=original
项目主页：https://github.com/awslabs/aurora-dsql-orms#readme
源码仓库：https://github.com/awslabs/aurora-dsql-orms

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

- 包体积（解压后）：104 kB，38 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：pg \>=8，drizzle-orm ^0\.45
- 首次发布：2026-08-26T01:38:51.279Z
- 最新版本发布：2026-09-25T18:59:16.783Z
- 近 30 天下载量：19386（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Amazon Aurora DSQL 的 Drizzle ORM 适配器

## 安装

```sh
npm install @aws/aurora-dsql-drizzle
```

也可以使用：`pnpm add @aws/aurora-dsql-drizzle`、`yarn add @aws/aurora-dsql-drizzle`、`bun add @aws/aurora-dsql-drizzle`

## README

# 用于 Drizzle ORM 的 Aurora DSQL 适配器

[![GitHub](https://img.shields.io/badge/github-awslabs/aurora--dsql--orms-blue?logo=github)](https://github.com/awslabs/aurora-dsql-orms) [![npm version](https://img.shields.io/npm/v/@aws/aurora-dsql-drizzle.svg)](https://www.npmjs.com/package/@aws/aurora-dsql-drizzle) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Discord chat](https://img.shields.io/discord/1435027294837276802.svg?logo=discord)](https://discord.com/invite/nEF6ksFWru)

[滴入外科手术](https://orm.drizzle.team/) 支持 [亚马逊·奥罗拉 DSQL](https://aws.amazon.com/rds/aurora/dsql/)。 。 。 .

它继续前进 `drizzle-orm/node-postgres`页:1 [Aurora DSQL 连接器](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) 是一个 `pg.Pool` 有IAM标志认证,所以没有定制方言——只是一丝不苟 `drizzle()` 工厂,一个选入的OCC重试帮助器,一个DSQL-有意识的植入器,和一个迁移CLI.

## 所需资源

-   滴入外科手术 `^0.45` 财务报告和审定财务报表 `pg` `>=8` (同类依赖关系)
-   节点.js `>=20`
-   Aurora DSQL 集群和 AWS 证书 `dsql:DbConnect` 对于您所连接的数据库角色

## 安装

```bash
npm install @aws/aurora-dsql-drizzle drizzle-orm pg
npm install -D drizzle-kit
```

IAM认证和TLS由连接器处理.

## 连接

```ts
import { drizzle } from "@aws/aurora-dsql-drizzle";
import * as schema from "./schema";

const db = drizzle({
  connection: {
    host: process.env.CLUSTER_ENDPOINT!, // <id>.dsql.<region>.on.aws
    region: "us-east-1", // optional; inferred from the host otherwise
    user: "myuser", // a database role scoped to what your app needs
    options: "-c search_path=myschema",
  },
  schema,
});

const owners = await db.select().from(schema.owner);
```

`user` 需要——见 [使用数据库角色和IAM认证](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html) 用于创建只授予您应用程序需要的特权的角色。 不存在默认,所以一个连接永远不会降落在 `admin` 以无所取.

已经有泳池了? 直接通过: `drizzle({ client: pool, schema })`时 `pool` 是一个 `AuroraDSQLPool` (或任何 `pg.Pool`) (中文(简体) ). `db.$client` 暴露基本池;调用 `await db.$client.end()` 关闭它.

## 与OCC 重试的交易

DSQL 使用乐观的货币控制: ComMIT 交易失败与 `OC000` 编号 : `OC001` (标准数据) `40001`) (中文(简体) ). `db.transactionWithRetry` 重新运行这些冲突的全部交易.

```ts
import { sql } from "drizzle-orm";

await db.transactionWithRetry(async (tx) => {
  await tx.update(accounts).set({ balance: sql`balance - 100` }).where(...);
  await tx.update(accounts).set({ balance: sql`balance + 100` }).where(...);
});
```

每一次重试都重播回话,所以 **必须是一能的** ——不得重复的副作用(电子邮件,队列写出). 保持交易平平:嵌入式 `tx.transaction()` 由于解释性错误而快速失败,所以部分工作永远不会被误认为一个承诺的保存点.

重试默认值为 `maxRetries` 3个, `baseDelayMs` 50岁, `maxDelayMs` 5000 (责任后退与等焦. 通过一个可选交易配置第二, 重试超过第三; 当重试用完后, 将丢弃 `AwsDsqlRetryExhaustedError` (最后一场冲突是 `.cause`) (中文(简体) ).

```ts
await db.transactionWithRetry(
  async (tx) => { await tx.insert(orders).values({ ... }); },
  { isolationLevel: "serializable" },
  { maxRetries: 5, onRetry: (err, attempt, max) => log.warn({ err, attempt, max }) },
);
```

## 移徙

导入 `migrate` 从这个包裹。 它每笔交易应用一个 DDL 语句——匹配 DSQL 如何运行 DDL —— 并逐个跟踪每个语句, 所以用它来代替库存 `drizzle-orm/node-postgres` 映射器, 它发送单个交易中的每个语句 :

```ts
import { migrate, getMigrationStatus } from "@aws/aurora-dsql-drizzle";

const result = await migrate(db, { migrationsFolder: "./drizzle" });
if (!result.success) throw new Error(result.error.message);
```

工作流程如下:

1.  **生成** SQL 从您的计划并重写它为 DSQL:
    
    ```bash
    npx aurora-dsql-drizzle generate --out ./drizzle -- --config drizzle.config.ts
    ```
    
    这个运行 `drizzle-kit generate`,然后用 [`dsql-lint`](https://github.com/awslabs/aurora-dsql-tools/tree/main/dsql-lint) ——"奥罗拉"号DSQL穿透和固定器——同时保留了"德利兹"号 `--> statement-breakpoint` 标记。 转了 `CREATE INDEX` 输入 `CREATE INDEX ASYNC`,重写 `SERIAL` 列为 `BIGINT … GENERATED … AS IDENTITY` (扩大类型——审查),并添加 `NOT VALID` 以 `ALTER TABLE`审查和承诺结果。 (`transform` 财务报告和审定财务报表 `lint` 子命令独自运行这些步骤。 )
    
    对于每个创建后外国密钥,分别添加一个 `ALTER TABLE ASYNC ... VALIDATE CONSTRAINT ...` 转换后的语句 `NOT VALID` 语句。 约束立即适用于新写作; 验证 检查现有行。 美容师等待着这个同步的工作.
    
    奥罗拉 DSQL 支持 `NO ACTION`, (中文(简体) ), `RESTRICT`, (中文(简体) ), `CASCADE`, (中文(简体) ), `SET NULL`,以及 `SET DEFAULT`附加时 `MATCH SIMPLE`, (中文(简体) ), `MATCH FULL`,和可延期的外国 键。 分级动作算上交易行修改限制. 偏爱 `NO ACTION` 或者说 `RESTRICT` 用于无约束儿童 交易重试处理, 因为外国密钥冲突可以浮出水面 序列化失败.
    
    留着"滴水"吧 `breakpoints: true` (默认). 适配器每个标记应用一个语句,因此持有一个以上语句的断点文件被以解释性错误拒绝,而不是作为单一多语句交易发送.
    
    已知限制:变换法将每个语句分别插入,因此一次需要多个语句的定律不适用. 要知道的情况是 `ALTER COLUMN … ADD GENERATED … AS IDENTITY`,哪个 `dsql-lint` 折叠到上一个 `CREATE TABLE` 当他看见他们俩在一起的时候,他只看见他们俩 `ALTER` 并报告为无法修复。 在表格定义中定义身份列,或用手将两个语句合并.
    
2.  **应用** 在部署时承诺的迁移,使用 `migrate()` 以上拨打.
    
    每个语句都单独应用(自动承诺),然后记录在跟踪表里,所以一个被中断的跑道恢复它留下的地方——记录的语句被跳出. 同步 DDL (`CREATE INDEX ASYNC`, (中文(简体) ), `ALTER TABLE ASYNC … VALIDATE CONSTRAINT`因此,一个失败的背景工作从未报告为成功。 相冲突的声明在DSQL的乐观-货币错误上被重审. `getMigrationStatus(db, config)` 对待处理的报告不作任何改动.
    
    关于恢复问题的一个告诫是:声明及其跟踪行是单独的承诺。 如果运行在它们之间的空隙中死亡,则该语句被应用而未被跟踪,并且因为 `drizzle-kit` 发射 `CREATE TABLE` 无 `IF NOT EXISTS` 重运行失败 . `migrate()` 的报表,以便您手动对齐跟踪表.
    

## 国 际

```
aurora-dsql-drizzle generate [--out <dir>] [-- <drizzle-kit args>]   Generate + transform
aurora-dsql-drizzle transform [input] [-o output]                    Transform SQL for DSQL
aurora-dsql-drizzle lint [input]                                      Lint SQL for DSQL
```

退出代码 : `0` 干净, `1` 无法修复的错误仍然存在(以及适配器自己的使用错误,例如未知的旗帜), `2` 从 dsql-lint 传播的使用错误, `3` 用咨询意见固定(例如:. `NOT VALID` 添加到外国密钥中——在应用前添加同步验证.

## 示例

见 [实例/应用](https://npmcn.com/package/%40aws/aurora-dsql-drizzle/examples/veterinary-app/) 完成一个项目:计划、承诺的DSQL迁移, `db:migrate` 脚本,以及针对活集群的集成测试.

## 资源

-   [Amazon Aurora DSQL 文档](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/what-is-aurora-dsql.html)
-   [DSQL 不支持的 PostgreSQL 特性](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-unsupported-features.html)
-   [Aurora DSQL 节点连接器](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres)
-   [Drizzle ORM 文档](https://orm.drizzle.team/docs)
-   [dsql-lint (日语)](https://github.com/awslabs/aurora-dsql-tools/tree/main/dsql-lint)

## 警卫

见 [捐款](https://npmcn.com/package/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @aws/aurora-dsql-drizzle 是什么？

Amazon Aurora DSQL 的 Drizzle ORM 适配器

### 如何安装 @aws/aurora-dsql-drizzle？

在项目目录运行 npm install @aws/aurora-dsql-drizzle，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：pg（\>=8）、drizzle-orm（^0\.45）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 aurora-dsql-drizzle，可以用 npx aurora-dsql-drizzle 直接运行。

### @aws/aurora-dsql-drizzle 支持 TypeScript 吗？

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

### @aws/aurora-dsql-drizzle 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws/aurora-dsql-drizzle 需要什么版本的 Node\.js？

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

### @aws/aurora-dsql-drizzle 可以商用吗？

@aws/aurora-dsql-drizzle 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws/aurora-dsql-drizzle 的下载量有多少？

根据 npm 官方下载统计，@aws/aurora-dsql-drizzle 在 2026/10/08 – 2026/11/06 这 30 天内被下载 19,386 次，日均约 646 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws/aurora-dsql-drizzle 还在维护吗？

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