/aurora-dsql

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"