fix(databases-on-aws): correct DSQL type guidance, add cluster-lifecycle troubleshooting

Update DSQL skill to reflect current DSQL type support: JSON is a supported
column type (1 MiB, auto-compressed), while JSONB, arrays, and INET remain
runtime-only. Replace the narrow quick-reference type list with a pointer to
the canonical AWS docs and an awsknowledge verify-query row, so the skill
does not drift as DSQL's type surface evolves.

Add troubleshooting entries for the INACTIVE-cluster wake error and the
FailedPrecondition returned when backing up an IDLE/INACTIVE cluster, with a
pointer to the cluster-lifecycle documentation.

Extend the Tier 2 functional eval suite with three new evals covering the
updated behaviors — JSON column storage, array-column rejection, and the
INACTIVE-cluster wake flow — plus the grader clauses they need and an
--eval-ids flag on the runner for targeted subset runs.

Verified against live cluster: JSON accepted as column type; JSONB and TEXT[]
rejected with "datatype not supported"; ::jsonb cast + ->> / @> operators
work as expected.

Co-Authored-By: anwesham-lab <64298192+anwesham-lab@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: anwesham-lab

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

@@ -153,13 +153,11 @@ defaults that may change — when a user's decision depends on an exact limit, v
 | 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`       |
+| 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. No need to verify for general guidance or when
-the exact number doesn't affect the user's 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.
 
-**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/).
+**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/).
 
 ## CLI Scripts Available
 
@@ -208,7 +206,7 @@ ALTER COLUMN TYPE, DROP COLUMN, DROP CONSTRAINT → Table Recreation Pattern (Wo
 - MUST include tenant_id in all tables
 - MUST use `CREATE INDEX ASYNC` exclusively
 - MUST issue each DDL in its own transact call: `transact(["CREATE TABLE ..."])`
-- MUST store arrays/JSON as TEXT
+- MUST store arrays as TEXT; SHOULD store JSON in a `JSON` column
 
 ### Workflow 2: Safe Data Migration
 

plugins/databases-on-aws/skills/dsql/references/development-guide.md

@@ -13,7 +13,8 @@ effortless scaling, multi-region viability, among other advantages.
 - **REQUIRED: Follow DDL Guidelines** - Refer to [DDL Rules](#schema-ddl-rules)
 - **SHALL repeatedly generate fresh tokens** - Refer to [Connection Limits](auth/authentication-guide.md#connection-rules)
 - **ALWAYS use ASYNC indexes** - `CREATE INDEX ASYNC` is mandatory
-- **MUST Serialize arrays/JSON as TEXT** - Store arrays/JSON as TEXT (comma separated, JSON.stringify)
+- **MUST serialize arrays as TEXT** - comma-separated
+- **SHOULD store JSON in a `JSON` column** - cast to `JSONB` at query time for JSONB operators
 - **ALWAYS Batch within row limit** - maintain transaction limits (verify via `awsknowledge`: `aurora dsql transaction limits`)
 - **REQUIRED: Build and sanitize all SQL with `safe_query.build()`** - See [Input Validation](../mcp/tools/input-validation.md#required-pattern)
 - **MUST follow correct Application Layer Patterns** - when multi-tenant isolation or application referential integrity are required; refer to [Application Layer Patterns](#application-layer-patterns)
@@ -53,9 +54,9 @@ effortless scaling, multi-region viability, among other advantages.
 
 ### Schema Design Rules
 
-- MUST use **simple PostgreSQL types:** VARCHAR, TEXT, INTEGER, BOOLEAN, TIMESTAMP
-- MUST store arrays as TEXT (comma-separated is recommended)
-- MUST store JSON objects as TEXT (JSON.stringify)
+- MUST verify column types via `awsknowledge`: `aurora dsql supported data types` or the [DSQL supported data types list](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html)
+- MUST store arrays as TEXT (comma-separated)
+- SHOULD store JSON in a `JSON` column; cast to `JSONB` at query time for JSONB operators
 - ALWAYS include tenant_id in tables for multi-tenant isolation
 - SHOULD create async indexes for tenant_id and common query patterns
 
@@ -124,9 +125,7 @@ UPDATE table SET c = 'default' WHERE c IS NULL;        ← AFTER ADD COLUMN
 
 ### Supported Data Types
 
-```
-VARCHAR, TEXT, INTEGER, DECIMAL, BOOLEAN, TIMESTAMP, UUID
-```
+**MUST** verify column types via `awsknowledge`: `aurora dsql supported data types` or the [DSQL supported data types list](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html). `JSONB`, arrays, and `INET` are [runtime-only](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html#working-with-postgresql-compatibility-query-runtime) — cast at query time.
 
 ### Supported Key
 

plugins/databases-on-aws/skills/dsql/references/examples/data-operations.md

@@ -54,7 +54,7 @@ async function batchInsert(pool, tenantId, items) {
         await client.query(
           `INSERT INTO entities (tenant_id, name, metadata)
           VALUES ($1, $2, $3)`,
-          [tenantId, item.name, JSON.stringify(item.metadata)]
+          [tenantId, item.name, item.metadata]
         );
       }
 
@@ -105,7 +105,7 @@ async function processBatches(pool, tenantId, batches, startIdx, step) {
       for (const item of batch) {
         await client.query(
           'INSERT INTO entities (tenant_id, name, metadata) VALUES ($1, $2, $3)',
-          [tenantId, item.name, JSON.stringify(item.metadata)]
+          [tenantId, item.name, item.metadata]
         );
       }
 

plugins/databases-on-aws/skills/dsql/references/examples/patterns.md

@@ -131,7 +131,7 @@ INSERT INTO distributors VALUES (nextval('order_seq'), 'nothing');
 
 ## Data Serialization
 
-**Pattern:** MUST store arrays and JSON as TEXT (runtime-only types). Per [DSQL docs](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html), cast to JSON at query time.
+**Pattern:** **MUST** store arrays as `TEXT` (comma-separated). **SHOULD** store JSON in a `JSON` column and cast to `JSONB` at query time for JSONB operators. Arrays and `JSONB` are [runtime-only types](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html#working-with-postgresql-compatibility-query-runtime).
 
 ```javascript
 function toTextArray(values) {
@@ -142,32 +142,21 @@ function fromTextArray(textValue) {
   return textValue ? textValue.split(',').map(v => v.trim()) : [];
 }
 
-function toTextJSON(object) {
-  return JSON.stringify(object);
-}
-
-function fromTextJSON(textValue) {
-  if (!textValue) return null;
-  try {
-    return JSON.parse(textValue);
-  } catch (err) {
-    console.warn('Invalid JSON in column:', err.message);
-    return null;
-  }
-}
-
 const categoriesText = toTextArray(['backend', 'api', 'database']);
 await pool.query('INSERT INTO projects (project_id, categories) VALUES ($1, $2)', [projectId, categoriesText]);
 
-const configText = toTextJSON({ theme: 'dark', notifications: true });
-await pool.query('INSERT INTO user_settings (user_id, preferences) VALUES ($1, $2)', [userId, configText]);
+await pool.query(
+  'INSERT INTO user_settings (user_id, preferences) VALUES ($1, $2)',
+  [userId, { theme: 'dark', notifications: true }],
+);
 ```
 
 Query-time operations:
 
 ```sql
-SELECT user_id, preferences::jsonb->>'theme' as theme
-FROM user_settings WHERE preferences::jsonb->>'notifications' = 'true';
+SELECT user_id, preferences::jsonb->>'theme' AS theme
+FROM user_settings
+WHERE preferences::jsonb->>'notifications' = 'true';
 
-SELECT project_id, string_to_array(categories, ',') as category_array FROM projects;
+SELECT project_id, string_to_array(categories, ',') AS category_array FROM projects;
 ```

plugins/databases-on-aws/skills/dsql/references/mysql-migrations/full-example.md

@@ -45,7 +45,7 @@ transact([
      price DECIMAL(10,2) NOT NULL,
      category VARCHAR(255) DEFAULT 'other' CHECK (category IN ('electronics', 'clothing', 'food', 'other')),
      tags TEXT,
-     metadata TEXT,
+     metadata JSON,
      stock INTEGER DEFAULT 0 CHECK (stock >= 0),
      is_active BOOLEAN DEFAULT true,
      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
@@ -70,7 +70,7 @@ transact(["CREATE INDEX ASYNC idx_products_category ON products(tenant_id, categ
 | `MEDIUMTEXT`                  | `TEXT`                                                                                                                                                     |
 | `ENUM(...)`                   | `VARCHAR(255)` with `CHECK` constraint                                                                                                                     |
 | `SET(...)`                    | `TEXT` (comma-separated)                                                                                                                                   |
-| `JSON`                        | `TEXT` (JSON.stringify)                                                                                                                                    |
+| `JSON`                        | `JSON`                                                                                                                                                     |
 | `UNSIGNED`                    | `CHECK (col >= 0)`                                                                                                                                         |
 | `TINYINT(1)`                  | `BOOLEAN`                                                                                                                                                  |
 | `DATETIME`                    | `TIMESTAMP`                                                                                                                                                |
@@ -99,7 +99,6 @@ transact(["CREATE INDEX ASYNC idx_products_category ON products(tenant_id, categ
 - **MUST convert** AUTO_INCREMENT to UUID with gen_random_uuid(), IDENTITY column with `GENERATED AS IDENTITY (CACHE ...)`, or explicit SEQUENCE -- ALWAYS use `GENERATED AS IDENTITY` for auto-incrementing columns (see [AUTO_INCREMENT Migration](ddl-auto-increment.md#auto_increment-migration))
 - **MUST replace** ENUM with VARCHAR and CHECK constraint
 - **MUST replace** SET with TEXT (comma-separated)
-- **MUST replace** JSON columns with TEXT
 - **MUST replace** FOREIGN KEY constraints with application-layer referential integrity
 - **MUST replace** ON UPDATE CURRENT_TIMESTAMP with application-layer updates
 - **MUST convert** all index creation to use CREATE INDEX ASYNC

plugins/databases-on-aws/skills/dsql/references/mysql-migrations/type-mapping.md

@@ -97,7 +97,7 @@ Map MySQL data types to their DSQL equivalents.
 
 | MySQL Type     | DSQL Equivalent                                           | Notes                                                                                                |
 | -------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| JSON           | TEXT                                                      | MUST store as TEXT                                                                                   |
+| JSON           | `JSON`                                                    | Direct equivalent                                                                                    |
 | AUTO_INCREMENT | UUID with gen_random_uuid(), IDENTITY column, or SEQUENCE | See [AUTO_INCREMENT Migration](ddl-auto-increment.md#auto_increment-migration) for all three options |
 
 ---

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

@@ -35,7 +35,7 @@ These guidelines apply when users say "Get started with DSQL" or similar phrases
   - Example:
     - "What column names would you like in this table?"
     - "What is the column name of the primary key?"
-    - "JSON must be serialized. Would you like to stringify the JSON to serialize it as TEXT?"
+    - "Would you like to store this in a `JSON` column, or serialize as TEXT?"
 
 **Examples:**
 
@@ -252,7 +252,9 @@ cargo add aws-sdk-dsql tokio --features full
 - If yes, MUST verify DSQL compatibility:
   - No SERIAL types (use `GENERATED AS IDENTITY` with sequences, or UUID)
   - No foreign keys (implement in application)
-  - No array/JSON column types (serialize as TEXT)
+  - No array column types — serialize as TEXT
+  - JSON uses the `JSON` column type; cast to `JSONB` at query time
+  - Verify column types against the [supported data types list](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html)
   - Reference [`./development-guide.md`](./development-guide.md) for full constraints
 
 **If no schema found:**
@@ -349,7 +351,7 @@ Let them know you're ready to help with more:
 **ALWAYS follow these rules:**
 
 1. **Indexes:** Use `CREATE INDEX ASYNC` - synchronous index creation not supported
-2. **Serialization:** Store arrays/JSON as TEXT (comma-separated or JSON.stringify)
+2. **Serialization:** Store arrays as TEXT (comma-separated); store JSON in a `JSON` column and cast to `JSONB` at query time
 3. **Referential Integrity:** Implement foreign key validation in application code
 4. **DDL Operations:** Execute one DDL per transaction, no mixing with DML
 5. **Transaction Limits:** Maximum 3,000 row modifications, 10 MiB data size per transaction

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

@@ -52,6 +52,18 @@ Before referring to any listed errors, refer to the complete [DSQL troubleshooti
 - Use native TLS libraries (not OpenSSL 1.0.x)
 - Set `server_name_indication` to cluster endpoint in SSL config
 
+## Cluster Lifecycle
+
+See [cluster lifecycle](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/cluster-lifecycle.html) for state definitions and behavior.
+
+### Error: "FATAL: unable to accept connection, waking up cluster, please retry later"
+
+Poll `aws dsql get-cluster --identifier <id> --region <region> --query status --output text` until `ACTIVE`, then retry.
+
+### Error: `FailedPrecondition` when backing up an `IDLE` / `INACTIVE` cluster
+
+Connect to the cluster to wake it, then retry the backup.
+
 ## Incompatibility
 
 When migrating from PostgreSQL, remember DSQL doesn't support:

tools/evals/databases-on-aws/README.md

@@ -68,15 +68,29 @@ python tools/evals/databases-on-aws/dsql/scripts/run_functional_evals.py \
   --verbose
 ```
 
-**What it checks** (5 eval prompts, 20 assertions total):
-
-| Eval                   | Focus                 | Key assertions                                                             |
-| ---------------------- | --------------------- | -------------------------------------------------------------------------- |
-| 1. Transaction limits  | MCP delegation        | Calls `awsknowledge`, cites 3,000 row limit, recommends batching           |
-| 2. Multi-tenant schema | Correctness           | Uses `tenant_id`, `CREATE INDEX ASYNC`, no foreign keys, separate DDL txns |
-| 3. Index limits        | MCP delegation        | Calls `awsknowledge`, cites 24 index limit, suggests alternatives          |
-| 4. Python connection   | Language routing      | Recommends DSQL Python Connector, IAM auth, 15-min token expiry, SSL       |
-| 5. Column type change  | DDL migration routing | Table Recreation Pattern, DROP TABLE warning, batching, user confirmation  |
+Run a subset by ID (e.g., just the new type / lifecycle evals):
+
+```bash
+python tools/evals/databases-on-aws/dsql/scripts/run_functional_evals.py \
+  --evals tools/evals/databases-on-aws/dsql/evals.json \
+  --plugin-dir plugins/databases-on-aws \
+  --output-dir /tmp/dsql-eval-results \
+  --eval-ids 6,7,8 \
+  --verbose
+```
+
+**What it checks** (8 eval prompts, 30 assertions total):
+
+| Eval                      | Focus                 | Key assertions                                                                                     |
+| ------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
+| 1. Transaction limits     | MCP delegation        | Calls `awsknowledge`, cites 3,000 row limit, recommends batching                                   |
+| 2. Multi-tenant schema    | Correctness           | Uses `tenant_id`, `CREATE INDEX ASYNC`, no foreign keys, separate DDL txns                         |
+| 3. Index limits           | MCP delegation        | Calls `awsknowledge`, cites 24 index limit, suggests alternatives                                  |
+| 4. Python connection      | Language routing      | Recommends DSQL Python Connector, IAM auth, 15-min token expiry, SSL                               |
+| 5. Column type change     | DDL migration routing | Table Recreation Pattern, DROP TABLE warning, batching, user confirmation                          |
+| 6. JSON column storage    | Type guidance         | Prefers `JSON` column type, explains `::jsonb` cast, does not claim JSON must be stored as TEXT    |
+| 7. Array storage          | Type guidance         | Flags `TEXT[]` / array column unsupported (runtime-only), recommends TEXT or `JSON` column         |
+| 8. INACTIVE cluster error | Troubleshooting       | Identifies INACTIVE state, uses `aws dsql get-cluster` to poll until `ACTIVE`, retries afterwards  |
 
 ### Tier 3: Safe-Query Enforcement Evals
 

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

@@ -60,6 +60,40 @@
         "Mentions batching the data copy for tables exceeding 3,000 rows",
         "Requires or recommends user confirmation before destructive steps"
       ]
