fix(dsql): address merge-blocking review findings #1-#4

- #1: Strip surrounding quotes from all placeholders in catalog-queries
  so safe_query helpers (which emit their own quotes) don't double-quote.
  Add worked safe_query.build() example to preamble.
- #2: DP threshold changed from 10 to 8 (validated: SHOW
  join_collapse_limit = 8 on live DSQL). Agent now instructed to SHOW
  the value rather than hardcoding.
- #3: Remove pg_stat_user_tables.last_analyze cross-check (DSQL never
  populates it). Guard reltuples with GREATEST(..., 0) for the -1
  sentinel on never-analyzed tables.
- #4: Fix '11 generic' to '10 generic' in SKILL.md reference table.

Author: Morlej

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

@@ -84,7 +84,7 @@ Load these files as needed for detailed guidance:
 | [query-plan/catalog-queries.md](references/query-plan/catalog-queries.md)                           | MUST load at Workflow 9 Phase 0                       | `pg_class`/`pg_stats`/`pg_indexes` SQL, correlated-predicate verification |
 | [query-plan/guc-experiments.md](references/query-plan/guc-experiments.md)                           | MUST load at Workflow 9 Phase 0                       | GUC experiment procedures, 30-second skip protocol                        |
 | [query-plan/report-format.md](references/query-plan/report-format.md)                               | MUST load at Workflow 9 Phase 0                       | Required report structure, element checklist, support request template    |
-| [query-plan/query-rewrites-generic.md](references/query-plan/query-rewrites-generic.md)             | SHOULD load at Phase 0; sub-files on-demand           | Index of 11 generic rewrite patterns                                      |
+| [query-plan/query-rewrites-generic.md](references/query-plan/query-rewrites-generic.md)             | SHOULD load at Phase 0; sub-files on-demand           | Index of 10 generic rewrite patterns                                      |
 | [query-plan/query-rewrites-dsql-specific.md](references/query-plan/query-rewrites-dsql-specific.md) | SHOULD load at Phase 0; sub-files on-demand           | Index of DSQL-specific rewrite patterns                                   |
 
 ---

plugins/databases-on-aws/skills/dsql/references/query-plan/catalog-queries.md

@@ -2,10 +2,22 @@
 
 Exact SQL for interrogating optimizer statistics and actual cardinalities against the DSQL cluster.
 
-**Placeholder substitution:** All queries in this file use `'{...}'` placeholders. MUST substitute via `safe_query.build()` — see input-validation.md. Use the correct helper per position:
+**Placeholder substitution:** All queries in this file use `{...}` placeholders. MUST substitute via `safe_query.build()` — see input-validation.md. Use the correct helper per position:
 
 - **Identifier positions** (FROM clause, GROUP BY, column aliases): `ident()` → emits `"value"`
-- **String-literal positions** (WHERE `= '{schema}'`, `IN ('{table}')`, equality comparisons against catalog columns): `allow()` or `regex()` → emits `'value'`
+- **String-literal positions** (WHERE `= {schema}`, `IN ({table})`, equality comparisons against catalog columns): `allow()` or `regex()` → emits `'value'`
+
+Worked example:
+
+```python
+safe_query.build(
+    "SELECT reltuples FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace "
+    "WHERE n.nspname = {schema} AND c.relname IN ({t1}, {t2})",
+    schema=regex(r"^[a-z_]+$", user_schema),
+    t1=regex(r"^[a-z_]+$", table1),
+    t2=regex(r"^[a-z_]+$", table2),
+)
+```
 
 ## Table of Contents
 
@@ -33,8 +45,8 @@ SELECT
   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}');
+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).
@@ -54,9 +66,9 @@ SELECT
   histogram_bounds,
   correlation
 FROM pg_stats
-WHERE schemaname = '{schema}'
-  AND tablename = '{table}'
-  AND attname IN ('{col1}', '{col2}');
+WHERE schemaname = {schema}
+  AND tablename = {table}
+  AND attname IN ({col1}, {col2});
 ```
 
 **Key fields:**
@@ -79,8 +91,8 @@ SELECT
   indexname,
   indexdef
 FROM pg_indexes
-WHERE schemaname = '{schema}'
-  AND tablename IN ('{table1}', '{table2}', '{table3}')
+WHERE schemaname = {schema}
+  AND tablename IN ({table1}, {table2}, {table3})
 ORDER BY tablename, indexname;
 ```
 
@@ -123,9 +135,9 @@ SELECT
   c.udt_name,
   c.is_nullable
 FROM information_schema.columns c
