用于 Drizzle ORM 的 Aurora DSQL 适配器
滴入外科手术 支持 亚马逊·奥罗拉 DSQL。 。 。 .
它继续前进 drizzle-orm/node-postgres页:1 Aurora DSQL 连接器 是一个 pg.Pool 有IAM标志认证,所以没有定制方言——只是一丝不苟 drizzle() 工厂,一个选入的OCC重试帮助器,一个DSQL-有意识的植入器,和一个迁移CLI.
所需资源
- 滴入外科手术
^0.45财务报告和审定财务报表pg>=8(同类依赖关系) - 节点.js
>=20 - Aurora DSQL 集群和 AWS 证书
dsql:DbConnect对于您所连接的数据库角色
安装
npm install @aws/aurora-dsql-drizzle drizzle-orm pg
npm install -D drizzle-kit
IAM认证和TLS由连接器处理.
连接
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认证 用于创建只授予您应用程序需要的特权的角色。 不存在默认,所以一个连接永远不会降落在 admin 以无所取.
已经有泳池了? 直接通过: drizzle({ client: pool, schema })时 pool 是一个 AuroraDSQLPool (或任何 pg.Pool) (中文(简体) ). db.$client 暴露基本池;调用 await db.$client.end() 关闭它.
与OCC 重试的交易
DSQL 使用乐观的货币控制: ComMIT 交易失败与 OC000 编号 : OC001 (标准数据) 40001) (中文(简体) ). db.transactionWithRetry 重新运行这些冲突的全部交易.
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) (中文(简体) ).
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 映射器, 它发送单个交易中的每个语句 :
import { migrate, getMigrationStatus } from "@aws/aurora-dsql-drizzle";
const result = await migrate(db, { migrationsFolder: "./drizzle" });
if (!result.success) throw new Error(result.error.message);
工作流程如下:
-
生成 SQL 从您的计划并重写它为 DSQL:
npx aurora-dsql-drizzle generate --out ./drizzle -- --config drizzle.config.ts这个运行
drizzle-kit generate,然后用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并报告为无法修复。 在表格定义中定义身份列,或用手将两个语句合并. -
应用 在部署时承诺的迁移,使用
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 添加到外国密钥中——在应用前添加同步验证.
示例
见 实例/应用 完成一个项目:计划、承诺的DSQL迁移, db:migrate 脚本,以及针对活集群的集成测试.
资源
警卫
见 捐款 更多信息.
许可证
阿帕奇 - 2.0