dsql

Amazon Aurora DSQL 技能

Aurora DSQL 是一款无服务器、兼容 PostgreSQL 的分布式 SQL 数据库。本技能涵盖通过 MCP 工具直接执行查询、管理架构、迁移、多租户隔离、IAM 身份验证，以及通过 aurora-dsql-loader 批量加载数据。

---

参考文件

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

核心：

参考文件	加载时机	内容
development-guide.md	修改架构或执行数据库操作前务必加载	最佳实践、DDL 规则、事务限制、外键约束
foreign-keys.md	执行外键操作或迁移时务必加载	外键语法、操作、验证、租户键
language.md	需要选择特定语言时务必加载	驱动选择、DSQL 连接器、连接代码
access-control.md	涉及角色、授权或敏感数据时务必加载	范围限定的角色设置、IAM 到数据库角色的映射
troubleshooting.md	遇到错误或意外行为时建议加载	OCC 和 23503、外键、连接、集群状态
limits-and-error-codes.md	确定批次、键或索引的大小前，或遇到 54000/0A000/54011 时建议加载	包含 SQLSTATE 和确切消息的所有限制、拒绝原因及配额
dsql-examples.md	获取实现示例时加载	多租户访问、批量操作、标识和序列、连接池
onboarding.md	用户请求“开始使用 DSQL”时	交互式分步指南
occ-retry-patterns.md	编写 OCC 重试代码或缓解冲突时务必加载	连接器、40001 重试、不可重试的 23503、外键读取冲突、幂等设计

MCP：

参考文件	加载时机	内容
mcp-setup.md	获取 MCP 服务指导时始终加载	设置说明、2 种配置选项
mcp-tools.md	查看 MCP 工具语法和示例时	工具参数、输入验证
dsql-lint.md	运行 dsql_lint 或处理外部 SQL 前务必加载	工具参考、修复状态、无法修复的错误的解决方法

DDL 迁移：

参考	加载时机	内容
ddl-migrations/overview.md	对 ALTER TYPE、SET NOT NULL、MODIFY PRIMARY KEY，必须加载	直接 ALTER 覆盖范围和最后手段：重建表
ddl-migrations/column-operations.md	DROP COLUMN、ALTER TYPE、SET/DROP NOT NULL/DEFAULT	列级迁移模式
ddl-migrations/constraint-operations.md	ADD/DROP CONSTRAINT、VALIDATE CONSTRAINT、MODIFY PRIMARY KEY	约束和结构变更
ddl-migrations/batched-migration.md	行数超过 3,000 的表	分批处理模式、进度跟踪

MySQL 迁移：

参考	加载时机	内容
mysql-migrations/type-mapping.md	进行 MySQL → DSQL 迁移时，必须加载	数据类型映射、功能替代方案
mysql-migrations/ddl-operations.md	将 MySQL DDL 转换为 DSQL	AUTO_INCREMENT、ENUM、SET、FK 模式
mysql-migrations/full-example.md	完整的 MySQL 表迁移	端到端示例及决策摘要

PostgreSQL 迁移：

参考	加载时机	内容
pg-migrations/type-mapping.md	对 DSQL NUMERIC 或 PG 类型问题，必须加载	C 排序规则、NUMERIC(p,s)、JSON/JSONB
pg-migrations/index-conversion.md	进行任何索引转换或询问索引支持时，必须加载	GIN/GiST/BRIN → btree、移除运算符类、部分索引和表达式索引、排序顺序
pg-migrations/schema-objects.md	对 ENUM、物化视图、扩展、多模式、CREATE FUNCTION，必须加载	ENUM → CHECK、视图、角色/IAM 映射、LANGUAGE sql 函数
pg-migrations/multi-region.md	多区域、主动-主动或 HA 相关问题	架构、地理分区

ORM 指南：

参考资料	加载时机	内容
orm-guides/overview.md	迁移 ORM 或在 DSQL 中使用 ORM 锁定时	Django/EF Core/Hibernate/Rails/SQLAlchemy 的适配器名称、锁定方式和关键注意事项

数据加载：

参考资料	加载时机	内容
data-loading.md	规划或运行 aurora-dsql-loader 批量加载时	全新与预热分区、恢复/重试、--on-conflict 语义、吞吐量诊断

系统诊断：

