aurora-dsql

Amazon Aurora DSQL

概述

Aurora DSQL 是一种无服务器、兼容 PostgreSQL 的分布式 SQL 数据库。此技能支持通过 psql 脚本和 PostgreSQL 驱动程序直接与数据库交互、管理架构、支持迁移、多租户模式以及查询计划可解释性。

主要功能：

• 使用生成的 IAM 身份验证令牌通过 psql 直接执行查询（参见 scripts/psql-connect.sh）
• 使用 DSQL 约束管理架构（每个事务执行一条 DDL、异步索引）
• 安全迁移数据（列级、约束级、MySQL→DSQL）
• 通过 tenant_id + 参数化 SQL 实现多租户隔离
• 基于 IAM 的身份验证，令牌有效期为 15 分钟
• 诊断慢查询的查询计划（EXPLAIN ANALYZE + GUC 实验）

推荐使用 psql 搭配 aws dsql generate-db-connect-auth-token，建立通过 IAM 身份验证的会话。应用程序代码 SHOULD 使用特定语言的 DSQL Connectors and SDKs。如需查询 AWS 知识（服务文档、AWS API 调用），首选的 MCP 集成方式是 AWS MCP Server。

---

参考文件

根据需要加载以下文件，获取详细指导：

development-guide.md

何时加载： 实施架构变更或数据库操作前，始终加载 内容： 最佳实践、DDL 规则、连接模式、事务限制、数据类型序列化模式、应用层引用完整性说明、安全最佳实践

查询执行：

database-tools.md

何时加载： 需要针对 DSQL 执行临时查询的详细语法和示例时加载。临时查询优先使用 psql（通过 scripts/psql-connect.sh）——直接执行，而不是编写一次性脚本。 内容： 基于 psql 的只读和写入模式、事务语义、输入验证

MCP（AWS 知识 / API）：

mcp-setup.md

何时加载： 配置或推荐 AWS MCP Server，以查询 AWS 知识、访问 AWS API 或为各类助手单独安装时加载。 内容： 何时使用 psql，何时使用 AWS MCP Server、规范 AWS 设置文档的链接、凭证提醒。

mcp-tools.md

何时加载： 调用 AWS MCP Server 工具以验证 DSQL 服务限制、获取文档或执行 AWS API 调用时加载。 内容： 工具范围——知识类（aws___search_documentation、aws___read_documentation、aws___recommend、aws___retrieve_skill、aws___list_regions、aws___get_regional_availability）和 API 类（aws___call_aws、aws___run_script、aws___get_tasks、aws___get_presigned_url）；指向 documentation-tools.md 的链接。

documentation-tools.md

何时加载： 查询 DSQL 服务限制、获取特定 AWS 文档页面，或轮询通过 AWS MCP Server 启动的长时间运行的 AWS API 调用时加载。 内容： AWS 知识工具的详细参数和调用示例。

platforms/ — 各助手的安装说明

何时加载： 在特定编码助手中安装 AWS MCP Server 时加载。 内容： 各助手的入口点详情——claude-code.md、codex.md、gemini.md、kiro.md。

language.md

何时加载： 编写 DSQL 连接代码前必须加载。对于所选驱动，参照链接中的 example_preferred.<ext>——凭记忆编写的连接代码容易偏离规范的 IAM 令牌刷新模式。规范的入口示例（加载 language.md 查看完整的驱动列表以及连接池/TLS/令牌刷新详情）：

• Python：import aurora_dsql_psycopg as dsql → dsql.connect(host, region, user)
• JS（node-postgres）：import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector" → new AuroraDSQLPool({ host, user })
• JS（postgres.js）：import { auroraDSQLPostgres } from "@aws/aurora-dsql-postgresjs-connector" → auroraDSQLPostgres({ host, user })
• Go（pgx）：import "github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"
• Java（JDBC）：software.amazon.dsql:aurora-dsql-jdbc-connector:1.4.0 → jdbc:aws-dsql:postgresql://...

包含内容： 各语言的规范 DSQL 连接器包、驱动选择、框架模式、IAM 身份验证令牌轮换与 TLS 配置，以及 Python / JavaScript / TypeScript / Go / Java / Rust 的连接代码示例。

