motherduck-migrate-to-motherduck
Plan a migration onto MotherDuck. Use when moving from Snowflake, BigQuery, Redshift, PostgreSQL, dbt-heavy stacks, or lakehouse tooling and the key decisions are target pattern, cutover slices, source-vs-target validation, rollback, and native-versus-DuckLake posture.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- motherduck-migrate-to-motherduck
- license
- MIT
- description
- Plan a migration onto MotherDuck. Use when moving from Snowflake, BigQuery, Redshift, PostgreSQL, dbt-heavy stacks, or lakehouse tooling and the key decisions are target pattern, cutover slices, source-vs-target validation, rollback, and native-versus-DuckLake posture.
02 资源文件 4
- 脚本artifacts/migration_validation_example.py2.1 KB
- 脚本artifacts/migration_validation_example.ts2.7 KB
- 参考文档references/MIGRATION_PLAYBOOK.md11.8 KB
- 参考文档references/MIGRATION_VALIDATION.md14.3 KB
03 SKILL.md 正文
Migrate to 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.
Start Here: Is a MotherDuck Server Active?
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.
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.
Migration Defaults
- native MotherDuck storage first
pg_duckdbwhen 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
Workflow
- Confirm whether live MotherDuck discovery is available.
- Classify the source system and the target serving pattern.
- Inspect the target-side MotherDuck layout if available.
- Pick the connection and ingestion path.
- Inventory incompatible SQL, functions, data types, and operational assumptions.
- Rebuild the analytical model in DuckDB SQL.
- Run source-vs-target validation.
- 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.3.0(harness-<harness>;llm-<llm>). If metadata is missing, fall back to harness-unknown and 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:
{
"summary": {},
"assumptions": [],
"implementation_plan": [],
"validation_plan": [],
"risks": []
}
References
Read these as reference, not as scripts to execute:
references/MIGRATION_PLAYBOOK.md-- target-pattern selection, migration decision matrix, DuckLake posture, and source-specific questions (Snowflake, Redshift, Postgres, dbt, lakehouse)references/MIGRATION_VALIDATION.md-- copy-adaptable validation SQL (row counts, metrics withpct_variance, new/deleted/changed records) and a Python orchestrator
Runnable Artifact
artifacts/migration_validation_example.py-- MotherDuck-backed Python example for source-vs-target validation and variance reportingartifacts/migration_validation_example.ts-- TypeScript companion artifact with the same validation output contract
Run it with:
uv run --with duckdb python skills/motherduck-migrate-to-motherduck/artifacts/migration_validation_example.py
Run the same validation flow against temporary MotherDuck databases:
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:
uv run scripts/test_typescript_artifacts.py
Related Skills
motherduck-connect-- choose the connection path for the target systemmotherduck-explore-- inspect the target-side MotherDuck workspacemotherduck-load-data-- bulk movement and raw landing patternsmotherduck-model-data-- shape the target analytical modelmotherduck-query-- port and validate critical SQLmotherduck-ducklake-- only when open-table-format requirements are explicit
04 同仓库更多 Skills
pydantic-ai-harness
Extend Pydantic AI agents with batteries-included capabilities from pydantic-ai-harness -- currently Code Mode, which collapses many tool calls into one sandboxed Python execution. Use when the user mentions pydantic-ai-harness, CodeMode, Monty, code mode, or tool sandboxing, when they want an agent to run agent-written Python, or when a Pydantic AI agent would benefit from orchestrating multiple tool calls in a single sandboxed script.
building-pydantic-ai-agents
Build AI agents with Pydantic AI — tools, capabilities (including on-demand loading), structured output, streaming, testing, and multi-agent patterns. Use when the user mentions Pydantic AI, imports pydantic_ai, or asks to build an AI agent, add tools/capabilities, defer capability loading, stream output, define agents from YAML, or test agent behavior.
motherduck-share-data
Create and manage MotherDuck data shares for zero-copy, read-only data distribution. Use whenever someone wants to share a database with team members, another organization, or the public — covers CREATE SHARE, access/visibility/update modes, GRANT READ ON SHARE, attaching share URLs, UPDATE SHARE, and REFRESH DATABASE.
motherduck-security-governance
Explain MotherDuck security, governance, and access-control patterns. Use for any question about SOC 2, GDPR, compliance, data residency, regions, SSO, service accounts, token handling, tenant isolation, sharing boundaries, snapshots and recovery, or governance posture — including when a security_compliance_owner, technical_owner, or application_builder is evaluating MotherDuck.
motherduck-rest-api
MotherDuck REST API control-plane reference. Use when calling api.motherduck.com to provision service accounts, create, list, rotate, or revoke access tokens, configure Duckling instance sizes and read scaling, inspect active accounts, or mint Dive embed sessions. Not for SQL or data-plane query work.
motherduck-query
Execute DuckDB SQL queries against MotherDuck databases. Use when running analytics, aggregations, transformations, or any SQL operation. Covers query best practices, CTEs, window functions, QUALIFY, and performance optimization.