参考资料	加载时机	内容
system-diagnostics/workflow.md	必须在工作流 12 入口加载——集群性能诊断	前提条件、5 个诊断阶段、时间对比、交接
system-diagnostics/wait-events.md	解读 AAS 结果时始终加载	标准 DSQL 等待事件说明和调查指南
system-diagnostics/promql-patterns.md	构建 PromQL 查询时加载	用于 AAS 细分、Top SQL、时间对比的可复用查询模板

查询计划可解释性：

参考	加载时机	内容
query-plan/workflow.md	必须在工作流 9 开始时加载——它控制所有其他文件	触发条件、上下文消歧、路由、分阶段工作流
query-plan/plan-interpretation.md	必须在工作流 9 阶段 0 加载	DSQL 节点类型、节点时长计算、估算误差范围
query-plan/catalog-queries.md	必须在工作流 9 阶段 0 加载	pg_class/pg_stats/pg_indexes SQL、相关谓词验证
query-plan/guc-experiments.md	必须在工作流 9 阶段 0 加载	GUC 实验流程、30 秒跳过协议
query-plan/report-format.md	必须在工作流 9 阶段 0 加载	必需的报告结构、要素清单、支持请求模板
query-plan/query-rewrites-generic.md	应在阶段 0 加载；按需加载子文件	10 种通用重写模式的索引
query-plan/query-rewrites-dsql-specific.md	应在阶段 0 加载；按需加载子文件	DSQL 专属重写模式的索引

---

选择连接方式：MCP 还是 CLI/psql

aurora-dsql MCP 服务会在启动时绑定单个集群（--cluster_endpoint），因此，要将它用于其他集群，就意味着需要编辑 .mcp.json 并重启会话。

• 只有当 aurora-dsql MCP 工具（readonly_query、transact、get_schema）已指向所需集群时，才可使用这些工具。
• 否则——未配置、已禁用，或绑定到其他集群时，切勿重新配置。 请改用 CLI + psql 方式：scripts/psql-connect.sh <cluster-id> --region <region> --command "SELECT ..."（生成 IAM 令牌并通过 psql 执行）。
• 如果无法确认 MCP 指向哪个集群，请先确认，或使用 CLI/psql 方式——在错误的集群上运行，比先检查更糟。

仅文档类 MCP 工具（dsql_lint、dsql_*_documentation、dsql_recommend）无需集群。 CloudWatch MCP（工作流 12）会在每次调用时接收 region/cluster_id，因此，一个正在运行的服务即可查询任何启用了 PromQL 的区域中的集群（调用时传入每个集群所在的区域）。详情见： connectivity-tools.md。

可用的 MCP 工具

aurora-dsql MCP 服务提供以下工具：

数据库操作：

1. readonly_query - 执行 SELECT 查询（返回字典列表）
2. transact - 在事务中执行 DDL/DML 语句（接受 SQL 语句列表）
3. get_schema - 获取指定表的结构

SQL 验证：

1. dsql_lint - 验证 SQL 是否兼容 DSQL，并可选择自动修复问题。在执行来自外部的 SQL 之前使用。

文档与知识：

1. dsql_search_documentation - 搜索 Aurora DSQL 文档
2. dsql_read_documentation - 阅读特定文档页面
3. dsql_recommend - 获取 DSQL 最佳实践建议

**注意：**没有 list_tables 工具。请使用 readonly_query 查询 information_schema。

详细的设置说明请参阅 mcp-setup.md。 详细的用法和示例请参阅 mcp-tools.md。

AWS Knowledge MCP（awsknowledge）

在向用户提供建议前，请先查证 DSQL 服务限制。以下数值限制为默认值，可能会发生变化；如果用户的决策取决于确切限制，请先进行核实：

限制	默认值	验证查询
每个事务的最大行修改数	3,000	aurora dsql transaction limits
每个事务的最大数据量	10 MiB	aurora dsql transaction limits
最大事务持续时间	5 分钟	aurora dsql transaction limits
每个集群的最大连接数	10,000	aurora dsql connection limits
身份验证令牌过期时间	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
支持的列数据类型	参阅文档	aurora dsql supported data types

**何时验证：**在建议批次大小、连接池设置或架构设计时，如果触及限制会导致失败；以及在确切数值可能影响用户决策的任何情况下。有关包含各 SQLSTATE 和确切错误消息的完整限制列表，请参阅 limits-and-error-codes.md；如果其中标注某个值为观察所得，且与文档不一致，请采用观察所得的值。