troubleshooting.md

何时加载： 调试错误或异常行为时加载。遇到 OCC 错误、连接失败或查询结果异常时，应始终查阅。 包含内容： 常见问题、错误消息及解决方案

onboarding.md

何时加载： 用户明确要求“开始使用 DSQL”或类似内容时 包含内容： 面向新用户的交互式分步指南

access-control.md

何时加载： 创建数据库角色、授予权限、为应用设置架构或处理敏感数据时，必须加载。应用始终使用受限角色——创建具有 dsql:DbConnect 的数据库角色。 包含内容： 受限角色设置、IAM 到数据库角色的映射、敏感数据的架构隔离、角色设计模式

身份验证与运维：

auth/authentication-guide.md

何时加载： 处理 IAM 身份验证令牌、密钥、SSL/TLS、连接池或审计日志时，必须加载。 包含内容： 令牌生命周期、密钥存储模式、SSL/TLS 设置、连接池指南、审计日志集成。

auth/connectivity-tools.md

何时加载： 选择驱动/ORM/适配器或规划批量数据加载时加载。 包含内容： 指向 AWS DSQL 规范连接工具页面（驱动、ORM、适配器）和批量加载文档页面的链接。

auth/scaling-guide.md

何时加载： 设计可扩展方案时加载——连接池、批处理优化、避免热点键、标识符选择。 包含内容： 水平扩展策略、连接池大小、批次大小指南、IDENTITY/UUID 权衡、序列缓存规则。

实现示例：

workflow-patterns.md

何时加载： 查找常见多步骤 DSQL 工作流（架构探索、CREATE+INDEX、安全迁移、批量插入、应用层外键检查）的完整示例时加载。 包含内容： 五种规范模式，包含 psql / 驱动代码。

dsql-examples.md

