krokoko · Oct 9, 2026 · Sep 30, 2026 · Oct 7, 2026 · Oct 8, 2026 · Oct 8, 2026
@@ -191,7 +191,7 @@
         "serverless",
         "postgresql"
       ],
-      "version": "1.9.1"
+      "version": "1.10.0"
     },
     {
       "category": "deployment",

@@ -22,5 +22,5 @@
   "license": "Apache-2.0",
   "name": "databases-on-aws",
   "repository": "https://github.com/awslabs/agent-plugins",
-  "version": "1.9.1"
+  "version": "1.10.0"
 }
@@ -1,6 +1,6 @@
 {
   "name": "databases-on-aws",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "Expert database guidance for the AWS database portfolio. Design schemas, execute queries, handle migrations, and choose the right database for your workload.",
   "author": {
     "name": "Amazon Web Services",

@@ -1,6 +1,6 @@
 ---
 name: dsql
-description: "Build with Aurora DSQL — manage schemas, execute queries, handle migrations, diagnose query plans, diagnose cluster performance, load data, and develop applications with a serverless, distributed SQL database. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL and PostgreSQL-to-DSQL schema conversion, foreign key constraints, OCC retry patterns, ORM migration (Django/EF Core/Hibernate/Rails/SQLAlchemy), DDL operations, query plan explainability, system diagnostics via CloudWatch AAS, SQL compatibility validation, and bulk data loading. Triggers on phrases like: DSQL, Aurora DSQL, distributed SQL database, serverless PostgreSQL-compatible database, migrate to DSQL, DSQL query plan, DSQL EXPLAIN ANALYZE, DSQL ENUM, DSQL foreign key, DSQL OCC retry, DSQL multi-region, DSQL JSONB, DSQL GIN index, load into DSQL, load CSV into DSQL, bulk load DSQL, aurora-dsql-loader, DSQL slow, DSQL performance, DSQL wait events, DSQL AAS."
+description: "Build with Aurora DSQL — manage schemas, execute queries, handle migrations, diagnose query plans, diagnose cluster performance, load data, and develop applications with a serverless, distributed SQL database. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL and PostgreSQL-to-DSQL schema conversion, foreign key constraints, OCC retry patterns, ORM migration (Django/EF Core/Hibernate/Rails/SQLAlchemy), DDL operations, query plan explainability, system diagnostics via CloudWatch AAS, SQL compatibility validation, and bulk data loading. Load before answering DSQL limit or error-code questions; it has limits docs omit. Triggers on phrases like: DSQL, Aurora DSQL, distributed SQL database, serverless PostgreSQL-compatible database, migrate to DSQL, DSQL query plan, DSQL EXPLAIN ANALYZE, DSQL ENUM, DSQL foreign key, DSQL OCC retry, DSQL multi-region, DSQL JSONB, DSQL GIN index, load into DSQL, load CSV into DSQL, bulk load DSQL, aurora-dsql-loader, DSQL slow, DSQL performance, DSQL wait events, DSQL AAS."
 license: Apache-2.0
 metadata:
   tags: aws, aurora, dsql, distributed-sql, distributed, distributed-database, database, serverless, serverless-database, postgresql, postgres, sql, schema, migration, multi-tenant, iam-auth, aurora-dsql, mcp, orm, enum, foreign-key, occ-retry, django, ef-core, dotnet, csharp, hibernate, rails, multi-region, schema-conversion, type-mapping, data-loading, system-diagnostics, wait-events, aas, performance, cloudwatch
@@ -18,16 +18,17 @@ Load these files as needed for detailed guidance:
 
 ### Core:
 
-| Reference                                                 | When to Load                                        | Contains                                                                                 |
-| --------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| [development-guide.md](references/development-guide.md)   | ALWAYS before schema changes or DB operations       | Best practices, DDL rules, transaction limits, foreign key constraints                   |
-| [foreign-keys.md](references/foreign-keys.md)             | MUST load for foreign key operations or migrations  | FK syntax, actions, validation, tenant keys                                              |
-| [language.md](references/language.md)                     | MUST load for language-specific choices             | Driver selection, DSQL Connectors, connection code                                       |
-| [access-control.md](references/access-control.md)         | MUST load for roles, grants, or sensitive data      | Scoped role setup, IAM-to-database role mapping                                          |
-| [troubleshooting.md](references/troubleshooting.md)       | SHOULD load for errors or unexpected behavior       | OCC and `23503` errors, FK validation, connection failures, cluster state, DDL rejection |
-| [dsql-examples.md](references/dsql-examples.md)           | Load for implementation examples                    | Multi-tenant access, batch operations, identity and sequences, connection pooling        |
-| [onboarding.md](references/onboarding.md)                 | User requests "Get started with DSQL"               | Interactive step-by-step guide                                                           |
-| [occ-retry-patterns.md](references/occ-retry-patterns.md) | MUST load for OCC retry code or conflict mitigation | Connectors, `40001` retry, non-retryable `23503`, FK read conflicts, idempotent design   |
+| Reference                                                         | When to Load                                                                      | Contains                                                                               |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| [development-guide.md](references/development-guide.md)           | ALWAYS before schema changes or DB operations                                     | Best practices, DDL rules, transaction limits, foreign key constraints                 |
+| [foreign-keys.md](references/foreign-keys.md)                     | MUST load for foreign key operations or migrations                                | FK syntax, actions, validation, tenant keys                                            |
+| [language.md](references/language.md)                             | MUST load for language-specific choices                                           | Driver selection, DSQL Connectors, connection code                                     |
+| [access-control.md](references/access-control.md)                 | MUST load for roles, grants, or sensitive data                                    | Scoped role setup, IAM-to-database role mapping                                        |
+| [troubleshooting.md](references/troubleshooting.md)               | SHOULD load for errors or unexpected behavior                                     | OCC and `23503`, FK, connections, cluster state                                        |
+| [limits-and-error-codes.md](references/limits-and-error-codes.md) | SHOULD load before sizing batches, keys or indexes, or on `54000`/`0A000`/`54011` | Every limit, rejection and quota with SQLSTATE and exact message                       |
+| [dsql-examples.md](references/dsql-examples.md)                   | Load for implementation examples                                                  | Multi-tenant access, batch operations, identity and sequences, connection pooling      |
+| [onboarding.md](references/onboarding.md)                         | User requests "Get started with DSQL"                                             | Interactive step-by-step guide                                                         |
+| [occ-retry-patterns.md](references/occ-retry-patterns.md)         | MUST load for OCC retry code or conflict mitigation                               | Connectors, `40001` retry, non-retryable `23503`, FK read conflicts, idempotent design |
 
 ### MCP:
 
@@ -56,12 +57,12 @@ Load these files as needed for detailed guidance:
 
 ### PostgreSQL Migrations:
 
-| Reference                                                                         | When to Load                                                                      | Contains                                                                    |
-| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| [pg-migrations/type-mapping.md](references/pg-migrations/type-mapping.md)         | MUST load for DSQL NUMERIC or PG type questions                                   | C collation rules, NUMERIC(p,s), JSON/JSONB                                 |
-| [pg-migrations/index-conversion.md](references/pg-migrations/index-conversion.md) | MUST load for any index conversion or index support question                      | GIN/GiST/BRIN → btree, operator class removal, partial + expression indexes |
-| [pg-migrations/schema-objects.md](references/pg-migrations/schema-objects.md)     | MUST load for ENUM, materialized views, extensions, multi-schema, CREATE FUNCTION | ENUM → CHECK, views, role/IAM mapping, LANGUAGE sql functions               |
-| [pg-migrations/multi-region.md](references/pg-migrations/multi-region.md)         | Multi-region, active-active, or HA questions                                      | Architecture, geographic partitioning                                       |
+| Reference                                                                         | When to Load                                                                      | Contains                                                                                |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [pg-migrations/type-mapping.md](references/pg-migrations/type-mapping.md)         | MUST load for DSQL NUMERIC or PG type questions                                   | C collation rules, NUMERIC(p,s), JSON/JSONB                                             |
+| [pg-migrations/index-conversion.md](references/pg-migrations/index-conversion.md) | MUST load for any index conversion or index support question                      | GIN/GiST/BRIN → btree, operator class removal, partial + expression indexes, sort order |
+| [pg-migrations/schema-objects.md](references/pg-migrations/schema-objects.md)     | MUST load for ENUM, materialized views, extensions, multi-schema, CREATE FUNCTION | ENUM → CHECK, views, role/IAM mapping, LANGUAGE sql functions                           |
+| [pg-migrations/multi-region.md](references/pg-migrations/multi-region.md)         | Multi-region, active-active, or HA questions                                      | Architecture, geographic partitioning                                                   |
 
 ### ORM Guides:
 
@@ -153,12 +154,12 @@ defaults that may change — when a user's decision depends on an exact limit, v
 | Max connections per cluster           | 10,000        | `aurora dsql connection limits`    |
 | 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 indexes per table                 | 24 incl. PK   | `aurora dsql index limits`         |
 | Max columns per index                 | 8             | `aurora dsql index limits`         |
 | IDENTITY/SEQUENCE CACHE values        | 1 or >= 65536 | `aurora dsql sequence cache`       |
 | Supported column data types           | See docs      | `aurora dsql supported data types` |
 
-**When to verify:** Before recommending batch sizes, connection pool settings, or schema designs where hitting a limit would cause failures; any time the exact number can affect user decision.
+**When to verify:** Before recommending batch sizes, connection pool settings, or schema designs where hitting a limit would cause failures; any time the exact number can affect user decision. For the full limit set with each SQLSTATE and its exact error message, see [limits-and-error-codes.md](references/limits-and-error-codes.md); where it marks a value observed and the docs differ, use the observed value.
 
 **Fallback:** If `awsknowledge` is unavailable, use the defaults above and flag that limits should be verified against [DSQL documentation](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/).
 
@@ -287,10 +288,9 @@ MUST load [system-diagnostics/workflow.md](references/system-diagnostics/workflo
 
 - **`awsknowledge` returns no results:** Use the default limits in the table above and note that limits should be verified against [DSQL documentation](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/).
 - **`dsql_lint` unavailable or timing out:** See the Error Handling section of [dsql-lint.md](references/dsql-lint.md). Do not silently skip validation — inform the user and require explicit confirmation before proceeding with manual rules from [development-guide.md](references/development-guide.md).
-- **OCC serialization error:** Retry the transaction. If persistent, check for hot-key contention — see [troubleshooting.md](references/troubleshooting.md).
-- **Foreign key violation (`23503`):** Correct the relationship or referential action; **MUST NOT**
-  send it through the `40001` retry loop — see [troubleshooting.md](references/troubleshooting.md).
-- **Transaction exceeds limits:** Split write batches to stay under 3,000 row modifications and 10 MiB; locked-row primary keys count toward the size limit — see [batched-migration.md](references/ddl-migrations/batched-migration.md).
+- **OCC serialization error (`40001`):** Retry with backoff, and keep `(OC001)` in the loop too — see [occ-retry-patterns.md](references/occ-retry-patterns.md).
+- **Foreign key violation (`23503`):** Correct the relationship or referential action; **MUST NOT** send it through the `40001` retry loop — see [troubleshooting.md](references/troubleshooting.md).
+- **Transaction exceeds limits:** Split batches under 3,000 rows and 10 MiB; size is checked at `COMMIT` — see [limits-and-error-codes.md](references/limits-and-error-codes.md#exceeded-limits) to size them and [batched-migration.md](references/ddl-migrations/batched-migration.md) for the pattern.
 - **Token expiration mid-operation:** Generate a fresh IAM token — see [authentication-guide.md](references/auth/authentication-guide.md). See [troubleshooting.md](references/troubleshooting.md) for other issues.
 
 ## Additional Resources

@@ -45,7 +45,7 @@ Part of [DSQL Development Guide](../development-guide.md).
 **Best practices:**
 
 - Keep authentication tokens in memory only; discard after use
-- Regenerate token on connection errors
+- Regenerate the token only on a `Signature expired` hint; otherwise a fresh token will not help — see [troubleshooting.md](../troubleshooting.md#connection-and-authorization)
 - Monitor token generation failures
 - Set connection timeouts appropriately
 

@@ -72,7 +72,7 @@ effortless scaling, multi-region viability, among other advantages.
 - REQUIRED: **at most one DDL statement** per operation
 - ALWAYS separate schema (DDL) and data (DML) changes
 - MUST use **`CREATE INDEX ASYNC`:** No synchronous creation (verify limits via `awsknowledge`: `aurora dsql index limits`)
-  - MAXIMUM: **24 indexes per table**
+  - MAXIMUM: **24 indexes per table**, including the primary key ([details](limits-and-error-codes.md#exceeded-limits))
   - MAXIMUM: **8 columns per index**
   - **MUST** verify index is ready before relying on it: `SELECT indisvalid FROM pg_index WHERE indexrelid = 'index_name'::regclass` — queries work but skip the index until `indisvalid = true`
 - MUST use **`ALTER TABLE ASYNC ... VALIDATE CONSTRAINT`** for constraint validation: No synchronous validation

@@ -43,13 +43,22 @@ Concrete example (from `dsql_lint(sql="CREATE INDEX idx ON t (c);", fix=true)`):
 
 **Schema notes:**
 
-- `rule` is a snake_case string identifying the rule (e.g., `index_async`, `truncate`, `json_type`, `set_transaction`); `line` is 1-indexed.
+- `rule` is a snake_case string identifying the rule (e.g., `index_async`, `index_sort_direction`, `truncate`, `json_type`, `set_transaction`); `line` is 1-indexed.
 - `fix_result.status` is one of three values: `fixed`, `fixed_with_warning`, or `unfixable`. Always check this field — `fix_result` is present for every diagnostic when `fix=true`.
 - `fix_result.detail` is present for `fixed` and `fixed_with_warning`; absent for `unfixable`.
 - `fixed_sql` contains rewritten SQL when the linter produces a rewrite. Do not assume it is present
   when no rewrite is needed. Presence of `fixed_sql` does NOT mean the SQL is safe to execute —
   check every diagnostic first.
 - `summary.errors` counts `unfixable` diagnostics; `summary.warnings` counts `fixed_with_warning`; `summary.fixed` counts `fixed`.
+- **Do not gate a pipeline on any one counter.** Severity is derived from `fix_result.status`, so the
+  same rule can land in different counters depending on the input: `index_sort_direction` reports
+  `fixed_with_warning` for `DESC` but a silent `fixed` for `ASC`, even though DSQL rejects both. A
+  check on `errors == 0` or `warnings == 0` passes SQL that was rewritten underneath it. Check
+  `len(diagnostics)` instead — but zero means no lint rule fired, not that DSQL accepts the SQL:
+  operator classes pass with no diagnostic and are rejected
+  ([index-conversion.md](pg-migrations/index-conversion.md)), while valid `BEGIN ATOMIC` bodies
+  raise a `parse_error` (see [Error Handling](#error-handling)). Do not compare `fixed_sql` to
+  the input; it can match while an `unfixable` diagnostic is present.
 - `statement_preview` is the linter's pointer to the offending statement — useful when presenting diagnostics to the user.
 
 ---

@@ -32,7 +32,7 @@ Both `JSONB` and `JSON` are valid; pick by access pattern (see Schema Design Rul
 
 ## Schema Design: Index Creation
 
-MUST use `CREATE INDEX ASYNC` (max 24 indexes/table, 8 columns/index — verify via `awsknowledge`: `aurora dsql index limits`). Source: [aurora-dsql-samples/java/liquibase](https://github.com/aws-samples/aurora-dsql-samples/tree/main/java/liquibase)
+MUST use `CREATE INDEX ASYNC` (max 24 indexes/table including the primary key, 8 columns/index — verify via `awsknowledge`: `aurora dsql index limits`). Source: [aurora-dsql-samples/java/liquibase](https://github.com/aws-samples/aurora-dsql-samples/tree/main/java/liquibase)
 
 ```sql
 CREATE INDEX ASYNC idx_owner_city ON owner(city);