**备用方案：**如果 awsknowledge 不可用，请使用上述默认值，并提醒用户应根据 DSQL 文档核实限制。

可用的 CLI 脚本

脚本中的 Bash 脚本可用于集群管理（创建、删除、列出、查看集群信息）、psql 连接，以及从本地或 S3 上的 csv/tsv/parquet 文件批量加载数据。 用法和钩子配置请参阅 scripts/README.md。

---

快速开始

0. **选择连接方式：**确认 aurora-dsql MCP 的目标是你的集群；如果不是，请改用 CLI/psql 方式——参见选择连接方式。以下步骤中提到的 MCP 工具，也可以通过 psql-connect.sh --command "..." 以相同方式运行对应的 SQL。
1. **探索：**使用 readonly_query 和 information_schema 列出表。使用 get_schema 查看表结构。
2. 查询：使用 readonly_query 执行 SELECT 查询。对于多租户应用，WHERE 中必须包含 tenant_id。必须使用 safe_query.build() 构建 SQL。
3. **更改架构：**使用 transact，每个事务执行一条 DDL。必须将 DML 批量控制在 3,000 行以下。必须单独调用 CREATE INDEX ASYNC。先使用 dsql_lint 验证。
4. **批量加载数据：**使用 aurora-dsql-loader 加载 CSV/TSV/Parquet。详情请参阅 data-loading.md。先使用 --dry-run。

---

性能路由

当用户报告性能问题时，使用此表选择正确的工作流：

用户反馈	路由
一般性能问题、“集群很慢”、“发生了变化”、延迟回归、未指定具体查询	工作流 12（系统诊断）——先通过 CloudWatch 观察
有待调查的具体查询或 query_id、“解释此计划”、“为什么此查询很慢”	工作流 9（查询计划可解释性）——直接进行 EXPLAIN 分析
OCC 冲突、提交错误、重试风暴	工作流 12（系统诊断）——先通过 CW 指标确认，再进行调查
成本优化、“计算时间花在哪里”	工作流 12（系统诊断）——先找出主要贡献因素

**规则：**拿不准时，先从工作流 12 开始。它会找出需要调查的具体查询，并附带上下文转到工作流 9。

---

常见工作流

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

1. 使用单独的 transact 调用，创建包含 tenant_id 的租户自有表
2. 租户自有父表使用复合租户外键，共享父表使用普通外键
3. 使用单独的 CREATE INDEX ASYNC 调用，创建租户索引和查询模式索引
4. 使用 get_schema 验证

• 每条 DDL 必须在单独的 transact 调用中执行：transact(["CREATE TABLE ..."])
• 数组必须序列化为单列表示形式——DSQL 没有数组列类型；优先使用 JSONB（运算符可直接使用）；当数据库不处理该列内容时，可以使用 TEXT；询问用户。对于 JSONB 数组，在查询时使用 jsonb_array_elements_text(data) 展开

工作流 2：安全数据迁移

执行前，MUST 使用 dsql_lint(fix=true) 验证每条 DDL。DML 无需 lint。

1. 使用 dsql_lint(sql=..., fix=true) 验证 DDL——按照 dsql-lint.md 处理诊断结果
2. 如果有经过审核的 fixed_sql，则执行该语句；否则执行经过审核的源语句
3. 在单独的 transact 调用中添加列
4. 使用 UPDATE 填充现有行（分批处理，每批少于 3,000 行）
5. 使用 readonly_query COUNT 进行验证
6. 如有需要，创建索引：先验证，然后在单独的 transact 调用中执行经过审核的 DDL

• MUST 在单独的 transact 调用中执行每条 ALTER TABLE——DSQL 不支持包含多条 DDL 的事务，会报错 multiple ddl statements not supported in a transaction
• MUST 仅使用列名和类型添加列；通过单独的 UPDATE 设置 DEFAULT
• MUST 在单独的 transact 调用中分批更新，每批少于 3,000 行

恢复： 通过筛选 WHERE new_column IS NULL 恢复失败的批次。

工作流 3：批量数据加载

使用 aurora-dsql-loader 加载 CSV、TSV 或 Parquet 文件。在就吞吐量提供建议或诊断加载缓慢问题之前，MUST 加载 data-loading.md。

