dsql

Amazon Aurora DSQL 技能

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

---

参考文件

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

核心：

参考文件	加载时机	内容
development-guide.md	在更改架构或执行数据库操作前，始终加载	最佳实践、DDL 规则、事务限制、应用层参照完整性
language.md	必须加载，以便进行特定语言的选择	驱动程序选择、DSQL 连接器、连接代码
access-control.md	涉及角色、授权或敏感数据时必须加载	限定范围的角色设置、IAM 到数据库角色的映射
troubleshooting.md	出现错误或意外行为时建议加载	OCC 错误、连接失败、集群状态错误、令牌过期、DDL 被拒绝的原因
dsql-examples.md	获取实现示例时加载	多租户架构示例、批量操作、FK 验证模式、连接池
onboarding.md	用户请求“开始使用 DSQL”时	交互式分步指南
occ-retry-patterns.md	编写 OCC 重试代码或缓解冲突时必须加载	DSQL 连接器、手动重试模式、幂等设计

MCP：

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

DDL 迁移：

参考	加载时机	包含内容
ddl-migrations/overview.md	遇到 DROP COLUMN、ALTER TYPE、DROP CONSTRAINT 时必须加载	表重建模式、验证与交换
ddl-migrations/column-operations.md	遇到 DROP COLUMN、ALTER TYPE、SET/DROP NOT NULL/DEFAULT 时	列级迁移模式
ddl-migrations/constraint-operations.md	遇到 ADD/DROP 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	遇到 PG → DSQL 类型问题时必须加载	C 排序规则、NUMERIC 精度、JSON/JSONB
pg-migrations/fk-replacement.md	生成 FK 验证代码时必须加载	按租户范围限定的 validate_fk_*() 模板、级联操作
pg-migrations/index-conversion.md	诊断无法修复的索引时必须加载	GIN/GiST/BRIN → btree、部分索引、表达式索引
pg-migrations/schema-objects.md	遇到 ENUM、物化视图、扩展、多模式时必须加载	ENUM → CHECK、视图、角色/IAM 映射
pg-migrations/multi-region.md	遇到多区域、主动-主动或 HA 问题时	架构、地理分区

ORM 指南：

参考资料	何时加载	包含内容
orm-guides/overview.md	将任何 ORM 迁移到 DSQL 时	适配器名称、Django/Hibernate/Rails/SQLAlchemy 的关键注意事项

数据加载：

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

查询计划可解释性：

参考资料	何时加载	包含内容
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 加载	必需的报告结构、要素清单、支持请求模板

---

可用的 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 minutes	aurora dsql transaction limits
每个集群的最大连接数	10,000	aurora dsql connection limits
身份验证令牌有效期	15 minutes	aurora dsql authentication token
最大连接持续时间	60 minutes	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

何时核实： 在建议批处理大小、连接池设置或架构设计之前，如果触及限制会导致故障；只要精确数值可能影响用户决策，也应核实。

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

CLI 工具

直接使用 AWS CLI、psql 和 aurora-dsql-loader 管理集群、建立 SQL 连接，以及从本地或 S3 中的 CSV/TSV/Parquet 文件批量加载数据。加载 data-loading.md 以获取加载器使用指南。

---

快速入门

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。

---

常见工作流

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

1. 使用 transact 创建包含 tenant_id 列的主表
2. 在单独的 transact 调用中，在 tenant_id 上创建异步索引
3. 为常见查询模式创建复合索引（分别调用 transact）
4. 使用 get_schema 验证架构

• 所有表中必须包含 tenant_id
• 必须仅使用 CREATE INDEX ASYNC
• 必须在各自的 transact 调用中执行每条 DDL：transact(["CREATE TABLE ..."])
• 必须将数组序列化为 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. 添加列：transact(["ALTER TABLE ... ADD COLUMN ..."])
3. 使用 UPDATE 填充现有行（每批少于 3,000 行）
4. 使用 readonly_query COUNT 验证
5. 如有需要，创建索引：先验证，再运行 transact(["CREATE INDEX ASYNC ..."])

• 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：应用层引用完整性

**INSERT：**MUST 使用 readonly_query 验证父记录是否存在 → 如果未找到则抛出错误 → 使用 transact 插入子记录。

**DELETE：**MUST 使用 readonly_query COUNT 检查依赖项 → 如果存在依赖项则返回错误 → 如果安全，则使用 transact 删除。

工作流 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、DROP COLUMN、DROP CONSTRAINT 或 MODIFY PRIMARY KEY，请使用 表重建模式。这是一个破坏性工作流，每一步都需要用户确认。该模式中生成的每条 DDL（CREATE new、INSERT ... SELECT、DROP old、RENAME）在执行前 MUST 使用 dsql_lint(sql=..., fix=true) 验证。

尝试执行上述任一操作前，MUST 加载 ddl-migrations/overview.md。

工作流 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 诊断报告。

必须在阶段 0 加载以下全部四个参考文件：query-plan/plan-interpretation.md、query-plan/catalog-queries.md、query-plan/guc-experiments.md、query-plan/report-format.md。各阶段的流程（捕获计划、收集证据、开展实验、生成报告）均在这些文件中定义。

安全性。 捕获计划时只能使用 readonly_query。捕获计划时，将 DML 重写为 SELECT。不得使用 transact --allow-writes 捕获计划。

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

必须加载 pg-migrations/type-mapping.md 和 pg-migrations/schema-objects.md。首先运行 dsql_lint(fix=true) 进行机械修复，然后针对无法修复的诊断以及检查器无法处理的模式，应用 pg-migrations 参考文件中的语义转换。部署前，对最终输出重新运行检查。

工作流 11：ORM 迁移（Django/Hibernate/Rails）

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

错误场景

• awsknowledge 未返回结果： 使用上表中的默认限制，并注明应根据 DSQL 文档核实这些限制。
• dsql_lint 不可用或超时： 请参阅 dsql-lint.md 的错误处理部分。不要悄然跳过验证——应告知用户，并在依据 development-guide.md 中的手动规则继续操作前，要求用户明确确认。
• OCC 序列化错误： 重试事务。如果问题持续存在，请检查是否有热点键争用——参阅 troubleshooting.md。
• 事务超出限制： 拆分为每批少于 3,000 行——参阅 batched-migration.md。
• 操作过程中令牌过期： 生成新的 IAM 令牌——参阅 authentication-guide.md。其他问题请参阅 troubleshooting.md。

其他资源

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