MotherDuck

Available as a beta from 0.33.0. A MotherDuck target loads into a MotherDuck database through DuckDB’s md: connection, with the same SQL, types and write strategies as a DuckDB target. It’s in beta, and it hasn’t been tested against a live MotherDuck account.

DuckDB 2.0 isn’t supported by MotherDuck yet

SQLLoad bundles DuckDB 2.0. MotherDuck doesn’t accept DuckDB 2.0 clients yet: its extension supports DuckDB up to 1.5.6 and refuses to load on 2.0. Until MotherDuck supports DuckDB 2.0, a MotherDuck target can’t connect. sqlload debug, plan and load report MotherDuck’s own message:

$ sqlload debug
fail  target shop  MotherDuck: cannot open md:shop: MotherDuck doesn't accept the DuckDB version this SQLLoad bundles yet, so no SQLLoad release can connect to it until it does. MotherDuck says: Your DuckDB version (v2.0.0) is not yet supported by MotherDuck. …

MotherDuck lists the client versions it supports in duckdb-versions.json.

Connection

[connections.shop]
kind = "motherduck"
database = "shop"
token = "${ENV:MOTHERDUCK_TOKEN}"

[targets.shop]
connection = "shop"
loader_schema = "raw"

Key	Meaning
database	The MotherDuck database, with or without md:. Required, here or in the target. It can’t hold the token.
token	A MotherDuck access token. Use ${ENV:NAME}. Default: the motherduck_token or MOTHERDUCK_TOKEN environment variable.

A target’s database overrides the connection’s, so one connection can serve, say, a shop_dev and a shop database. MotherDuck attaches the account’s other databases too, so SQLLoad names every table with its database, and a target that names no database is refused. Without a token SQLLoad refuses the connection rather than wait for MotherDuck’s browser sign-in. A duckdb connection refuses an md: path; use kind = "motherduck". The first connection installs MotherDuck’s DuckDB extension into ~/.duckdb, which needs the network once.

How data arrives

Every row reaches MotherDuck as Arrow batches appended inside the batch’s transaction, as on DuckDB. Unlike DuckDB, MotherDuck never reads files itself: files sources, including Parquet in S3 or a local folder, and a Snowflake source’s unloaded files are read by SQLLoad and appended as Arrow. plan names that route for every table.

append, merge, delete_insert and replace run the same statements as on DuckDB.

Limits

• Not tested against a live MotherDuck account. The tests cover the connection settings, the refusals and the route; the statements are DuckDB’s, tested on DuckDB.
• Each table loads on its own connection, as on DuckDB. Whether MotherDuck runs concurrent schema changes and transactions across those connections exactly as local DuckDB does is untested.