Back to Details

motherduck-migrate-to-motherduck

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate to MotherDuck

迁移至MotherDuck

Use this skill when the user needs a migration plan from another warehouse, PostgreSQL estate, or mixed analytics stack onto MotherDuck.
This is a use-case skill. It orchestrates 
motherduck-connect
, 
motherduck-explore
, 
motherduck-load-data
, 
motherduck-model-data
, 
motherduck-query
, and 
motherduck-ducklake
.
当用户需要从其他数据仓库、PostgreSQL环境或混合分析栈迁移至MotherDuck时，可使用本技能。
这是一个场景化技能，它会编排
motherduck-connect
、
motherduck-explore
、
motherduck-load-data
、
motherduck-model-data
、
motherduck-query
和
motherduck-ducklake
这些技能。

Start Here: Is a MotherDuck Server Active?

第一步：是否有活跃的MotherDuck服务器？

Always determine this before writing a migration plan.
  • If a remote MotherDuck MCP server or local MotherDuck server is active, use it.
  • Ask which MotherDuck database or workspace will receive the migration if the user has not specified it.
  • Explore the live target side first when available:
    • existing databases and schemas
    • current landing zones
    • current analytical tables
    • naming conventions
    • any partial migration already in place
Also capture the source-side shape:
  • source platform
  • source table grain
  • key metrics
  • validation keys
  • serving workloads after cutover
If no server is active, ask for representative source and target schemas before finalizing the migration plan.
在制定迁移方案前，务必先确认这一点。
  • 如果存在远程MotherDuck MCP服务器或本地MotherDuck服务器处于活跃状态，请直接使用该服务器。
  • 如果用户未指定，请询问迁移将导入至哪个MotherDuck数据库或工作区。
  • 若目标端可用，先探索当前目标端的情况：
    • 现有数据库和模式
    • 当前着陆区
    • 当前分析表
    • 命名规范
    • 已完成的部分迁移内容
同时收集源端的信息：
  • 源平台
  • 源表粒度
  • 关键指标
  • 验证键
  • 切换后的服务负载
如果没有活跃服务器，在最终确定迁移方案前，请获取具有代表性的源端和目标端模式。

Use This Skill When

适用场景

  • The user is moving from Snowflake, Redshift, Postgres, or similar.
  • The user needs cutover sequencing and validation.
  • The user needs to decide between native MotherDuck, 
    pg_duckdb
    , or DuckLake.
  • The migration plan needs rollback, not just a list of copy commands.
  • 用户从Snowflake、Redshift、Postgres或类似平台迁移。
  • 用户需要切换顺序和验证方案。
  • 用户需要在原生MotherDuck、
    pg_duckdb
    或DuckLake之间做出选择。
  • 迁移方案需要包含回滚机制，而不仅仅是复制命令列表。

Migration Defaults

迁移默认规则

  • native MotherDuck storage first
  • pg_duckdb
    when extending an existing PostgreSQL estate is the least disruptive path
  • validate before cutover
  • port SQL dialect and data types deliberately before performance tuning
  • phased cutover over big-bang replacement
  • 优先使用原生MotherDuck存储
  • 当扩展现有PostgreSQL环境的改动最小时，选择
    pg_duckdb
  • 在切换前完成验证
  • 在性能调优前，针对性地迁移SQL方言和数据类型
  • 采用分阶段切换，而非一次性全量替换

Workflow

工作流程

  1. Confirm whether live MotherDuck discovery is available.
  2. Classify the source system and the target serving pattern.
  3. Inspect the target-side MotherDuck layout if available.
  4. Pick the connection and ingestion path.
  5. Inventory incompatible SQL, functions, data types, and operational assumptions.
  6. Rebuild the analytical model in DuckDB SQL.
  7. Run source-vs-target validation.
  8. Cut over one workload at a time.
When this skill produces a native DuckDB (
md:
) connection, watermark it with 
custom_user_agent=agent-skills/2.2.0(harness-<harness>;llm-<llm>)
. If metadata is missing, fall back to 
harness-unknown
and 
llm-unknown
.
  1. 确认是否可进行实时MotherDuck发现。
  2. 对源系统和目标服务模式进行分类。
  3. 若目标端可用，检查MotherDuck的布局。
  4. 选择连接和数据导入路径。
  5. 梳理不兼容的SQL、函数、数据类型以及操作假设。
  6. 使用DuckDB SQL重建分析模型。
  7. 执行源端与目标端的验证。
  8. 逐个切换工作负载。
