awslabs
diff --git a/‎mise.toml‎
Lines changed: 1 addition & 1 deletion b/‎mise.toml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎plugins/databases-on-aws/skills/dsql/SKILL.md‎
Lines changed: 36 additions & 9 deletions b/‎plugins/databases-on-aws/skills/dsql/SKILL.md‎
Lines changed: 36 additions & 9 deletions
diff --git a/‎plugins/databases-on-aws/skills/dsql/references/auth/authentication-guide.md‎
Lines changed: 4 additions & 0 deletions b/‎plugins/databases-on-aws/skills/dsql/references/auth/authentication-guide.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎plugins/databases-on-aws/skills/dsql/references/query-plan/catalog-queries.md‎
Lines changed: 145 additions & 0 deletions b/‎plugins/databases-on-aws/skills/dsql/references/query-plan/catalog-queries.md‎
Lines changed: 145 additions & 0 deletions
@@ -106,7 +106,7 @@ run = "uv run tools/init-skill.py"
 [tasks."security:bandit"]
 description = "Run Bandit"
 run = [
-  "bandit -r ."
+  "bandit -r . -x ./.tmp,./node_modules",
 ]
 
 [tasks."security:semgrep"]
 
@@ -1,6 +1,6 @@
 ---
 name: dsql
-description: "Build with Aurora DSQL — manage schemas, execute queries, handle migrations, and develop applications with a serverless, distributed SQL database. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL migration, and DDL operations. Triggers on phrases like: DSQL, Aurora DSQL, create DSQL table, DSQL schema, migrate to DSQL, distributed SQL database, serverless PostgreSQL-compatible database."
+description: "Build with Aurora DSQL — manage schemas, execute queries, handle migrations, diagnose query plans, and develop applications with a serverless, distributed SQL database. Covers IAM auth, multi-tenant patterns, MySQL-to-DSQL migration, DDL operations, and query plan explainability. Triggers on phrases like: DSQL, Aurora DSQL, create DSQL table, DSQL schema, migrate to DSQL, distributed SQL database, serverless PostgreSQL-compatible database, DSQL query plan, DSQL EXPLAIN ANALYZE, why is my DSQL query slow."
 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
@@ -109,6 +109,11 @@ sampled in [.mcp.json](../../.mcp.json)
 **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
+
 ---
 
 ## MCP Tools Available
@@ -156,8 +161,6 @@ the exact number doesn't affect the user's decision.
 **Fallback:** If `awsknowledge` 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), psql connection, and bulk data loading from local/s3 csv/tsv/parquet files.
@@ -188,8 +191,7 @@ Validate inputs carefully (no parameterized queries available)
 Use transact tool with list of SQL statements
 Follow one-DDL-per-transaction rule
 Always use CREATE INDEX ASYNC in separate transaction
