feat(databases-on-aws): add Drizzle ORM guidance to DSQL skill

[praba2210]

Adds Aurora DSQL guidance for the newly shipped @aws/aurora-dsql-drizzle adapter, bringing Drizzle to parity with the existing EF Core coverage.

Related

• Adapter: awslabs/aurora-dsql-orms — node/drizzle (v0.1.0)

Changes

New content

• references/orm-guides/overview.md — Drizzle (TypeScript) section: adapter row, requirements, and an 11-row gotchas table (setup, required user, OCC retry, retry exhaustion, migrations, generate, SERIAL, breakpoints, identity columns, foreign keys, resume). Placed between Django and EF Core to keep the file alphabetical.
• references/language.md — #### Drizzle under JavaScript/TypeScript, alphabetically before Prisma.
• tools/evals/.../evals.json — evals 22 (data-layer setup) and 23 (migration failure), LLM-judge, 4 assertions each.
• tools/evals/.../trigger_evals.json — 2 should-trigger cases, 1 should-not-trigger control (Drizzle against self-hosted PostgreSQL).

Extended existing content

• SKILL.md — Drizzle added to the description, tags, ORM-guides table, and the Workflow 11 heading.
• references/auth/connectivity-tools.md — Drizzle row in the adapters table; count 4 → 5.
• references/dsql-lint.md — Drizzle added to the ORM-output list, plus a bullet for aurora-dsql-drizzle generate and the CLI exit codes.
• references/orm-guides/overview.md — Drizzle added to the shared foreign-key preamble (raw-SQL hook and composite-mapping lists).
• tools/evals/databases-on-aws/README.md — counts (21→23 prompts, 85→93 assertions, 37→40 trigger cases) and two table rows.
• Version 1.8.1 → 1.9.0 across the three manifests.

Verification — every technical claim was checked against the adapter source, its committed example migrations, and live dsql_lint: peer ranges and engines, the required-user guard, optional region, retry defaults and argument order, sys.wait_for_job, breakpoint rejection, CLI exit codes, the serial_type and at_unsupported_alter_column_add_generated rules, and that drizzle-kit emits no IF NOT EXISTS. mise run lint, fmt:check, and test (125 passed) are green.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Adds Aurora DSQL guidance and eval coverage for using Drizzle ORM via the newly shipped @aws/aurora-dsql-drizzle adapter, bringing TypeScript/Drizzle to parity with existing ORM guidance.

Changes:

• Adds Drizzle adapter setup/migration gotchas to the ORM overview and language reference docs.
• Extends DSQL linting guidance with Drizzle-specific generation/transform steps.
• Adds new Drizzle-related functional and trigger eval cases; bumps plugin version to 1.9.0.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/evals/databases-on-aws/dsql/trigger_evals.json	Adds trigger/non-trigger queries for Drizzle-on-DSQL vs Drizzle-on-Postgres routing.
tools/evals/databases-on-aws/dsql/evals.json	Adds functional evals validating correct Drizzle adapter and migration guidance.
tools/evals/databases-on-aws/README.md	Updates eval counts and documents the new Drizzle eval entries.
plugins/databases-on-aws/skills/dsql/references/orm-guides/overview.md	Adds Drizzle adapter row and a detailed gotchas section for setup/migrations/retries/FKs.
plugins/databases-on-aws/skills/dsql/references/language.md	Adds a Drizzle subsection under JS/TS with key adapter and workflow pointers.
plugins/databases-on-aws/skills/dsql/references/dsql-lint.md	Adds Drizzle generation guidance and notes CLI exit codes.
plugins/databases-on-aws/skills/dsql/references/auth/connectivity-tools.md	Adds Drizzle adapter row and updates specialized-adapter count.
plugins/databases-on-aws/skills/dsql/SKILL.md	Adds Drizzle to description/tags and updates ORM workflow naming/table text.
plugins/databases-on-aws/.codex-plugin/plugin.json	Bumps plugin version to 1.9.0.
plugins/databases-on-aws/.claude-plugin/plugin.json	Bumps plugin version to 1.9.0.
.claude-plugin/marketplace.json	Bumps marketplace plugin version to 1.9.0.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[spencercorwin]

Looks good to me, but also running agent review now and will update

[spencercorwin]

Agent-Lead Code review

The Drizzle guidance is useful, but I found seven validated issues. The highest-impact issue is the CLI exit-code guidance, which can send users down the wrong recovery path or bypass the skill's existing acknowledgement gate.

Validated findings