1. 先使用 --dry-run 验证
2. 使用 --manifest-dir 将清单存储在持久存储中（不要使用 /tmp——AL2023 上的 tmpfs 会在崩溃时丢失），如果文件有标题行，则使用 --header
3. 失败时：使用 --resume-job-id 恢复；对于重复项，使用 --on-conflict do-nothing
4. 对于大型表：加载完成后使用 CREATE INDEX ASYNC 创建二级索引

工作流 4：外键约束

创建、修改、删除或迁移外键之前，MUST 加载并遵循 foreign-keys.md。

工作流 5：使用租户隔离进行查询

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

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

设置角色、映射 IAM 和配置架构权限时，MUST 加载 access-control.md。

工作流 7：表重建 DDL 迁移

对于 ALTER COLUMN TYPE、SET NOT NULL 或 MODIFY PRIMARY KEY，MUST 加载 ddl-migrations/overview.md。支持时使用直接 ALTER 形式；否则，提供经用户批准的表重建计划。

工作流 8：验证并迁移到 DSQL

运行 dsql_lint 前，MUST 加载 dsql-lint.md。运行 dsql_lint(sql=source_sql, fix=true) 进行验证和自动转换。对于源自 MySQL 的 SQL，即使 lint 未发现问题，也 MUST 对照 mysql-migrations/type-mapping.md 进行交叉检查。遇到 parse_error 时，改为手动转换，然后重新运行 lint。

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

说明 DSQL 优化器选择特定计划的原因。适用于查询缓慢、DPU 高、意外的全表扫描，或用户不理解查询计划的情况。交付内容必须是一份结构化的 Markdown 诊断报告。

进入工作流时 MUST 加载 query-plan/workflow.md——该文件定义了触发条件、上下文判定、路由和完整的分阶段工作流（阶段 0–4）。Workflow.md 会说明各阶段需要加载哪些参考文件。

安全性。 仅使用 readonly_query 捕获计划。将 DML 改写为 SELECT 来捕获计划。捕获计划时 MUST NOT 使用 transact --allow-writes。

工作流 10：完整 PostgreSQL → DSQL 架构迁移

必须加载 pg-migrations/type-mapping.md、pg-migrations/index-conversion.md、pg-migrations/schema-objects.md 和 foreign-keys.md。先运行 dsql_lint(fix=true) 进行机械修复，保留外键关系，转换不受支持的源语法或选项，然后针对无法修复的诊断以及 linter 无法处理的模式，应用 pg-migrations 参考资料中的语义转换。部署前重新 lint 最终输出。

工作流 11：ORM 迁移与锁定（Django/EF Core/Hibernate/Rails/SQLAlchemy）

加载 orm-guides/overview.md，了解适配器名称、锁定指南和特定框架的注意事项。

工作流 12：系统诊断（CloudWatch AAS）

通过 PromQL 查询 db.active_sessions.avg，诊断集群性能。检测等待事件分布中的时间异常，识别性能退化的查询，并转到工作流 9 进行逐个查询的调查。

要求： 启用并配置 CloudWatch MCP 服务（awslabs.cloudwatch-mcp-server），使其能够在与集群相同的区域访问 PromQL——启用方法、区域要求以及使其工具完成注册所需的会话重启，请参阅 mcp/mcp-setup.md。

进入工作流时必须加载 system-diagnostics/workflow.md——其中定义了前置条件、5 个诊断阶段、时间基线，以及针对已识别查询转到工作流 9 的路由方式。

错误场景

• awsknowledge 未返回结果： 使用上表中的默认限制，并说明应根据 DSQL 文档核实这些限制。
• dsql_lint 不可用或超时： 请参阅 dsql-lint.md 的“错误处理”部分。不得悄然跳过验证——应告知用户，并在使用 development-guide.md 中的手动规则继续操作前，要求用户明确确认。
• OCC 序列化错误（40001）： 使用退避策略重试，并将 (OC001) 一并纳入重试循环——请参阅 occ-retry-patterns.md。
• 外键违规（23503）： 修正关系或引用操作；不得将其纳入 40001 重试循环——请参阅 troubleshooting.md。
• 事务超出限制： 将批次拆分为少于 3,000 行且小于 10 MiB；大小会在 COMMIT 时检查——请参阅 limits-and-error-codes.md 了解如何确定批次大小，并参阅 batched-migration.md 了解相应模式。
• 操作期间令牌过期： 生成新的 IAM 令牌——请参阅 authentication-guide.md。其他问题请参阅 troubleshooting.md。

其他资源

• Aurora DSQL 文档
• 代码示例代码库