motherduck-migrate-to-motherduck

迁移到 MotherDuck

从这里开始：MotherDuck 服务是否处于活动状态？

使用活动的远程 MotherDuck MCP 服务或本地 MotherDuck 服务，检查范围内的数据库、架构、粒度、键和相关指标。复用已知上下文，并将发现范围限定在请求的工作内；默认不要扫描整个工作区。根据实际数据模型确定结果。

根据请求或活动上下文确定目标。只有当歧义会实质性影响结果时才提问。没有服务时，使用提供的架构和明确的假设进行规划；不要暗示已进行实时验证。

迁移默认策略

• 优先使用 MotherDuck 原生存储
• 扩展现有 PostgreSQL 体系时，pg_duckdb 是干扰最小的路径
• 切换前进行验证
• 在性能调优前，有意识地迁移 SQL 方言和数据类型
• 分阶段切换，而非一次性替换
• 如果源数据库已打包在云存储中，则远程导入 DuckDB 数据库文件（CREATE DATABASE ... FROM 's3://...'）
• 如果必须在开发、预发布和生产环境中重建目标环境（数据库、角色、共享和服务账户），则使用 Terraform 定义
• 如果旧数据仓库强制执行行访问策略、列脱敏或安全视图，则在 Shares 上使用安全视图；映射每项策略，并以受影响的使用者身份进行测试
• 在目标模型稳定后，将经过验证的业务定义、联接规则和切换注意事项记录到 Guides 中

工作流

1. 检查可用的 MotherDuck 服务，或提供的源和目标上下文。
2. 对源系统和目标服务模式进行分类。
3. 检查目标端的 MotherDuck 布局（如果可用）。
4. 选择连接和数据摄取路径。
5. 列出不兼容的 SQL、函数、数据类型和运维假设。
6. 使用 DuckDB SQL 重建分析模型。
7. 执行源与目标的验证。
8. 创建或更新相关的 MotherDuck Guides，使切换后的 Agent 使用经过验证的目标定义。
9. 一次切换一个工作负载。

根据请求确定执行方式：回答、审查或规划工作应返回所请求的迁移产物；构建或更改工作只执行请求范围内的迁移部分并进行验证。切换、破坏性源更改或尚未获准的外部写入都必须先获得确认。

当此技能生成原生 DuckDB（md:）连接时，使用 custom_user_agent=agent-skills/2.6.0(harness-<harness>;llm-<llm>) 为其添加标识。如果缺少元数据，则使用 harness-unknown 和 llm-unknown 作为后备值。

输出

对于完整的迁移项目，根据请求酌情涵盖以下内容：

• 目标模式
• 迁移顺序
• 验证计划
• 回滚路径
• 首个切换部分

对于明确要求结构化 JSON 的请求，请阅读输出规范。否则，使用适合所请求交付物的格式。

参考资料

只阅读与任务相关的章节；这些内容仅供参考，并非必须遵循的固定步骤。

• references/MIGRATION_PLAYBOOK.md -- 目标模式选择、迁移决策矩阵、DuckLake 方案以及特定源系统问题（Snowflake、Redshift、Postgres、dbt、lakehouse）
• references/MIGRATION_VALIDATION.md -- 可复制改编的验证 SQL（行数、使用 pct_variance 的指标、新增／删除／更改记录）和 Python 编排器

示例

仅在运行随附示例或复现其验证时，才阅读执行参考。

• migration_validation_example.py
• migration_validation_example.ts

相关技能

仅在缺少相应能力时加载相关技能；复用已建立的上下文。

• motherduck-connect——为目标系统选择连接路径
• motherduck-explore——检查目标端的 MotherDuck 工作区
• motherduck-load-data——批量迁移和原始数据落地模式
• motherduck-model-data——构建目标分析模型
• motherduck-query——迁移并验证关键 SQL
• motherduck-ducklake——仅在明确要求开放表格式时使用
• motherduck-manage-guides——保留已验证的目标语义和迁移注意事项