#	Confidence	Area	Finding	Suggestion	Validation process	Reviewed SHA
1	100	dsql-lint.md L97-L98 (correctness)	The exit-code mapping says 1 means SQL needs a hand-written rewrite and 2 means a usage error. The adapter also returns 1 for its own argument and input errors, while lint does not write transformed SQL. This can make users rewrite valid SQL or try to apply unchanged SQL.	Document each subcommand separately. State that adapter usage/input errors can return 1, and distinguish lint from the commands that write fixes.	Compared the text with adapter 0.1.0 source. rejectUnknownFlags, missing-input paths, and unknown commands exit 1; lint only reports diagnostics. npm confirms 0.1.0 is the published latest version.	ff5f6608e0f84cfbde0e1cc09543469c978c1fb7
2	95	dsql-lint.md L97-L98 (safety)	Exit 3 is described as “review … then apply,” but the same skill requires agents to surface every diagnostic and the rewritten SQL, then obtain user acknowledgement for fixed_with_warning. Foreign-key rewrites produce this status.	Route exit 3 through the existing fixed_with_warning workflow. Require diagnostic display, rewritten-SQL review, and user acknowledgement before application.	Re-read the current workflow at lines 59–75 and critical rules at lines 84–86. Adapter tests and source confirm foreign-key NOT VALID rewrites return 3.	ff5f6608e0f84cfbde0e1cc09543469c978c1fb7
3	95	overview.md L23-L48 (setup)	The copyable installation command omits drizzle-kit, although the section requires it and the documented generation workflow invokes it. A clean project following the table cannot run the workflow.	Add npm install -D drizzle-kit, or split the install column into runtime and development commands.	Compared the guide with the published package README and package.json; both list drizzle-kit as a development dependency. This also remains an unresolved existing review comment.	ff5f6608e0f84cfbde0e1cc09543469c978c1fb7
4	95	evals.json L261-L270 (tests)	Eval 22 asks for connection setup and its expected output requires host, user, region, and schema, but no graded assertion checks that setup. A generic adapter recommendation can pass without usable connection guidance.	Add an assertion requiring the drizzle({ connection: { host, user, region }, schema }) shape, allowing region omission only when host inference is explained.	Compared the prompt and expected_output with all four graded expectations. Only user is graded; host, region, and schema are not.	ff5f6608e0f84cfbde0e1cc09543469c978c1fb7
5	95	evals.json L273-L282 (tests)	Eval 23's expected output requires foreign-key NOT VALID handling and SERIAL widening review, but neither behavior is graded. The eval can pass while omitting two migration-safety rules introduced by this PR.	Add assertions for post-creation foreign-key validation and SERIAL-to-BIGINT IDENTITY widening review.	Compared the expected output with the four expectations. The adapter source and tests confirm both transformations are intentional user-visible behavior.	ff5f6608e0f84cfbde0e1cc09543469c978c1fb7
6	90	overview.md L58-L63 (migrations)	The guide tells users to append a separate asynchronous validation statement but does not tell them to add a --> statement-breakpoint. Without that marker, the migrator can reject the file as a multi-statement chunk.	Show the validation statement with a preceding breakpoint marker, or state explicitly that every manually added statement needs one.	Confirmed the migrator rejects multi-statement chunks and the adapter's committed foreign-key example places a breakpoint between each add and validation statement.	ff5f6608e0f84cfbde0e1cc09543469c978c1fb7
7	85	overview.md L59 (performance)	The SERIAL rewrite documents CACHE 1 but only asks users to review type widening. Elsewhere, this skill reserves CACHE 1 for low allocation rates and recommends at least 65536 for throughput.	Add a throughput warning and tell users to choose CACHE 65536 for high-allocation identity columns.	Cross-checked the new row with the skill's scaling, auto-increment, OCC, and EF Core guidance. They consistently distinguish CACHE 1 ordering from CACHE 65536 throughput.	ff5f6608e0f84cfbde0e1cc09543469c978c1fb7

[praba2210]

Thanks — ran all seven against @aws/aurora-dsql-drizzle 0.1.0 and @aws/dsql-lint 0.2.17 (executed the CLI, not just read it). 3 fixed, 4 look like false positives.

#	Verdict	Basis
1	Fixed	Mapping was wrong, different mechanism than described: lint mode returns 1 for any diagnostic, including ones the transform fixes silently. CREATE INDEX ASYNC idx ON t USING btree (c) → one fixed-status diagnostic, {errors: 0, warnings: 0, fixed: 0}, yet lint exits 1 while --fix exits 0. 3 is fix-mode only per dsql-lint --help. Now split by mode. 2 never reaches the caller — the adapter passes fixed args and a dsql-lint usage error emits non-JSON, so the parse throws and it exits 1; dropped that clause and documented your real point instead: 1 can be bad args / missing file / drizzle-kit failure, so check stderr first
6	Fixed	Worse than "can reject": transform on a 2-statement chunk exits 0 with no marker inserted and no diagnostic, so migrate() stops with success: false at apply time — and it rejects any such chunk, not just breakpoint-free files. Breakpoints + Foreign keys rows and the dsql-lint.md bullet now require the marker
3	Fixed	Added npm install -D drizzle-kit (same as Copilot's comment). npx drizzle-kit can fetch on demand, so not a blocker, but the cell should match the prose below it
2	False positive	The fixed_with_warning gate governs SQL the agent runs via transact after MCP dsql_lint; exit 3 is the CLI writing files that migrate() applies. dsql-lint.md already names the specific remediation (ALTER TABLE ASYNC ... VALIDATE CONSTRAINT + job verification)
4, 5	False positive	Only expectations are graded (one judge call each); expected_output is prose for the report artifact. Corpus-wide convention — evals 15/16 have 137- and 115-word expected_output against 5 expectations. Happy to add host/region/schema and FK/SERIAL assertions if you want broader grading
7	False positive	The row documents emitted output, verified: id BIGINT PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY ( CACHE 1 ). Matches the skill's PostgreSQL SERIAL mapping (pg-migrations/type-mapping.md:135, schema-objects.md:143); 65536 covers MySQL AUTO_INCREMENT and high-throughput sequences. Recommending it here means hand-editing generated DDL

On the FK note: native foreign-key handling needs @aws/dsql-lint >= 0.2.17. Upstream main pins that and documents it in node/drizzle/README.md ("adds NOT VALID to foreign keys created with ALTER TABLE"), but the change is still under [Unreleased], so the published 0.1.0 tarball pins >=0.2.14 and its README still says foreign keys are removed. A fresh install resolves 0.2.17 and emits NOT VALID (what I measured); a lockfile holding 0.2.14-0.2.16 would strip them instead. Adding that floor to the skill's Drizzle requirements line.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.