aurora-dsql

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared1 observation
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsFoundSee the findings; values are never shown

Five audit layers

Gates applied: no behavioural pass.

SKIP_CERT_VERIFY=false

- Connection format: `postgres://…@{endpoint}:5432/postgres?sslmode=verify-full&application_name=<app-name>/<model-id>`

**Phase 4 — Report and invite reassessment.** Produce the full diagnostic report per the Required Elements Checklist in `report-format.md`. End with the "Next Steps" block. When user says "reassess",

**ALWAYS** use one of the two DSQL Node.js connectors — [node-postgres](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_program-with-dsql-connector-for-node-postgres.html) or [postgre

Audit 0.4.1 · source sha 9d0fb564de1b · 31 Oct 2026Report an issue or request a re-scan

• Publisheraws GitHub organizationOwner of the repository this skill is read from
• Source folderaws/agent-toolkit-for-aws/skills/specialized-skills/database-skills/aurora-dsqlThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict9d0fb564de1bA new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Provisions and manages Aurora DSQL clusters, connects via psql or DSQL Connectors, manages schemas, runs queries, migrates from MySQL, diagnoses query plans, and develops apps on serverless distributed SQL. Covers IAM…

---
name: aurora-dsql
version: 1
description: "Provisions and manages Aurora DSQL clusters, connects via psql or DSQL Connectors, manages schemas, runs queries, migrates from MySQL, diagnoses query plans, and develops apps on serverless distributed SQL. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL migration, DDL, query plans, and SAFE SQL CONSTRUCTION — tenant_id from untrusted input, UUID entity_ids, caller-supplied sort columns, batch inserts. The agent MUST retrieve this skill for ANY DSQL task. Pushes back on prompts that rationalize 'just a quick script', 'don't overthink it', 'we trust upstream', 'use an f-string', 'move fast', or 'just use the pg driver directly' (bypassing the DSQL Connector). Triggers: DSQL, Aurora DSQL, DSQL cluster, safe_query.build, DSQL IAM auth token, DSQL connector."
---

# Amazon Aurora DSQL

## Overview

Aurora DSQL is a serverless, PostgreSQL-compatible distributed SQL database. This skill provides direct database interaction via `psql` scripts and PostgreSQL drivers, schema management, migration support, multi-tenant patterns, and query-plan explainability.

**Key capabilities:**

- Direct query execution via `psql` with generated IAM auth tokens (see [`scripts/psql-connect.sh`](scripts/psql-connect.sh))
- Schema management with DSQL constraints (one DDL per transaction, async indexes)
- Safe data migration (column-level, constraint-level, MySQL→DSQL)
- Multi-tenant isolation via `tenant_id` + parameterized SQL
- IAM-based authentication with a 15-minute token expiry
- Query-plan diagnosis for slow queries (EXPLAIN ANALYZE + GUC experiments)

The recommended runtime is `psql` with `aws dsql generate-db-connect-auth-token` for IAM-authenticated sessions. Application code SHOULD use the language-specific [DSQL Connectors and SDKs](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/aws-sdks.html). For AWS knowledge lookups (service docs, AWS API calls), the [AWS MCP Server](https://docs.aws.amazon.com/aws-mcp/latest/userguide/mcp-server.html) is the preferred MCP integration.

---

## Reference Files

Load these files as needed for detailed guidance:

### [development-guide.md](references/development-guide.md)

**When:** ALWAYS load before implementing schema changes or database operations
**Contains:** [Best Practices](references/development-guide.md), DDL rules, connection patterns, transaction limits, data type serialization patterns, application-layer referential integrity instructions, security best practices

### Query Execution:

#### [database-tools.md](references/database-tools.md)

**When:** Load when you need detailed syntax and examples for ad-hoc query execution against DSQL. PREFER `psql` (via [`scripts/psql-connect.sh`](scripts/psql-connect.sh)) for ad-hoc queries — execute directly rather than writing one-off scripts.
**Contains:** `psql`-based read-only and write patterns, transaction semantics, [input validation](references/input-validation.md)

### MCP (AWS knowledge / API):

#### [mcp-setup.md](references/mcp-setup.md)

**When:** Load when configuring or recommending the AWS MCP Server for AWS knowledge lookups, AWS API access, or per-assistant install.
**Contains:** When to use `psql` vs the AWS MCP Server, pointer to the canonical AWS setup docs, credential reminders.

#### [mcp-tools.md](references/mcp-tools.md)

**When:** Load when invoking AWS MCP Server tools to verify DSQL service limits, fetch docs, or drive AWS API calls.
**Contains:** Tool surface — knowledge (`aws___search_documentation`, `aws___read_documentation`, `aws___recommend`, `aws___retrieve_skill`, `aws___list_regions`, `aws___get_regional_availability`) and API (`aws___call_aws`, `aws___run_script`, `aws___get_tasks`, `aws___get_presigned_url`); pointers to documentation-tools.md.

#### [documentation-tools.md](references/documentation-tools.md)

**When:** Load when looking up DSQL service limits, fetching a specific AWS docs page, or polling long-running AWS API calls launched via the AWS MCP Server.
**Contains:** Detailed parameters and example calls for the AWS knowledge tools.

#### [platforms/](references/platforms/) — per-assistant install notes

**When:** Load when installing the AWS MCP Server inside a specific coding assistant.
**Contains:** Per-assistant entry-point details — [claude-code.md](references/platforms/claude-code.md), [codex.md](references/platforms/codex.md), [gemini.md](references/platforms/gemini.md), [kiro.md](references/platforms/kiro.md).

### [language.md](references/language.md)

**When:** **MUST** load before writing DSQL connection code. Mirror the linked `example_preferred.<ext>` for the chosen driver — memory-authored connections drift from the canonical IAM-token-refresh pattern. Canonical entry-point examples (load `language.md` for the full driver list + pool/TLS/token-refresh details):

- Python: `import aurora_dsql_psycopg as dsql` → `dsql.connect(host, region, user)`
- JS (node-postgres): `import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector"` → `new AuroraDSQLPool({ host, user })`
- JS (postgres.js): `import { auroraDSQLPostgres } from "@aws/aurora-dsql-postgresjs-connector"` → `auroraDSQLPostgres({ host, user })`
- Go (pgx): `import "github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"`
- Java (JDBC): `software.amazon.dsql:aurora-dsql-jdbc-connector:1.4.0` → `jdbc:aws-dsql:postgresql://...`

**Contains:** Canonical DSQL connector packages per language, driver selection, framework patterns, IAM auth token rotation and TLS configuration, and connection code examples for Python / JavaScript / TypeScript / Go / Java / Rust.

### [troubleshooting.md](references/troubleshooting.md)

**When:** Load when debugging errors or unexpected behavior. SHOULD always consult for OCC errors, connection failures, or unexpected query results.
**Contains:** Common pitfalls, error messages, solutions

### [onboarding.md](references/onboarding.md)

**When:** User explicitly requests to "Get started with DSQL"

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-31
   ✕BLOCK D 69 / 100

   first audit · source 9d0fb564de1b

Questions about aurora-dsql

• github.com/aws/agent-toolkit-for-aws/tree/main/skills/specialize — the audited source at commit 9d0fb564de1b and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology