How to Migrate Local DuckDB Files to MotherDuck

October 27, 2026

Migrating a local DuckDB file to MotherDuck means copying databases, schemas, and tables from an attached local file into a cloud database, then repointing views and application connection strings at md:. The copy command is COPY FROM DATABASE and takes seconds for small databases, minutes for large ones.

The mechanical part is easy. The part that bites is everything attached to the file: views that reference sibling databases, absolute paths to parquet files, Python code with hardcoded filenames, and a storage bill that did not exist before.

What should you audit before copying anything?

Run these against the local file and write down the answers.

  • Total size per schema. SELECT database_name, schema_name, SUM(total_blocks * block_size)/1e9 AS gb FROM duckdb_tables() GROUP BY 1,2; gives you the storage number MotherDuck will bill for.
  • View dependencies. duckdb_views() lists definitions; grep them for read_parquet(' and absolute paths.
  • External file reads in tables. Any table created as CREATE TABLE ... AS SELECT * FROM 'file.parquet' is materialised locally — the data goes to the cloud. A CREATE VIEW over a parquet file will break unless the file is also uploaded.
  • Extension usage. duckdb_extensions() — httpfs, postgres_scanner, and spatial all need to be available on the MotherDuck side, and some are restricted.

That last item catches people. A local file happily using spatial for geometry columns may need different types in the cloud.

How do you perform the copy?

The sequence in a single DuckDB session:

  1. ATTACH 'local.duckdb' AS src;
  2. ATTACH 'md:' AS md; — token from the environment.
  3. CREATE DATABASE md:analytics; if it does not exist.
  4. COPY FROM DATABASE src TO md:analytics;

The copy brings schemas, tables, and their data, but not views. Views must be recreated against the cloud database. Run duckdb_views() on the source, dump the definitions, and recreate them by hand with the target qualified.

For a large database, run the copy in chunks by schema — COPY FROM DATABASE works per database, so create separate cloud databases per source schema cluster if a single copy times out.

How do you rewrite views and code?

Every view that says FROM src.events must become FROM analytics.events. Two practical approaches:

Approach When
Recreate views in cloud with qualified names Always, as the baseline
Search and replace in a repo of .sql files If views are maintained in version control

For Python, the change is usually one line: the connection string. Everything else that used con.sql('SELECT ...') keeps working, as long as the query references the cloud database name instead of the local attachment alias.

Watch for relative paths. read_parquet('data/*.parquet') resolves relative to the process working directory locally. In the cloud there is no such directory — those need to become absolute object-storage URLs or the files need uploading.

What will it cost?

MotherDuck bills storage per GB-month plus compute by query volume, tiered by plan. A 50GB local DuckDB file becomes 50GB of cloud storage. In many cases that file contains three years of data where 12 months would do.

Before you copy, decide what not to copy. Old partitions, scratch tables, and backups-of-backups are common. Copy the schemas you need, leave the rest in the local file as an archive. Nobody regrets a smaller warehouse migration.

How do you verify the copy worked?

Three checks, in order:

  1. Row counts per table. Query duckdb_tables() on both sides and compare estimated_size. Counts may differ by small amounts on tables with in-flight writes; large differences mean a failed copy.
  2. Spot-check aggregates. Run SELECT count(*), sum(amount) FROM a few of your largest tables on both sides.
  3. Run your real queries. Not the toy ones. Take the five queries your team actually runs daily and execute them against md: , timing each. If one is dramatically slower, the table probably needs a different sort order in the cloud — DuckDB’s file layout does not transfer.

What breaks after migration

  • Views referencing src. Most common. Fails with a clear error, at least.
  • Concurrent writes. Local usage is single-user; once shared, two people writing the same table conflicts.
  • Long-running queries on the free tier. Query volume limits bite at a level you cannot predict from local testing.
  • Extension version drift. Local DuckDB version and MotherDuck’s supported version differ; pin your local client to a version that matches.

Key Takeaways

  • Migrate with ATTACH both sides then COPY FROM DATABASE; views are not copied and must be recreated.
  • Audit storage per schema first — everything you copy is billed monthly.
  • Absolute or relative parquet paths in tables and views break in the cloud; upload the files or convert to views over object storage.
  • Verify with row counts, spot-check aggregates, and the five queries your team actually runs.
  • Pin your local DuckDB client version to match MotherDuck’s supported version to avoid extension drift.