-ALTER COLUMN TYPE, DROP COLUMN, DROP CONSTRAINT are NOT supported directly
-  → These require the Table Recreation Pattern (see Workflow 6)
+ALTER COLUMN TYPE, DROP COLUMN, DROP CONSTRAINT → Table Recreation Pattern (Workflow 6)
 ```
 
 ---
@@ -250,16 +252,42 @@ MUST load [ddl-migrations/overview.md](references/ddl-migrations/overview.md) be
 
 MUST load [mysql-migrations/type-mapping.md](references/mysql-migrations/type-mapping.md) for type mappings, feature alternatives, and migration steps.
 
+### Workflow 8: Query Plan Explainability
+
+Explains why the DSQL optimizer chose a particular plan. Triggered by slow queries, high DPU, unexpected Full Scans, or plans the user doesn't understand. **REQUIRES a structured Markdown diagnostic report is the deliverable** beyond conversation — run the workflow end-to-end before answering. Use the `aurora-dsql` MCP when connected; fall back to raw `psql` with a generated IAM token (see the fallback block below) otherwise.
+
+**Phase 0 — Load reference material.** Read all four before starting — each has content later phases need verbatim (node-type math, exact catalog SQL, the `>30s` skip protocol, required report elements):
+
+1. [query-plan/plan-interpretation.md](references/query-plan/plan-interpretation.md) — node types, duration math, anomalous values
+2. [query-plan/catalog-queries.md](references/query-plan/catalog-queries.md) — pg_class / pg_stats / pg_indexes SQL
+3. [query-plan/guc-experiments.md](references/query-plan/guc-experiments.md) — GUC procedures and `>30s` skip protocol
+4. [query-plan/report-format.md](references/query-plan/report-format.md) — required report structure
+
+**Phase 1 — Capture the plan.** **ALWAYS** run `readonly_query("EXPLAIN ANALYZE VERBOSE …")` on the user's query verbatim (SELECT form) — **ALWAYS** capture a fresh plan from the cluster, even when the user describes the plan or reports an anomaly. **MAY** leverage `get_schema` or `information_schema` for schema sanity checks. When EXPLAIN errors (`relation does not exist`, `column does not exist`), **MUST** report the error verbatim — **MUST NOT** invent DSQL-specific semantics (e.g., case sensitivity, identifier quoting) as the root cause. Extract Query ID, Planning Time, Execution Time, DPU Estimate. **SELECT** runs as-is. **UPDATE/DELETE** rewrite to the equivalent SELECT (same join chain + WHERE) — the optimizer picks the same plan shape. **INSERT**, pl/pgsql, DO blocks, and functions **MUST** be rejected. **MUST NOT** use `transact --allow-writes` for plan capture; it bypasses MCP safety.
+
+**Phase 2 — Gather evidence.** Using SQL from `catalog-queries.md`, query `pg_class`, `pg_stats`, `pg_indexes`, `COUNT(*)`, `COUNT(DISTINCT)`. Classify estimation errors per `plan-interpretation.md` (2x–5x minor, 5x–50x significant, 50x+ severe). Detect correlated predicates and data skew.
+
+**Phase 3 — Experiment (conditional).** ≤30s: run GUC experiments per `guc-experiments.md` (default + merge-join-only) plus optional redundant-predicate test. >30s: skip experiments, include the manual GUC testing SQL verbatim in the report, and do not re-run for redundant-predicate testing. Anomalous values (impossible row counts): confirm query results are correct despite the anomalous EXPLAIN, flag as a potential DSQL bug, and produce the Support Request Template from `report-format.md`.
+
+**Phase 4 — Produce the report, invite reassessment.** Produce the full diagnostic report per the "Required Elements Checklist" in [query-plan/report-format.md](references/query-plan/report-format.md) — structure is non-negotiable. End with the "Next Steps" block from that reference so the user can ask for a reassessment after applying a recommendation. When the user says "reassess" (or equivalent), re-run Phase 1–2 and **append an "Addendum: After-Change Performance"** to the original report (before/after table, match against expected impact) rather than producing a new report.
+
+**psql fallback (MCP unavailable).** Pipe statements into `psql` via heredoc and check `$?`; report failures without proceeding on partial evidence:
+
+```bash
+TOKEN=$(aws dsql generate-db-connect-admin-auth-token --hostname "$HOST" --region "$REGION")
+PGPASSWORD="$TOKEN" psql "host=$HOST port=5432 user=admin dbname=postgres sslmode=require" <<<"EXPLAIN ANALYZE VERBOSE <sql>;"
+```
+
+**Safety.** Plan capture uses `readonly_query` exclusively — it rejects INSERT/UPDATE/DELETE/DDL at the MCP layer. Rewrite DML to SELECT (Phase 1) rather than asking `transact --allow-writes` to run it; write-mode `transact` bypasses all MCP safety checks. **MUST NOT** run arbitrary DDL/DML or pl/pgsql.
+
 ---
 
 ## Error Scenarios
 
-- **MCP server unavailable:** Fall back to CLI scripts ([scripts/](../../scripts/)) or direct psql. Note the limitation to the user.
 - **`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/).
 - **OCC serialization error:** Retry the transaction. If persistent, check for hot-key contention — see [troubleshooting.md](references/troubleshooting.md).
 - **Transaction exceeds limits:** Split into batches under 3,000 rows — see [batched-migration.md](references/ddl-migrations/batched-migration.md).
-- **Token expiration mid-operation:** Generate a fresh IAM token and reconnect — see [authentication-guide.md](references/auth/authentication-guide.md).
-- See [troubleshooting.md](references/troubleshooting.md) for other issues.
+- **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.
 
 ---
 
