docs(dsql): require official Flyway module

plugins/databases-on-aws/skills/dsql/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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, FK replacement code generation, OCC retry patterns, ORM migration (Django/EF Core/Hibernate/Rails), 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, FK replacement code generation, OCC retry patterns, Flyway and ORM migration (Django/EF Core/Hibernate/Rails), 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 Flyway, flyway-database-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
+  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, flyway, 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
 ---
 
 # Amazon Aurora DSQL Skill
@@ -38,12 +38,13 @@ Load these files as needed for detailed guidance:
 
 ### DDL Migrations:
 
-| Reference                                                                                     | When to Load                                                 | Contains                                |
-| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------- |
-| [ddl-migrations/overview.md](references/ddl-migrations/overview.md)                           | MUST load for DROP COLUMN, ALTER TYPE, DROP CONSTRAINT       | Table recreation pattern, verify & swap |
-| [ddl-migrations/column-operations.md](references/ddl-migrations/column-operations.md)         | DROP COLUMN, ALTER TYPE, SET/DROP NOT NULL/DEFAULT           | Column-level migration patterns         |
-| [ddl-migrations/constraint-operations.md](references/ddl-migrations/constraint-operations.md) | ADD/DROP CONSTRAINT, VALIDATE CONSTRAINT, MODIFY PRIMARY KEY | Constraint and structural changes       |
-| [ddl-migrations/batched-migration.md](references/ddl-migrations/batched-migration.md)         | Tables exceeding 3,000 rows                                  | Batching patterns, progress tracking    |
+| Reference                                                                                     | When to Load                                                 | Contains                                      |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
+| [ddl-migrations/overview.md](references/ddl-migrations/overview.md)                           | MUST load for DROP COLUMN, ALTER TYPE, DROP CONSTRAINT       | Table recreation pattern, verify & swap       |
+| [ddl-migrations/column-operations.md](references/ddl-migrations/column-operations.md)         | DROP COLUMN, ALTER TYPE, SET/DROP NOT NULL/DEFAULT           | Column-level migration patterns               |
+| [ddl-migrations/constraint-operations.md](references/ddl-migrations/constraint-operations.md) | ADD/DROP CONSTRAINT, VALIDATE CONSTRAINT, MODIFY PRIMARY KEY | Constraint and structural changes             |
+| [ddl-migrations/batched-migration.md](references/ddl-migrations/batched-migration.md)         | Tables exceeding 3,000 rows                                  | Batching patterns, progress tracking          |
+| [flyway.md](references/flyway.md)                                                             | MUST load for Flyway setup, adapter choice, or migration     | Official module, deprecated adapter migration |
 
 ### MySQL Migrations:
 

plugins/databases-on-aws/skills/dsql/references/flyway.md

@@ -0,0 +1,43 @@
+# Flyway on Aurora DSQL
+
+Always use Flyway's official Aurora DSQL community module,
+`org.flywaydb:flyway-database-dsql`, with a release compatible with the Flyway runtime.
+
+MUST NOT select or recommend `software.amazon.dsql:aurora-dsql-flyway-support`. It is deprecated.
+When an existing installation uses it, direct the user to migrate to the official module through
+the tested dependency swap below.
+
+Verify that the selected official module version resolves from the user's configured artifact
+repository and check its declared Flyway compatibility. Do not use an unreleased commit or
+snapshot, and do not change production dependencies until the official replacement is available
+in the user's environment.
+
+## Migrate an Existing Installation
+
+1. Test the change outside production.
+2. Record the current Flyway, PostgreSQL module, DSQL JDBC connector, and adapter versions.
+3. Replace `software.amazon.dsql:aurora-dsql-flyway-support` with a published
+   `org.flywaydb:flyway-database-dsql` version compatible with the Flyway runtime.
+4. Keep the existing DSQL JDBC URL, migration files, schema-history table, and `flyway.dsql.*`
+   configuration. Keep the Aurora DSQL JDBC connector on the runtime classpath when using
+   `jdbc:aws-dsql:postgresql://`.
+5. Run `flyway info` and `flyway validate`.
+6. Run `flyway migrate` only after the existing history and pending migrations look correct.
+
+MUST NOT load both adapters together. Both register Aurora DSQL database support in Flyway, so
+classpath coexistence is not a supported migration strategy.
+
+Before `flyway migrate`, rollback is a dependency-only change. After new migrations execute,
+recover using the application's normal database migration procedure; changing the adapter back
+does not undo applied SQL.
+
+## DSQL Migration Rules
+
+The adapter choice does not change DSQL migration constraints:
+
+- Keep one DDL statement per migration transaction; use a script configuration with
+  `executeInTransaction=false` only when each statement may commit independently.
+- Use `CREATE INDEX ASYNC`.
+- Use `flyway.dsql.occMaxRetries`, `flyway.dsql.occMaxRetryDelaySeconds`, and
+  `flyway.dsql.awaitAsyncIndexes` only after checking the selected release's documentation.
+- Use `baselineOnMigrate=true` instead of the standalone `flyway baseline` command.

tools/evals/databases-on-aws/dsql/evals.json

@@ -198,6 +198,21 @@
         "Routes the query to Workflow 9 (EXPLAIN ANALYZE / query plan explainability) to establish the actual plan and root cause, and does not recommend index or schema changes from AAS data alone"
       ],
       "llm_judge": true
+    },
+    {
+      "id": 17,
+      "prompt": "We already run Aurora DSQL migrations with `software.amazon.dsql:aurora-dsql-flyway-support`. Should we keep using it or add the official `flyway-database-dsql` module alongside it? Give me the safest migration path without breaking our existing schema history.",
+      "expected_output": "Selects the official flyway-database-dsql module, identifies the AWS adapter as deprecated, directs existing users to migrate through a tested dependency swap, never loads both adapters together, and preserves existing migration state.",
+      "files": [],
+      "expectations": [
+        "Always recommends a published org.flywaydb:flyway-database-dsql release compatible with the user's Flyway runtime",
+        "Identifies software.amazon.dsql:aurora-dsql-flyway-support as deprecated and directs existing users to migrate away from it",
+        "Does NOT select or recommend the deprecated AWS adapter as the target state",
+        "Says to replace the AWS adapter with org.flywaydb:flyway-database-dsql and never load both in one Flyway runtime",
+        "Preserves the existing JDBC URL, migration files, schema-history table, and flyway.dsql.* configuration during the dependency swap",
+        "Recommends testing outside production and running flyway info and flyway validate before flyway migrate"
+      ],
+      "llm_judge": true
     }
   ]
 }