-WHERE c.table_schema = '{schema}'
-  AND c.table_name IN ('{table1}', '{table2}')
-  AND c.column_name IN ('{col1}', '{col2}');
+WHERE c.table_schema = {schema}
+  AND c.table_name IN ({table1}, {table2})
+  AND c.column_name IN ({col1}, {col2});
 ```
 
 Cross-reference the column type against predicate literals visible in the EXPLAIN output. When the types differ, use the B-Tree Cross-Type Operator Support query below to determine whether the mismatch prevents index usage.
@@ -160,8 +172,8 @@ SELECT EXISTS (
   JOIN pg_type rt ON rt.oid = ao.amoprighttype
   -- 10003 = DSQL B-Tree OID; verify with: SELECT oid FROM pg_am WHERE amname = 'btree_index'
   WHERE ao.amopmethod = 10003
-    AND lt.typname = '{predicate_type}'
-    AND rt.typname = '{column_type}'
+    AND lt.typname = {predicate_type}
+    AND rt.typname = {column_type}
 ) AS index_usable;
 ```
 
@@ -183,8 +195,8 @@ JOIN pg_attribute a ON a.attrelid = ix.indrelid
   AND a.attnum = ANY(ix.indkey)
 JOIN pg_type t ON t.oid = a.atttypid
 JOIN pg_namespace n ON n.oid = ic.relnamespace
-WHERE n.nspname = '{schema}'
-  AND i.tablename IN ('{table1}', '{table2}')
+WHERE n.nspname = {schema}
+  AND i.tablename IN ({table1}, {table2})
 ORDER BY i.tablename, i.indexname, a.attnum;
 ```
 

plugins/databases-on-aws/skills/dsql/references/query-plan/query-rewrites/reltuples-estimate.md

@@ -4,7 +4,7 @@ When a query performs `COUNT(*)` on a large table, rewrite to use the `reltuples
 
 **SHOULD apply when:** An approximate count is acceptable and the table is large enough that `COUNT(*)` is prohibitively expensive.
 
-**Staleness warning:** `reltuples` reflects the last `ANALYZE` or autovacuum run. MUST warn the user that the value MAY be stale on write-heavy or recently created tables. SHOULD recommend cross-checking `pg_stat_user_tables.last_analyze` when the count drives a decision.
+**Staleness warning:** `reltuples` reflects the last `ANALYZE` run. MUST warn the user that the value MAY be stale on write-heavy or recently created tables (DSQL does not populate `pg_stat_user_tables.last_analyze`). A value of `-1` means statistics have never been gathered — treat as "unknown" and recommend running `ANALYZE` first.
 
 **SHOULD skip when:** The application requires an exact count.
 
@@ -13,8 +13,8 @@ When a query performs `COUNT(*)` on a large table, rewrite to use the `reltuples
 SELECT COUNT(*) AS exact_count
 FROM big_table;
 
--- Rewritten (DSQL)
-SELECT reltuples::bigint AS estimated_count
+-- Rewritten (DSQL) — GREATEST guards against -1 (never-analyzed)
+SELECT GREATEST(reltuples, 0)::bigint AS estimated_count
 FROM pg_class
 WHERE oid = 'public.big_table'::regclass;
 ```

plugins/databases-on-aws/skills/dsql/references/query-plan/query-rewrites/split-large-joins.md

@@ -1,6 +1,6 @@
 # Rewrite: Split Large Joins for DP Join Ordering (DSQL-Specific)
 
-When a query joins more tables than the optimizer's DP threshold (e.g., 10 joins for Aurora DSQL), rewrite it into multiple subqueries each joining no more tables than the threshold, then join the subquery results.
+When a query joins more tables than the optimizer's DP threshold, rewrite it into multiple subqueries each joining no more tables than the threshold, then join the subquery results. The agent MUST run `SHOW join_collapse_limit;` on the target cluster to determine the actual threshold rather than assuming a fixed value (default is **8** on Aurora DSQL).
 
 This allows the PostgreSQL-based DSQL engine to apply dynamic-programming (DP) join ordering within each smaller block, producing a better overall join plan than a greedy algorithm on many tables.
 
@@ -9,7 +9,7 @@ This allows the PostgreSQL-based DSQL engine to apply dynamic-programming (DP) j
 **SHOULD skip when:** The total table count is at or below the threshold, or splitting would prevent necessary cross-block optimizations.
 
 ```sql
--- Original (11 tables — exceeds DP threshold of 10)
+-- Original (11 tables — exceeds default DP threshold of 8)
 SELECT *
 FROM R1
   JOIN R2 ON R1.id = R2.r1_id
@@ -24,7 +24,7 @@ FROM R1
   JOIN R11 ON R10.id = R11.r10_id
 WHERE Filters;
 
--- Rewritten (DSQL) — split into two CTEs, each ≤ 10 tables
+-- Rewritten (DSQL) — split into two CTEs, each ≤ 8 tables
 WITH
   sub1 AS (
     SELECT R1.id, R6.id AS r6_id, R6.col