Name: aurora-dsql
Author: aws

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 S

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" or similar phrase Contains: Interactive step by step guide for new users [access control.md](references/access control.md) When: MUST load when creating database roles, granting permissions, setting up schemas for applications, or handling sensitive data. ALWAYS use scoped roles for applications — create database roles with dsql:DbConnect . Contains: Scoped role setup, IAM to database role mapping, schema separation for sensitive data, role design patterns Authentication & Operations: [auth/authentication guide.md](references/auth/authentication guide.md) When: MUST load when handling IAM auth tokens, secrets, SSL/TLS, connection pooling, or audit logging. Contains: Token lifecycle, secret storage patterns, SSL/TLS settings, connection pool guidance, audit log integration. [auth/connectivity tools.md](references/auth/connectivity tools.md) When: Load when picking a driver/ORM/adapter or planning bulk data loading. Contains: Pointer to the canonical AWS DSQL connectivity tools page (drivers, ORMs, adapters) and the bulk loading docs page. [auth/scaling guide.md](references/auth/scaling guide.md) When: Load when designing for scale — connection pooling, batch optimization, hot key avoidance, identifier choice. Contains: Horizontal scaling strategy, pool sizing, batch size guidance, IDENTITY/UUID trade offs, sequence cache rules. Implementation Examples: [workflow patterns.md](references/workflow patterns.md) When: Load when looking for a worked example of a common multi step DSQL workflow (schema explore, CREATE+INDEX, safe migration, batch insert, application layer FK check). Contains: Five canonical patterns with psql / driver code. [dsql examples.md](references/dsql examples.md) When: Load when looking for specific implementation examples. Contains: Index of examples/ .md (connection, schema, data operations, migrations, patterns). DDL Migrations (modular): [ddl migrations/overview.md](references/ddl migrations/overview.md) When: MUST load when performing DROP COLUMN, RENAME COLUMN, ALTER COLUMN TYPE, or DROP CONSTRAINT Contains: Table recreation pattern overview, transaction rules, common verify & swap pattern [ddl migrations/column operations.md](references/ddl migrations/column operations.md) When: Load for DROP COLUMN, ALTER COLUMN TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT migrations Contains: Step by step migration patterns for column level changes [ddl migrations/constraint operations.md](references/ddl migrations/constraint operations.md) When: Load for ADD/DROP CONSTRAINT, MODIFY PRIMARY KEY, column split/merge migrations Contains: Step by step migration patterns for constraint and structural changes [ddl migrations/batched migration.md](references/ddl migrations/batched migration.md) When: Load when migrating tables exceeding 3,000 rows Contains: OFFSET based and cursor based batching patterns, progress tracking, error handling MySQL Migrations (modular): [mysql migrations/type mapping.md](references/mysql migrations/type mapping.md) When: MUST load when migrating MySQL schemas to DSQL Contains: MySQL data type mappings, feature alternatives, DDL operation mapping [mysql migrations/ddl operations.md](references/mysql migrations/ddl operations.md) When: Load when translating MySQL DDL operations to DSQL equivalents Contains: ALTER COLUMN, DROP COLUMN, AUTO INCREMENT, ENUM, SET, FOREIGN KEY migration patterns [mysql migrations/full example.md](references/mysql migrations/full example.md) When: Load when migrating a complete MySQL table to DSQL Contains: End to end MySQL CREATE TABLE migration example with decision summary Query Plan Explainability (modular): When: MUST load all four at Workflow 8 Phase 0 — [query plan/plan interpretation.md](references/query plan/plan interpretation.md), [query plan/catalog queries.md](references/query plan/catalog queries.md), [query plan/guc experiments.md](references/query plan/guc experiments.md), [query plan/report format.md](references/query plan/report format.md) Contains: DSQL node types + Node Duration math + estimation error bands, pg class/pg stats/pg indexes SQL + correlated predicate verification, GUC experiment procedures + 30 second skip protocol, required report structure + element checklist + support request template Query Execution Run ad hoc DSQL queries with psql and a freshly generated IAM auth token. The bundled [ scripts/psql connect.sh ](scripts/psql connect.sh) wraps token generation, TLS configuration, and single statement guards — PREFER it over hand rolled psql invocations. Read only: Write/DDL (IAM admin auth token required): Schema discovery: there is no special list tables helper — use information schema: See [database tools.md](references/database tools.md) for detailed usage and examples. AWS Knowledge via the AWS MCP Server (optional) When connected to the [AWS MCP Server](https://docs.aws.amazon.com/aws mcp/latest/userguide/mcp server.html), its aws search documentation and aws read documentation tools can verify DSQL service limits before advising users. The numeric limits below are defaults that may change — when a user's decision depends on an exact limit, verify it first: Limit Default Verify query Max rows mutated per transaction 3,000 aurora dsql transaction limits Max data modified per write transaction 10 MiB aurora dsql transaction limits Max transaction duration 5 minutes aurora dsql transaction limits Max connections per cluster 10,000 aurora dsql connection limits IAM auth token expiry 15 minutes aurora dsql authentication token Max connection duration 60 minutes aurora dsql connection limits Max indexes per table 24 aurora dsql index limits Max columns per index 8 aurora dsql index limits IDENTITY/SEQUENCE CACHE values 1 or = 65536 aurora dsql sequence cache When to verify: Before recommending batch sizes, connection pool settings, or schema designs where hitting a limit would cause failures. No need to verify for general guidance or when the exact number doesn't affect the user's decision. Fallback: If the AWS MCP Server is unavailable, use the defaults above and note to the user that limits should be verified against [DSQL documentation](https://docs.aws.amazon.com/aurora dsql/latest/userguide/). CLI Scripts Available Bash scripts in [scripts/](scripts/) for cluster management (create, delete, list, cluster info) and psql connection. See [ref