@@ -268,5 +296,4 @@ MUST load [mysql-migrations/type-mapping.md](references/mysql-migrations/type-ma
 - [Aurora DSQL Documentation](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/)
 - [Code Samples Repository](https://github.com/aws-samples/aurora-dsql-samples)
 - [PostgreSQL Compatibility](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility.html)
-- [IAM Authentication Guide](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html)
 - [CloudFormation Resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dsql-cluster.html)
@@ -147,3 +147,7 @@ For production applications:
 
 For complete role setup instructions, schema separation patterns, and IAM configuration,
 see [access-control.md](../access-control.md).
+
+## Additional Resources
+
+- [IAM Authentication Guide (AWS documentation)](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html)
@@ -0,0 +1,145 @@
+# Catalog Queries Reference
+
+Exact SQL for interrogating optimizer statistics and actual cardinalities against the DSQL cluster.
+
+## Table of Contents
+
+1. [Table-Level Statistics (pg_class)](#table-level-statistics)
+2. [Column Statistics (pg_stats)](#column-statistics)
+3. [Index Definitions](#index-definitions)
+4. [Actual Row Counts](#actual-row-counts)
+5. [Actual Distinct Counts](#actual-distinct-counts)
+6. [Value Distribution Analysis](#value-distribution-analysis)
+
+---
+
+## Table-Level Statistics
+
+Retrieve optimizer's view of table size for all referenced tables:
+
+```sql
+SELECT
+  schemaname,
+  relname,
+  reltuples::bigint AS estimated_rows,
+  relpages
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE n.nspname = '{schema}'
+  AND c.relname IN ('{table1}', '{table2}', '{table3}');
+```
+
+Compare `reltuples` against actual `COUNT(*)`. A divergence >20% on the table-stats snapshot indicates stale `reltuples` requiring `ANALYZE`. This is distinct from the row-estimate-vs-actual error thresholds used for plan findings (see plan-interpretation.md: 2x–5x minor, 5x–50x significant, 50x+ severe).
+
+## Column Statistics
+
+Retrieve statistics for columns involved in joins, WHERE clauses, and estimation errors:
+
+```sql
+SELECT
+  tablename,
+  attname,
+  null_frac,
+  n_distinct,
+  most_common_vals,
+  most_common_freqs,
+  histogram_bounds,
+  correlation
+FROM pg_stats
+WHERE schemaname = '{schema}'
+  AND tablename = '{table}'
+  AND attname IN ('{col1}', '{col2}');
+```
+
+**Key fields:**
+
+| Field               | Use                                                    |
+| ------------------- | ------------------------------------------------------ |
+| `n_distinct`        | Negative = fraction of rows; Positive = absolute count |
+| `most_common_vals`  | Values the optimizer considers frequent                |
+| `most_common_freqs` | Corresponding frequencies (sum < 1.0)                  |
+| `histogram_bounds`  | Equal-frequency bucket boundaries for non-MCV values   |
+| `correlation`       | Physical row order correlation (-1 to 1)               |
+
+## Index Definitions
+
+Retrieve existing indexes on referenced tables. DSQL does not populate the cumulative `pg_stat_user_indexes` counters (`idx_scan`, `idx_tup_read`, `idx_tup_fetch`) that standard PostgreSQL exposes — infer index usage from the EXPLAIN plan instead.
+
+```sql
+SELECT
+  tablename,
+  indexname,
+  indexdef
+FROM pg_indexes
+WHERE schemaname = '{schema}'
+  AND tablename IN ('{table1}', '{table2}', '{table3}')
+ORDER BY tablename, indexname;
+```
+
+## Actual Row Counts
+
+Retrieve ground-truth row counts for comparison against `pg_class.reltuples`:
+
+```sql
+SELECT COUNT(*) AS actual_rows FROM {schema}.{table};
+```
+
+Run for each referenced table. Present results as:
+
+| Table  | pg_class.reltuples | Actual COUNT(*) | Difference         |
+| ------ | ------------------ | --------------- | ------------------ |
+| table1 | N                  | M               | X% over/undercount |
+
+## Actual Distinct Counts
+
+Retrieve actual distinct values for columns in joins and WHERE predicates:
+
+```sql
+SELECT COUNT(DISTINCT {column}) AS distinct_count FROM {schema}.{table};
+```
+
+Compare against `pg_stats.n_distinct`:
+
+- If `n_distinct` is positive: compare directly
+- If `n_distinct` is negative: multiply absolute value by actual row count to get estimated distinct count
+
+## Value Distribution Analysis
+
+For columns with suspected data skew, retrieve the actual top-N value frequencies:
+
+```sql
+SELECT
+  {column},
+  COUNT(*) AS freq,
+  ROUND(COUNT(*)::numeric / (SELECT COUNT(*) FROM {schema}.{table}), 5) AS fraction
+FROM {schema}.{table}
+GROUP BY {column}
+ORDER BY freq DESC
+LIMIT 20;
+```
+
+Compare results against `most_common_vals` and `most_common_freqs` from pg_stats. Flag:
+
+- Values present in data but missing from `most_common_vals`
+- Values whose actual frequency differs >2x from `most_common_freqs`
+- Skewed distributions where top values account for >50% of rows
+
+### Correlated Predicate Verification
+
+To verify predicate correlation, measure the actual combined selectivity:
+
+```sql
+SELECT COUNT(*) AS combined_count
+FROM {schema}.{table}
+WHERE {predicate1} AND {predicate2};
+```
+
+Then compare against the independence assumption:
+
+```
+Expected (independent) = (count_pred1 / total_rows) × (count_pred2 / total_rows) × total_rows
+Actual = combined_count
+Error = actual / expected
+```
+
+An error >3x indicates significant predicate correlation.
Original file line number	Diff line number	Diff line change
`@@ -106,7 +106,7 @@ run = "uv run tools/init-skill.py"`
`106`	`106`	`[tasks."security:bandit"]`
`107`	`107`	`description = "Run Bandit"`
`108`	`108`	`run = [`
`109`		`- "bandit -r ."`
	`109`	`+ "bandit -r . -x ./.tmp,./node_modules",`
`110`	`110`	`]`
`111`	`111`
`112`	`112`	`[tasks."security:semgrep"]`