当本技能生成原生DuckDB（
md:
）连接时，需为其添加水印：
custom_user_agent=agent-skills/2.2.0(harness-<harness>;llm-<llm>)
。若元数据缺失，则使用
harness-unknown
和
llm-unknown
作为替代。

Output

输出

The output of this skill should be:
  • the target pattern
  • the migration sequence
  • the validation plan
  • the rollback path
  • the first cutover slice
If the caller explicitly asks for structured JSON, return raw JSON only with no Markdown fences or prose before/after it. This is mainly for automated tests, regression checks, or downstream tooling that needs a stable machine-readable shape. Normal human-facing use of the skill can stay in prose unless JSON is explicitly requested.
Use this exact top-level shape when JSON is requested:
json
{
  "summary": {},
  "assumptions": [],
  "implementation_plan": [],
  "validation_plan": [],
  "risks": []
}
本技能的输出应包含：
  • 目标模式
  • 迁移顺序
  • 验证方案
  • 回滚路径
  • 首个切换分片
如果调用方明确要求结构化JSON，则仅返回原始JSON，不要添加任何Markdown围栏或前后说明文字。这主要用于自动化测试、回归检查或需要稳定机器可读格式的下游工具。面向普通用户的场景下，除非明确要求JSON，否则可使用散文式输出。
当要求返回JSON时，请使用以下确切的顶层结构：
json
{
  "summary": {},
  "assumptions": [],
  "implementation_plan": [],
  "validation_plan": [],
  "risks": []
}

References

参考资料

  • references/MIGRATION_PLAYBOOK.md
    -- preserved detailed migration guidance that used to live in this skill
  • references/MIGRATION_VALIDATION.md
    -- validation checks and comparison helpers
  • references/MIGRATION_PLAYBOOK.md
    -- 保留了原本包含在本技能中的详细迁移指南
  • references/MIGRATION_VALIDATION.md
    -- 验证检查和对比辅助工具

Runnable Artifact

可运行工件

  • artifacts/migration_validation_example.py
    -- MotherDuck-backed Python example for source-vs-target validation and variance reporting
  • artifacts/migration_validation_example.ts
    -- TypeScript companion artifact with the same validation output contract
Run it with:
bash
uv run --with duckdb python skills/motherduck-migrate-to-motherduck/artifacts/migration_validation_example.py
Run the same validation flow against temporary MotherDuck databases:
bash
MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
uv run --with duckdb python skills/motherduck-migrate-to-motherduck/artifacts/migration_validation_example.py
Validate the TypeScript companion artifact:
bash
uv run scripts/test_typescript_artifacts.py
  • artifacts/migration_validation_example.py
    -- 基于MotherDuck的Python示例，用于源端与目标端的验证和差异报告
  • artifacts/migration_validation_example.ts
    -- TypeScript配套工件，具有相同的验证输出约定
运行方式：
bash
uv run --with duckdb python skills/motherduck-migrate-to-motherduck/artifacts/migration_validation_example.py
针对临时MotherDuck数据库运行相同的验证流程：
bash
MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
uv run --with duckdb python skills/motherduck-migrate-to-motherduck/artifacts/migration_validation_example.py
验证TypeScript配套工件：
bash
uv run scripts/test_typescript_artifacts.py

Related Skills

相关技能

  • motherduck-connect
    -- choose the connection path for the target system
  • motherduck-explore
    -- inspect the target-side MotherDuck workspace
  • motherduck-load-data
    -- bulk movement and raw landing patterns
  • motherduck-model-data
    -- shape the target analytical model
  • motherduck-query
    -- port and validate critical SQL
  • motherduck-ducklake
    -- only when open-table-format requirements are explicit
  • motherduck-connect
    -- 为目标系统选择连接路径
  • motherduck-explore
    -- 检查目标端MotherDuck工作区
  • motherduck-load-data
    -- 批量数据迁移和原始着陆模式
  • motherduck-model-data
    -- 构建目标分析模型
  • motherduck-query
    -- 迁移并验证关键SQL
  • motherduck-ducklake
    -- 仅在明确需要开放表格式时使用