{"_id":"@aws/aurora-dsql-drizzle","_rev":"2-2812ad8f0084f94e00b4f92c487deee3","name":"@aws/aurora-dsql-drizzle","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aws/aurora-dsql-drizzle","version":"0.1.0","keywords":["drizzle","drizzle-orm","aurora","dsql","aws","database","postgresql"],"author":{"name":"Amazon Web Services"},"license":"Apache-2.0","_id":"@aws/aurora-dsql-drizzle@0.1.0","maintainers":[{"name":"aws-aurora-dsql-devex","email":"dsql-dev-ex@amazon.com"}],"homepage":"https://github.com/awslabs/aurora-dsql-orms#readme","bugs":{"url":"https://github.com/awslabs/aurora-dsql-orms/issues"},"bin":{"aurora-dsql-drizzle":"dist/cli/index.js"},"dist":{"shasum":"e35c619500bdf55e843cb9fe33d3d8f87036ccb2","tarball":"https://registry.npmjs.org/@aws/aurora-dsql-drizzle/-/aurora-dsql-drizzle-0.1.0.tgz","fileCount":38,"integrity":"sha512-c8uKGK3Ymkm0ZYtttesNnoC/VM7merUrC6SZXLRKtmvkYRqlh+LZ2lYDGf5JqjJWd9bzRwJveDSXpROtIaJccQ==","signatures":[{"sig":"MEUCIQDfAF8Eo5WjOhKYMWBm0fJhA8dEG83smgm1irDsQyf6IgIgPRPhekgMHCJaydorxH3jdYr9IGxuuHWtD+XZRuf6doo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":102581},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"test":"NODE_OPTIONS='--experimental-vm-modules' jest","build":"tsc","format":"prettier --write .","pretest":"npm run build","dsql-lint":"tsx src/cli/index.ts lint","format:check":"prettier --check .","dsql-generate":"tsx src/cli/index.ts generate","dsql-transform":"tsx src/cli/index.ts transform"},"_npmUser":{"name":"aws-aurora-dsql-devex","email":"dsql-dev-ex@amazon.com"},"repository":{"url":"git+https://github.com/awslabs/aurora-dsql-orms.git","type":"git","directory":"node/drizzle"},"_npmVersion":"10.9.7","description":"Drizzle ORM adapter for Amazon Aurora DSQL","directories":{},"_nodeVersion":"22.22.2","dependencies":{"@aws/dsql-lint":">=0.2.14 <1","@aws/aurora-dsql-node-postgres-connector":">=0.1.9 <1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"pg":"^8.16.0","tsx":"^4.20.3","ts-jest":"^29.4.1","prettier":"4.0.0-alpha.13","@types/pg":"^8.15.0","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^25.2.0","drizzle-kit":"^0.31.0","drizzle-orm":"^0.45.2"},"peerDependencies":{"pg":">=8","drizzle-orm":"^0.45"},"_npmOperationalInternal":{"tmp":"tmp/aurora-dsql-drizzle_0.1.0_1787708331370_0.3040894348646985","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@aws/aurora-dsql-drizzle@0.2.0","bin":{"aurora-dsql-drizzle":"dist/cli/index.js"},"bugs":{"url":"https://github.com/awslabs/aurora-dsql-orms/issues"},"dist":{"shasum":"1cd1f1b1cad5659a73c6ab998c8d64668098d70d","tarball":"https://registry.npmjs.org/@aws/aurora-dsql-drizzle/-/aurora-dsql-drizzle-0.2.0.tgz","fileCount":38,"integrity":"sha512-e0oW9X7FL4YTKrAopiX6g8pzfzYkc7fCfV4tUfSQ94/V6AmmFwP8dz1dLz+Ly6rQZ706PluVBhK/0wNDkFZNIw==","signatures":[{"sig":"MEQCIGDyxtiuxuUiCJvHbOWq2pv8+E/GPH53JxsFdcx8e1/rAiBT2zoO2U14ucjSW/IS0pFRXFRX/iqM8arRBxrmigUrqg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDsj413DuyojvcArfSXBWNDci7IV0iQK3OC11UyH+wwDwIhAIZmHWsiTVTx5UjeYJlfXJshL37nOlmk+A03djoECqJ0"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aws%2faurora-dsql-drizzle@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":103605},"main":"dist/index.js","name":"@aws/aurora-dsql-drizzle","types":"dist/index.d.ts","author":{"name":"Amazon Web Services"},"engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"3e6eee5aed03ff177aa79ca1032d5277226f6fa1","license":"Apache-2.0","scripts":{"test":"NODE_OPTIONS='--experimental-vm-modules' jest","build":"tsc","format":"prettier --write .","pretest":"npm run build","dsql-lint":"tsx src/cli/index.ts lint","format:check":"prettier --check .","dsql-generate":"tsx src/cli/index.ts generate","dsql-transform":"tsx src/cli/index.ts transform"},"version":"0.2.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4c15138e-7680-490e-ab3b-e4a385a7f2ca"}},"homepage":"https://github.com/awslabs/aurora-dsql-orms#readme","keywords":["drizzle","drizzle-orm","aurora","dsql","aws","database","postgresql"],"repository":{"url":"git+https://github.com/awslabs/aurora-dsql-orms.git","type":"git","directory":"node/drizzle"},"_npmVersion":"11.5.1","description":"Drizzle ORM adapter for Amazon Aurora DSQL","directories":{},"maintainers":[{"name":"aws-aurora-dsql-devex","email":"dsql-dev-ex@amazon.com"}],"_nodeVersion":"22.23.2","dependencies":{"@aws/dsql-lint":">=0.2.17 <1","@aws/aurora-dsql-node-postgres-connector":">=0.1.9 <1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"pg":"^8.16.0","tsx":"^4.23.13","ts-jest":"^29.4.1","prettier":"4.0.0-alpha.13","@types/pg":"^8.23.1","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^26.6.1","drizzle-kit":"^0.31.0","drizzle-orm":"^0.45.2"},"peerDependencies":{"pg":">=8","drizzle-orm":"^0.45"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aurora-dsql-drizzle_0.2.0_1790362756701_0.08000381071502294"}}},"time":{"created":"2026-08-26T01:38:51.279Z","modified":"2026-09-25T18:59:17.062Z","0.1.0":"2026-08-26T01:38:51.520Z","0.2.0":"2026-09-25T18:59:16.783Z"},"bugs":{"url":"https://github.com/awslabs/aurora-dsql-orms/issues"},"author":{"name":"Amazon Web Services"},"license":"Apache-2.0","homepage":"https://github.com/awslabs/aurora-dsql-orms#readme","keywords":["drizzle","drizzle-orm","aurora","dsql","aws","database","postgresql"],"repository":{"url":"git+https://github.com/awslabs/aurora-dsql-orms.git","type":"git","directory":"node/drizzle"},"description":"Drizzle ORM adapter for Amazon Aurora DSQL","maintainers":[{"name":"aws-aurora-dsql-devex","email":"dsql-dev-ex@amazon.com"}],"readme":"# Aurora DSQL adapter for Drizzle ORM\n\n[![GitHub](https://img.shields.io/badge/github-awslabs/aurora--dsql--orms-blue?logo=github)](https://github.com/awslabs/aurora-dsql-orms)\n[![npm version](https://img.shields.io/npm/v/@aws/aurora-dsql-drizzle.svg)](https://www.npmjs.com/package/@aws/aurora-dsql-drizzle)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Discord chat](https://img.shields.io/discord/1435027294837276802.svg?logo=discord)](https://discord.com/invite/nEF6ksFWru)\n\n[Drizzle ORM](https://orm.drizzle.team/) support for [Amazon Aurora DSQL](https://aws.amazon.com/rds/aurora/dsql/).\n\nIt rides on `drizzle-orm/node-postgres`: the [Aurora DSQL connector](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) is a `pg.Pool` with IAM token authentication, so there is no custom dialect — just a thin `drizzle()` factory, an opt-in OCC retry helper, a DSQL-aware migrator, and a migration CLI.\n\n## Requirements\n\n- Drizzle ORM `^0.45` and `pg` `>=8` (peer dependencies)\n- Node.js `>=20`\n- An Aurora DSQL cluster, and AWS credentials with `dsql:DbConnect` for the database role you connect as\n\n## Install\n\n```bash\nnpm install @aws/aurora-dsql-drizzle drizzle-orm pg\nnpm install -D drizzle-kit\n```\n\nIAM authentication and TLS are handled by the connector.\n\n## Connect\n\n```ts\nimport { drizzle } from \"@aws/aurora-dsql-drizzle\";\nimport * as schema from \"./schema\";\n\nconst db = drizzle({\n  connection: {\n    host: process.env.CLUSTER_ENDPOINT!, // <id>.dsql.<region>.on.aws\n    region: \"us-east-1\", // optional; inferred from the host otherwise\n    user: \"myuser\", // a database role scoped to what your app needs\n    options: \"-c search_path=myschema\",\n  },\n  schema,\n});\n\nconst owners = await db.select().from(schema.owner);\n```\n\n`user` is required — see [Using database roles and IAM authentication](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html) for creating a role granted only the privileges your application needs. There is no default, so a connection never lands on `admin` by omission.\n\nAlready have a pool? Pass it directly: `drizzle({ client: pool, schema })`, where `pool` is an `AuroraDSQLPool` (or any `pg.Pool`). `db.$client` exposes the underlying pool; call `await db.$client.end()` to close it.\n\n## Transactions with OCC retry\n\nDSQL uses optimistic concurrency control: conflicting transactions fail at COMMIT with `OC000` / `OC001` (SQLSTATE `40001`). `db.transactionWithRetry` re-runs the whole transaction on those conflicts.\n\n```ts\nimport { sql } from \"drizzle-orm\";\n\nawait db.transactionWithRetry(async (tx) => {\n  await tx.update(accounts).set({ balance: sql`balance - 100` }).where(...);\n  await tx.update(accounts).set({ balance: sql`balance + 100` }).where(...);\n});\n```\n\nThe callback is re-run on every retry, so it **must be idempotent** — no side effects (emails, queue writes) that must not repeat. Keep transactions flat: a nested `tx.transaction()` fails fast with an explanatory error, so partial work is never mistaken for a committed savepoint.\n\nRetry defaults are `maxRetries` 3, `baseDelayMs` 50, `maxDelayMs` 5000 (exponential backoff with equal jitter). Pass an optional transaction config second and retry overrides third; when retries are exhausted it throws `AwsDsqlRetryExhaustedError` (the last conflict is on `.cause`).\n\n```ts\nawait db.transactionWithRetry(\n  async (tx) => { await tx.insert(orders).values({ ... }); },\n  { isolationLevel: \"serializable\" },\n  { maxRetries: 5, onRetry: (err, attempt, max) => log.warn({ err, attempt, max }) },\n);\n```\n\n## Migrations\n\nImport `migrate` from this package. It applies one DDL statement per transaction — matching how DSQL runs DDL — and tracks each statement individually, so use it in place of the stock `drizzle-orm/node-postgres` migrator, which sends every statement in a single transaction:\n\n```ts\nimport { migrate, getMigrationStatus } from \"@aws/aurora-dsql-drizzle\";\n\nconst result = await migrate(db, { migrationsFolder: \"./drizzle\" });\nif (!result.success) throw new Error(result.error.message);\n```\n\nThe workflow is:\n\n1. **Generate** SQL from your schema and rewrite it for DSQL:\n\n   ```bash\n   npx aurora-dsql-drizzle generate --out ./drizzle -- --config drizzle.config.ts\n   ```\n\n   This runs `drizzle-kit generate`, then rewrites each statement with [`dsql-lint`](https://github.com/awslabs/aurora-dsql-tools/tree/main/dsql-lint) — the Aurora DSQL linter and fixer — while preserving Drizzle's `--> statement-breakpoint` markers. It turns `CREATE INDEX` into `CREATE INDEX ASYNC`, rewrites `SERIAL` columns as `BIGINT … GENERATED … AS IDENTITY` (a type widening — review it), and adds `NOT VALID` to foreign keys created with `ALTER TABLE`. Review and commit the result. (`transform` and `lint` subcommands run those steps on their own.)\n\n   For every post-creation foreign key, add a separate `ALTER TABLE ASYNC\n... VALIDATE CONSTRAINT ...` statement after the transformed `NOT VALID`\n   statement. The constraint applies to new writes immediately; the validation\n   job checks existing rows. The migrator waits for that asynchronous job.\n\n   Aurora DSQL supports `NO ACTION`, `RESTRICT`, `CASCADE`, `SET NULL`, and\n   `SET DEFAULT`, plus `MATCH SIMPLE`, `MATCH FULL`, and deferrable foreign\n   keys. Cascading actions count toward transaction row-modification limits.\n   Prefer `NO ACTION` or `RESTRICT` for unbounded child cardinality and use\n   transaction retry handling because foreign-key conflicts can surface as\n   serialization failures.\n\n   Keep Drizzle Kit's `breakpoints: true` (the default). The adapter applies one statement per marker, so a breakpoint-free file holding more than one statement is rejected with an explanatory error rather than sent as a single multi-statement transaction.\n\n   Known limitation: the transform lints each statement separately, so a fix needing more than one statement at a time does not apply. The case to know about is `ALTER COLUMN … ADD GENERATED … AS IDENTITY`, which `dsql-lint` folds into the preceding `CREATE TABLE` when it sees both together; here it sees only the `ALTER` and reports it as unfixable. Define identity columns in the table definition, or merge the two statements by hand.\n\n2. **Apply** the committed migrations at deploy time, using the `migrate()` call above.\n\n   Each statement is applied on its own (autocommit) and then recorded in a tracking table, so a run interrupted partway resumes where it left off — recorded statements are skipped. Asynchronous DDL (`CREATE INDEX ASYNC`, `ALTER TABLE ASYNC … VALIDATE CONSTRAINT`) is awaited before the statement is recorded, so a failed background job is never reported as success. Conflicting statements are retried on DSQL's optimistic-concurrency errors. `getMigrationStatus(db, config)` reports applied vs. pending without changing anything.\n\n   One caveat on resuming: a statement and its tracking row are separate commits. If a run dies in the gap between them, the statement is applied but untracked, and because `drizzle-kit` emits `CREATE TABLE` without `IF NOT EXISTS` the re-run fails with \"already exists\". `migrate()` reports which statement it was so you can reconcile the tracking table by hand.\n\n## CLI\n\n```\naurora-dsql-drizzle generate [--out <dir>] [-- <drizzle-kit args>]   Generate + transform\naurora-dsql-drizzle transform [input] [-o output]                    Transform SQL for DSQL\naurora-dsql-drizzle lint [input]                                      Lint SQL for DSQL\n```\n\nExit codes: `0` clean, `1` unfixable errors remain (and the adapter's own usage errors, e.g. an unknown flag), `2` usage error propagated from dsql-lint, `3` fixed with advisories (e.g. `NOT VALID` added to a foreign key — add asynchronous validation before applying).\n\n## Example\n\nSee [examples/veterinary-app](./examples/veterinary-app/) for a complete project: schema, committed DSQL migration, `db:migrate` script, and integration tests against a live cluster.\n\n## Resources\n\n- [Amazon Aurora DSQL documentation](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/what-is-aurora-dsql.html)\n- [Unsupported PostgreSQL features in DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-unsupported-features.html)\n- [Aurora DSQL connector for node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres)\n- [Drizzle ORM documentation](https://orm.drizzle.team/docs)\n- [dsql-lint](https://github.com/awslabs/aurora-dsql-tools/tree/main/dsql-lint)\n\n## Security\n\nSee [CONTRIBUTING](../../CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}