+    },
+    {
+      "id": 6,
+      "prompt": "I need to store a JSON preferences blob per user in my DSQL users table. How should I model that column, and how do I query fields inside it?",
+      "expected_output": "Prefers the JSON column type over TEXT serialization. Explains that JSONB is runtime-only and must be cast (preferences::jsonb->>'key') at query time for JSONB operators.",
+      "files": [],
+      "expectations": [
+        "Prefers or recommends the JSON column type for the preferences blob",
+        "Mentions casting to jsonb at query time for JSONB operators",
+        "Does NOT claim JSON must be stored as TEXT (JSON column is supported in DSQL)"
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "I want to store a tags array per project in DSQL (e.g. ['backend','database','api']). Can I use TEXT[] for that?",
+      "expected_output": "Indicates TEXT[] / array column type is not supported (array is a runtime-only type in DSQL). Recommends storing arrays as TEXT (comma-separated) or inside a JSON column.",
+      "files": [],
+      "expectations": [
+        "Indicates TEXT[] or array column type is not supported in DSQL",
+        "Mentions arrays are runtime-only in DSQL",
+        "Recommends storing arrays as TEXT (comma-separated) or inside a JSON column"
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "My DSQL connection just failed with: FATAL: unable to accept connection, waking up cluster, please retry later. What's happening and what should I do?",
+      "expected_output": "Identifies the cluster as INACTIVE, explains that the first connection triggers the wake. Recommends polling cluster status via aws dsql get-cluster until ACTIVE, then retrying the connection.",
+      "files": [],
+      "expectations": [
+        "Identifies the cluster is in INACTIVE state and waking up",
+        "Mentions aws dsql get-cluster for checking cluster status",
+        "Recommends polling until the cluster reaches ACTIVE state",
+        "Recommends retrying the connection after cluster becomes ACTIVE"
+      ]
     }
   ]
 }