何时加载： 查找具体实现示例时加载。 包含内容： examples/*.md 索引（连接、架构、数据操作、迁移、模式）。

DDL 迁移（模块化）：

ddl-migrations/overview.md

何时加载： 执行 DROP COLUMN、RENAME COLUMN、ALTER COLUMN TYPE 或 DROP CONSTRAINT 时，必须加载 包含内容： 表重建模式概述、事务规则、常见的验证与切换模式

ddl-migrations/column-operations.md

适用场景： 执行 DROP COLUMN、ALTER COLUMN TYPE、SET/DROP NOT NULL、SET/DROP DEFAULT 迁移时加载 内容： 列级变更的分步迁移模式

ddl-migrations/constraint-operations.md

适用场景： 执行 ADD/DROP CONSTRAINT、MODIFY PRIMARY KEY、列拆分/合并迁移时加载 内容： 约束和结构变更的分步迁移模式

ddl-migrations/batched-migration.md

适用场景： 迁移行数超过 3,000 行的表时加载 内容： 基于 OFFSET 和游标的批处理模式、进度跟踪、错误处理

MySQL 迁移（模块化）：

mysql-migrations/type-mapping.md

适用场景： 将 MySQL 架构迁移到 DSQL 时必须加载 内容： MySQL 数据类型映射、功能替代方案、DDL 操作映射

mysql-migrations/ddl-operations.md

适用场景： 将 MySQL DDL 操作转换为对应的 DSQL 操作时加载 内容： ALTER COLUMN、DROP COLUMN、AUTO_INCREMENT、ENUM、SET、FOREIGN KEY 迁移模式

mysql-migrations/full-example.md

适用场景： 将完整的 MySQL 表迁移到 DSQL 时加载 内容： 端到端的 MySQL CREATE TABLE 迁移示例及决策摘要

查询计划可解释性（模块化）：

适用场景： 在工作流 8 的阶段 0 必须加载全部四项：query-plan/plan-interpretation.md、query-plan/catalog-queries.md、query-plan/guc-experiments.md、query-plan/report-format.md 内容： DSQL 节点类型 + 节点耗时计算 + 估算误差范围、pg_class/pg_stats/pg_indexes SQL + 相关谓词验证、GUC 实验流程 + 30 秒跳过协议、必需的报告结构 + 要素检查清单 + 支持请求模板

---

查询执行

使用 psql 和新生成的 IAM 身份验证令牌运行临时 DSQL 查询。随附的 scripts/psql-connect.sh 封装了令牌生成、TLS 配置和 单语句保护——优先使用它，而不要手动编写 psql 调用。

只读：

./scripts/psql-connect.sh --cluster <cluster-id> --command "SELECT * FROM entities LIMIT 10"

写入/DDL（需要 IAM 管理员身份验证令牌）：

./scripts/psql-connect.sh --cluster <cluster-id> --admin --command "CREATE INDEX ASYNC ..."

架构发现： 没有专用的 list_tables 辅助工具——请使用 information_schema：

SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';

详细用法和示例请参阅 database-tools.md。

通过 AWS MCP Server 获取 AWS 知识（可选）

连接到 AWS MCP Server 后， 其 aws___search_documentation 和 aws___read_documentation 工具可用于验证 DSQL 服务 限制，再向用户提供建议。以下数值限制均为默认值，可能会发生变化——当用户的决策取决于 某项限制的确切数值时，请先进行验证：

限制	默认值	验证查询
每笔事务修改的最大行数	3,000	aurora dsql transaction limits
每笔写入事务修改的最大数据量	10 MiB	aurora dsql transaction limits
最大事务时长	5 分钟	aurora dsql transaction limits
每个集群的最大连接数	10,000	aurora dsql connection limits
IAM 身份验证令牌有效期	15 分钟	aurora dsql authentication token
最大连接时长	60 分钟	aurora dsql connection limits
每张表的最大索引数	24	aurora dsql index limits
每个索引的最大列数	8	aurora dsql index limits
IDENTITY/SEQUENCE CACHE 值	1 或 >= 65536	aurora dsql sequence cache

何时验证： 在建议批量大小、连接池设置或架构设计之前，如果触及限制会导致失败，就应进行验证。一般性建议无需验证；如果确切数值不会影响用户的决策，也无需验证。

备用方案： 如果 AWS MCP Server 不可用，请使用以上默认值，并告知用户应对照 DSQL 文档验证限制。

可用的 CLI 脚本

scripts/ 中的 Bash 脚本可用于集群管理（创建、删除、列出、查看集群信息）和 psql 连接。用法请参阅 references/scripts-guide.md。批量加载数据请参阅 将数据加载到 Aurora DSQL。

务必优先使用 scripts/create-cluster.sh。该脚本通过单次原子性 CreateCluster 调用创建集群，并在调用中嵌入标签——与 AWS DSQL API 的形式一致，且输出易于解读。

任务	脚本	示例
创建带标签的集群	scripts/create-cluster.sh	./scripts/create-cluster.sh --created-by <model-id> --tags Environment=eval,Project=dsql-skill-eval
列出集群	scripts/list-clusters.sh	./scripts/list-clusters.sh --region us-east-1
查看集群信息	scripts/cluster-info.sh	./scripts/cluster-info.sh <cluster-id>
通过 psql 连接	scripts/psql-connect.sh	./scripts/psql-connect.sh --cluster <id> --command "SELECT 1"

---

快速入门

1. 列出表并探索架构

./scripts/psql-connect.sh --cluster <id> --command "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
./scripts/psql-connect.sh --cluster <id> --command "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_schema = 'public' AND table_name = '<table>' ORDER BY ordinal_position"

2. 查询数据

Use psql-connect.sh (or the language connector in app code) for SELECT queries
Always include tenant_id in WHERE clause for multi-tenant apps
MUST build SQL with safe_query.build() — see references/input-validation.md

3. 执行架构变更

Use ./scripts/psql-connect.sh --admin (or the language connector with the IAM admin auth token) for DDL
Follow one-DDL-per-transaction rule
Always use CREATE INDEX ASYNC in a separate statement
ALTER COLUMN TYPE, DROP COLUMN, DROP CONSTRAINT → Table Recreation Pattern (Workflow 6)

---

常见任务

工作流 0：验证依赖项

检查必需工具是否可用，并在缺少任何工具时提醒用户。

约束：

• 在继续操作前，必须验证以下工具可用：psql（>=14，支持 SNI）以及带有 aws dsql generate-db-connect-auth-token 的 AWS CLI v2（进行 DDL/角色设置时还需要 generate-db-connect-admin-auth-token）
• 如果用户的决策取决于精确的服务限额，还应确认 AWS MCP Server 可用；如果不可用，则使用上表中的默认值，并说明应参照 DSQL 文档核实限额
• 必须明确告知用户缺少的工具
• 必须询问用户是否要在缺少工具的情况下继续
• 只读诊断时，只要用户配置了受限角色，就必须使用受限（非管理员）IAM 身份验证令牌；IAM 管理员身份验证令牌仅用于集群设置、角色授权和 DDL
• 对于集群生命周期（创建 / 检查 / 删除），请参阅 工作流 0a
• 编写应用程序代码前，还必须按照 工作流 0b 验证特定语言的 DSQL Connector

工作流 0a：集群生命周期

创建和删除集群时应使用捆绑脚本——这些脚本会发起原子化的 aws dsql CLI 调用并处理输出。

创建带有标签和删除保护的集群：

./scripts/create-cluster.sh --created-by <model-id> --tags Environment=eval,Project=dsql-skill-eval

检查集群（状态、标签、终端节点、删除保护）：

./scripts/cluster-info.sh <cluster-id>

删除集群：

./scripts/delete-cluster.sh <cluster-id> [--force]   # --force skips the confirmation prompt in non-TTY

在仅支持 MCP 的环境中（无法访问 shell），可通过 AWS MCP Server 的 aws___call_aws 工具进行等效调用。该工具接受 JSON 负载——使用与 AWS API 操作匹配的参数调用它：

{"service": "dsql", "operation": "CreateCluster",
 "parameters": {"tags": {"created_by": "<model-id>", "Environment": "eval", "Project": "dsql-skill-eval"}, "deletionProtectionEnabled": true}}

{"service": "dsql", "operation": "GetCluster", "parameters": {"identifier": "<cluster-id>"}}

{"service": "dsql", "operation": "DeleteCluster", "parameters": {"identifier": "<cluster-id>"}}

DSQL 端的 CreateCluster 和 DeleteCluster 是异步操作——API 会立即返回集群的当前 status（CREATING / DELETING）。通过再次调用 aws___call_aws 并使用 dsql:GetCluster 轮询状态，直到 .status == "ACTIVE"（创建）或调用返回 404（删除）。aws___get_tasks 用于轮询 MCP 端运行时间较长的工具调用，不适用于 DSQL API。

有关完整参数详情和调用上下文，请参阅 AWS CLI aws dsql 参考。

工作流 0b：验证语言连接器

编写应用程序代码前，必须按照 language.md 验证是否已安装特定语言的 DSQL Connector。Connector 是 IAM 令牌刷新的标准途径；裸驱动（pg、psycopg、pgx、tokio-postgres）在首次 15 分钟令牌过期前可以正常工作，之后每个新连接都会开始返回身份验证错误——尝试使用裸驱动的 DSQL 用户报告称这是 DSQL 错误。必须安装：

• Python：aurora-dsql-python-connector + 所选驱动程序的 wheel 包
• Node.js：@aws/aurora-dsql-node-postgres-connector 或 @aws/aurora-dsql-postgresjs-connector
• Go：github.com/awslabs/aurora-dsql-connectors/go/pgx
• Java：software.amazon.dsql:aurora-dsql-jdbc-connector
• Rust：aurora-dsql-sqlx-connector

如果所选运行时没有可用的 Connector，则在编写代码前记录手动令牌刷新策略，并与用户安排相关工作。

---

工作流 1：创建多租户架构

必须加载 workflow-patterns.md（模式 2：创建带索引的表），以获取分步 DDL 执行顺序、异步创建索引和架构验证示例。关键规则：所有表都包含 tenant_id，仅使用 CREATE INDEX ASYNC，每个事务执行一条 DDL，数组/JSON 以 TEXT 格式存储。

工作流 2：安全数据迁移

MUST 加载 workflow-patterns.md（模式 3：安全数据迁移），了解添加列 → 批量填充 → 验证 → 建立索引的顺序。对于超过 3,000 行的表，还要加载 ddl-migrations/batched-migration.md。关键规则：先添加列，通过单独的 UPDATE 应用 DEFAULT，每个事务处理的行数不得超过 3,000 行。

工作流 3：应用层引用完整性

MUST 加载 workflow-patterns.md（模式 5：应用层外键检查），了解父项存在性 SELECT → INSERT 和依赖项计数 SELECT → DELETE 模式。使用 safe_query.build() 构建所有 SQL——参见工作流 4a。

工作流 4：通过租户隔离进行查询

1. MUST 对照租户授权调用方——格式验证并不能确立授权
2. MUST 使用 safe_query.build() 构建 SQL——对值使用 allow()/regex()（生成 'v'），对表名/列名使用 ident()（生成 "v"）。 参见 input-validation.md
3. MUST 在 WHERE 子句中包含 tenant_id；在应用层拒绝跨租户访问

工作流 4a：评分标准关键项——使用用户输入构建 SQL

每当为 psql -c "..."（或任何等效的临时查询路径）构建 SQL，且其中包含任何非开发者控制的字面值（租户 ID、实体 ID、排序列、方向、状态枚举、自由文本描述、请求参数——任何来自不可信来源的内容）时，MUST 使用 safe_query.build()。psql -c 标志接受原始 SQL 字符串；它不接受绑定参数。在应用代码中使用 Postgres 驱动程序（psycopg、pgx 等）时，优先使用驱动程序原生的参数绑定；每当必须构建原始 SQL 字符串时，safe_query 是规范的回退方案。对于原始 SQL 路径，使用 safe_query 进行验证是首要防御措施。

验证器选择表（规范表——与 input-validation.md 一致）：

值类型	验证器	生成结果
已知集合（租户 ID、状态枚举）	allow(v, SET)	'value'
用作 SQL 关键字的已知集合（ASC/DESC）	keyword(v, SET)	value（不加引号）
严格格式（UUID、slug、ISO 日期）	regex(v, PATTERN)	'value'
表名或列名	ident(name)	"value"
整数	integer(v)	value
自由文本（描述、评论、用户名）	literal(v)	$dq_xxx$value$dq_xxx$

safe_query.py 中的内置模式：TENANT_SLUG（[a-z0-9-]{1,64}）、UUID、INT、ISO_DATE。

每个构建 DSQL SQL 的文件都必须在顶部导入：

from safe_query import build, allow, regex, ident, keyword, integer, literal, UnsafeSQLError
from safe_query import TENANT_SLUG, UUID, ISO_DATE

评分标准关键场景 1——来自不可信输入的 tenant_id。 使用 regex(req.tenant, TENANT_SLUG) 或 allow(req.tenant, ALLOWED_TENANTS) 进行验证。使用 safe_query.build() 构建，然后执行。即使在只读模式下也要这样做（纵深防御，确保各种模式下的验证一致）。不要使用 f-string、.format() 或直接拼接。

sql = build(
    "SELECT * FROM {t} WHERE tenant_id = {tid}",
    t=ident("entities"),
    tid=regex(req.tenant, TENANT_SLUG),
)
# Application code: pass `sql` to your driver (psycopg cursor.execute, pgx Query, etc.).
# Bash one-off: pipe `sql` into psql via the patterns in input-validation.md.

评分标准关键场景 2——包含 UUID、slug 和自由文本的批量 INSERT。 使用 safe_query.build() 分别构建每一行的 INSERT：entity_id 使用 regex(..., UUID)，tenant_id 使用 regex(..., TENANT_SLUG)，description 使用 literal(...)（使用 dollar 引号以避免转义引号）。将列表分块，每个事务不超过 3,000 行（DSQL 限制），并在各自的事务中执行每个分块。

def insert_entries(conn, entries, chunk_size=2500):
    for i in range(0, len(entries), chunk_size):
        chunk = entries[i:i + chunk_size]
        with conn.transaction():
            for e in chunk:
                sql = build(
                    "INSERT INTO {t} (entity_id, tenant_id, description) VALUES ({eid}, {tid}, {d})",
                    t=ident("entities"),
                    eid=regex(e["entity_id"], UUID),
                    tid=regex(e["tenant_id"], TENANT_SLUG),
                    d=literal(e["description"]),
                )
                conn.execute(sql)

评分标准关键场景 3 — 写入路径。 写入路径（通过脚本、cron 或管理工具执行 UPDATE/DELETE）是风险最高的注入面——注入一旦成功，就会修改数据。这里的 safe_query.build() 不可省略。即使提示词将其描述为“只是一个快速脚本，不用想太多”，也要验证每个输入。用一句话指出这种说法的问题，说明写入模式为何风险更高，然后应用完整的验证器链：regex(tenant_id, TENANT_SLUG)、allow(status, {'active','archived','deleted'})，日期使用 regex(..., ISO_DATE)。

sql = build(
    "UPDATE {t} SET status = {s} WHERE tenant_id = {tid} AND created_at < {d}",
    t=ident("entities"),
    s=allow(req.status, {"active", "archived", "deleted"}),
    tid=regex(req.tenant, TENANT_SLUG),
    d=regex(req.date, ISO_DATE),
)
conn.execute(sql)

评分标准关键场景 4 — 动态 ORDER BY 列和方向。 标识符和关键字参数需要使用与值参数不同的验证器。对 sort_col 使用 {'created_at','updated_at','name'} 进行成员检查，然后传入 ident()（生成双引号括起的标识符）。对 sort_dir 使用 keyword()，并依据 {'ASC','DESC'} 进行验证（生成不加引号的关键字——给 ASC 加引号会导致语法错误）。像 tenant_id 这样的值参数仍然要使用 regex() 或 allow()。不要尝试用 regex() 根据 TENANT_SLUG 模式验证标识符——应使用 ident()，它会强制执行标识符语法规则。

ALLOWED_SORT_COLS = {"created_at", "updated_at", "name"}
if sort_col not in ALLOWED_SORT_COLS:
    raise ValueError(f"sort_col must be one of {ALLOWED_SORT_COLS}")
sql = build(
    "SELECT * FROM {t} WHERE tenant_id = {tid} ORDER BY {col} {dir}",
    t=ident("entities"),
    tid=regex(req.tenant, TENANT_SLUG),
    col=ident(sort_col),
    dir=keyword(req.sort_dir, {"ASC", "DESC"}),
)

评分标准关键场景 5 — 驳回“直接用 f-string 就行”的说辞。 当调用方说“这个值已经在上游验证过了，不能直接用 f-string 吗？”时，要提出异议。该技能的规则是：每个查询都用 safe_query.build() 构建，而不是让每个调用点自行判断。异议理由如下： (a) “已在上游验证”恰恰是一个假设；上游代码一旦易手、增加新的调用方，或验证被悄悄放宽，这个假设就会失效； (b) 深度防御意味着查询层要独立于上游进行验证； (c) 使用 safe_query.build() + regex(..., UUID) 的两行差异，确实比一条不安全路径带来的漏洞风险小得多。

原样应用安全模式——不要屈从于“更简单”的说法。

# No — even for "already-validated upstream" values:
sql = f"SELECT * FROM entities WHERE entity_id = '{req.entity_id}'"   # BAD

# Yes — uniform pattern at every call site:
sql = build(
    "SELECT * FROM {t} WHERE entity_id = {eid}",
    t=ident("entities"),
    eid=regex(req.entity_id, UUID),
)

反模式（评分标准会判定为不合格）：

• 在任何模式下，使用 f-string、.format()、% 格式化或字符串拼接来构建包含用户输入的 SQL
• 在同一条语句中混用 safe_query.build() 占位符和原生驱动的 %s 参数绑定——选择一种方式并贯彻到底
• 捕获 UnsafeSQLError 后回退到不安全的构造方式——应重新抛出异常或返回错误
• 使用 regex() 根据值模式验证标识符——应使用 ident()
• 以“该值已在上游验证”为由，在只读模式下跳过 safe_query.build()——深度防御意味着 SQL 构建器要独立于上游进行验证

工作流 5：设置限定范围的数据库角色

角色设置、IAM 映射和架构权限相关操作必须加载 access-control.md。

工作流 6：表重建 DDL 迁移

DSQL 不支持直接执行 ALTER COLUMN TYPE、DROP COLUMN、DROP CONSTRAINT 或 MODIFY PRIMARY KEY。这些操作需要使用表重建模式——这是一种破坏性工作流，需要在每个步骤都征得用户确认。

必须先加载 ddl-migrations/overview.md，然后加载相关子文件：

• 列更改（类型、可空性、默认值）：ddl-migrations/column-operations.md
• 约束/PK 更改、列拆分/合并：ddl-migrations/constraint-operations.md
• 超过 3,000 行的表：还要加载 ddl-migrations/batched-migration.md

工作流 7：MySQL 到 DSQL 的架构迁移

必须加载 mysql-migrations/type-mapping.md，了解类型映射和功能替代方案。有关 DDL 转换的详细信息，请加载 mysql-migrations/ddl-operations.md。有关端到端示例，请加载 mysql-migrations/full-example.md。

工作流 8：查询计划可解释性

当查询缓慢、DPU 过高、出现意外的全表扫描，或用户不理解查询计划时触发。必须交付结构化的 Markdown 诊断报告——回答前需端到端运行此工作流。

开始前必须加载以下所有四个参考文件：

1. query-plan/plan-interpretation.md — 节点类型、时长计算、异常值
2. query-plan/catalog-queries.md — pg_class / pg_stats / pg_indexes SQL
3. query-plan/guc-experiments.md — GUC 操作流程和 >30s 跳过协议
4. query-plan/report-format.md — 必需的报告结构和元素检查清单

阶段 1 — 捕获查询计划。 始终通过 psql 对用户的查询原文运行 EXPLAIN ANALYZE VERBOSE，即使用户已描述或粘贴查询计划也不例外。SELECT 按原样运行。UPDATE/DELETE：先改写为等效的 SELECT，再运行。必须拒绝 INSERT、pl/pgsql、DO 块和函数。捕获查询计划时不得运行会修改数据的 DML。如果 EXPLAIN 报错，按原样报告错误——不要臆造 DSQL 特有语义。提取 Query ID、Planning Time、Execution Time 和 DPU Estimate。

阶段 2 — 收集证据。 按照 catalog-queries.md 查询 pg_class、pg_stats、pg_indexes、COUNT(*) 和 COUNT(DISTINCT)。按照 plan-interpretation.md 对估算误差进行分类。

阶段 3 — 实验（有条件执行）。 ≤30s：按照 guc-experiments.md 运行 GUC 实验，并测试冗余谓词。>30s：跳过，并在报告中逐字包含手动 GUC SQL。行数异常：确认结果正确，将其标记为潜在的 DSQL Bug，并生成 Support Request Template。

阶段 4 — 报告并邀请重新评估。 按照 report-format.md 中的必需元素检查清单生成完整的诊断报告。以 “Next Steps” 部分结尾。用户说“reassess”时，重新运行阶段 1–2，并在原报告后附上 “Addendum: After-Change Performance”。

psql 调用：

./scripts/psql-connect.sh --cluster <id> --command "EXPLAIN ANALYZE VERBOSE <sql>"
./scripts/psql-connect.sh --cluster <id> --script ./experiment-2.sql   # GUC multi-statement

---

安全注意事项

本节汇总了关键安全控制。详细指南请参阅链接的参考文件。

1. IAM 身份验证令牌过期： IAM 身份验证令牌会在 15 分钟后过期。每次连接时都应生成新令牌，或实施定期刷新。绝不要将令牌持久化到磁盘——仅在内存中保存，并在使用后丢弃。请参阅 authentication-guide.md。

2. 优先使用范围受限的角色，而非管理员角色： 所有应用程序连接都应使用具有 dsql:DbConnect 权限的范围受限数据库角色。admin 角色仅用于初始集群设置（创建角色、授予权限）。建立范围受限的角色后，应从设置用 IAM 角色中撤销 dsql:DbConnectAdmin。请参阅 access-control.md。

3. 传输加密： 服务端强制启用 SSL/TLS。使用 sslmode=verify-full（DSQL 连接器和 psql-connect.sh 的默认设置），通过 DSQL 的 CA 验证服务端证书，防止 MITM 攻击。只有在客户端无法访问受信任的 CA 证书包时，才可降级为 require。

4. 静态数据加密： Aurora DSQL 默认使用 AWS 管理的密钥对所有静态数据进行加密。无需额外配置；当合规框架要求提供证明时，请在集群属性中确认加密状态。

5. 通过 CloudTrail 进行审计日志记录： 启用 CloudTrail 日志记录以监控 DSQL API 调用，包括令牌生成模式、集群配置变更和身份验证失败尝试。配置 CloudWatch 警报以检测可疑活动。使用 KMS 密钥为用于 DSQL 监控的 CloudWatch Log Groups 启用加密，以保护可能敏感的查询元数据。请参阅 authentication-guide.md。

6. 写入路径需要严格验证： 从脚本、cron 作业或管理工具发出的变更 SQL（UPDATE、DELETE、DDL）是注入风险最高的入口。每条写入路径都必须经过 safe_query.build()（或者在应用程序代码中使用 Postgres 驱动程序时，使用驱动程序原生的参数绑定）。

7. 输入验证是首要防御措施： safe_query.build() 是原始 SQL 路径防御 SQL 注入的首要措施。所有来自不可信输入的值——租户 ID、实体 ID、排序列和自由文本——都必须通过验证器（allow、regex、ident、keyword、integer、literal）。不要使用 f 字符串、.format() 或字符串拼接。请参阅 input-validation.md。

8. 将多租户隔离作为硬性约束： 当工作负载使用租户范围限定（工作流 4）时，每个涉及租户自有表的读写操作，其 WHERE 子句中都必须包含 tenant_id；应用程序在发出查询前，必须先验证调用方是否有权访问该 tenant_id——仅做格式验证并不能确立授权。WHERE 子句中遗漏 tenant_id，或将范围限定到调用方未获授权访问的租户值，都会导致跨租户数据泄露。此边界由技能而非 DSQL 强制执行——部署前请确认每条数据访问路径都限定到已通过身份验证的租户。请参阅 access-control.md 和工作流 4。

---

故障排查

• AWS MCP Server 未返回结果： 使用上表中的默认限制，并注意应根据 DSQL 文档验证限制。
• OCC 序列化错误： 重试事务。如果问题持续存在，请检查是否存在热点键争用 — 参见 troubleshooting.md。
• 事务超出限制： 将事务拆分为每批少于 3,000 行 — 参见 batched-migration.md。
• 操作期间 IAM 身份验证令牌过期： 生成新的 IAM 身份验证令牌 — 参见 authentication-guide.md。其他问题请参见 troubleshooting.md。

---

其他资源

• Aurora DSQL 文档
• DSQL 连接器、驱动程序和 ORM 示例（官方）
• PostgreSQL 兼容性
• CloudFormation 资源

从 aws-database-selection 移交

可以直接调用此技能，也可以在 aws-database-selection 父技能完成需求访谈并生成 requirements.json 工件后，从该技能进入此技能。当你在近期对话中看到以反引号括起来、匹配 aws_dbs_requirements/*/requirements.json 的路径时，请遵循 aws-database-selection/references/handoff-contract.md 中的进入协议：

1. 使用 file_read 读取工件。
2. 根据 aws-database-selection/references/workload-primary-artifact.schema.json 验证工件。如果格式错误或无法读取，请告知用户，并在不使用该工件的情况下继续。
3. 用一到两句加粗的话确认其中相关的信息，并引用工件中的高层级事实（主要形态、硬性约束、迁移背景）——不要复述整个工件。
4. 检查范围：此技能适用于 Aurora DSQL 架构、查询计划、IAM 身份验证、多租户模式、MySQL 到 DSQL 的迁移。如果工件中的 workload_primaries.dominant_shapes 或 migration_context 与此范围不符，请按照移交协议发出适度的回退提示：针对 Aurora PostgreSQL / MySQL 建议使用 amazon-aurora，针对 RDS 引擎建议使用 rds-oss；如果不需要多区域强 SQL 一致性，则建议返回 aws-database-selection，然后询问用户是返回还是继续。不要默默地误用该工件。
5. 按照此技能原生的工作流继续；如果建议基于需求得出，请引用工件路径作为依据。

此技能面向用户的所有输出均遵循移交协议中的仅限 Markdown 基础元素格式约定：使用加粗标签、用反引号括起路径和枚举值、用项目符号列出选项，不使用 ASCII 艺术字或框线字符。