MotherDuck

Availability

Core Standard Plus Pro Enterprise Flex Self-Managed Enterprise PyAirbyte

Support Level

Airbyte

Connector Version

0.2.3 (last updated 4 months ago)

CDK Version

6.61.6

Sync Success Rate

High

Usage Rate

High

Definition ID

042ee9b5-eb98-4e99-a4e5-3f0d573bee66

Overview

The MotherDuck destination writes each Airbyte stream to a table in a MotherDuck database. It connects through the DuckDB client and supports MotherDuck-hosted databases and local DuckDB files.

caution

Local DuckDB files aren't persistent in Airbyte Cloud. Use a MotherDuck-hosted database in Airbyte Cloud.

Prerequisites

To write to MotherDuck, you need:

• A MotherDuck account.
• A Read/Write access token. Read Scaling tokens are read-only and don't work with this destination.
• The name of a MotherDuck database that the token's account can write to.

For automated production workloads, you can use a MotherDuck service account with a Read/Write token. An organization Admin must create and configure service accounts.

Set up the destination

1. In MotherDuck, open your organization settings and select Create token.

2. Select Read/Write, configure an expiration if needed, and copy the token.

3. In Airbyte, create a MotherDuck destination.

4. Enter the following values:

   • MotherDuck Access Token: Enter the Read/Write token you created.
   • Destination DB: Enter md:<database-name>, for example md:analytics. Enter md: to use MotherDuck's default my_db database.

   Don't include the token in the connection string. Tokens in connection strings might appear in execution logs.

   • Schema Name: Enter the schema where Airbyte creates destination tables. The default is main.

5. Select Set up destination and wait for the connection test to complete.

Destinations V2

This destination implements Destinations V2, which writes source fields directly to typed destination columns.

Learn more in the Typing and deduping guide.

Supported sync modes

Sync mode	Supported?
Full Refresh - Overwrite	Yes
Full Refresh - Append	Yes
Full Refresh - Overwrite + Deduped	Yes
Incremental Sync - Append	Yes
Incremental Sync - Append + Deduped	Yes

Output schema

Each table contains at least the following columns:

• _airbyte_raw_id: A UUID assigned by Airbyte to each record.
• _airbyte_extracted_at: The time Airbyte extracted the record from the source.
• _airbyte_meta: A JSON object containing record metadata.

The destination also creates typed columns for fields in each stream's JSON schema.

Table and column names are normalized before Airbyte creates them:

• Letters are converted to lowercase.
• Whitespace and most special characters are replaced with underscores.
• Unicode letters and numbers are preserved.
• Names that start with a digit receive an underscore prefix.

Working with local DuckDB files

In Self-Managed Airbyte, you can enter a local .duckdb path for Destination DB. Airbyte normalizes the path under /local, which maps to the host directory configured by LOCAL_ROOT. The default host directory is /tmp/airbyte_local.

For example, /local/destination.duckdb maps to /tmp/airbyte_local/destination.duckdb with the default LOCAL_ROOT.

If you only need local DuckDB files, consider using the DuckDB destination.

Limitations

• The connector writes all selected streams to the configured Schema Name. It doesn't map source namespaces to separate MotherDuck schemas.
• Stream names must be unique after normalization, including streams from different source namespaces.
• Field names in a record must be unique after normalization. If fields collide, such as userId and userid, the connector skips the record.
• Data generations aren't supported.

Reference

Config fields reference

Field

Type

Property name

string

motherduck_api_key

string

destination_path

string

schema

Changelog

Expand to review

Version	Date	Pull Request	Subject
0.2.4	2026-07-14	81511	Fix silent data loss on multi-stream syncs by no longer discarding other streams' buffered records when one stream is flushed
0.2.3	2026-03-31	75645	Bump version to force registry update for supportLevel change to certified
0.2.2	2026-03-17	70438	Fix for camelCase columns being NULL
0.2.1	2026-01-29	70999	Fix for empty STRUCTs
0.2.0	2026-01-07	71063	Upgrade DuckDB to v1.4.2 and duckdb-engine to v0.17.0
0.1.26	2025-10-21	68338	Update dependencies
0.1.25	2025-10-14	67952	Update dependencies
0.1.24	2025-10-07	66822	Update dependencies
0.1.23	2025-08-08	64161	feat: allow null values in primary key fields. Primary keys are no longer declared as table constraints.
0.1.22	2025-07-22	63714	fix(destination-motherduck): handle special characters in stream name when creating tables
0.1.21	2025-07-22	63709	fix: resolve error "Can't find the home directory at '/nonexistent'" #63710
0.1.20	2025-07-07	62133	fix: when primary_key is not defined in the catalog, use source_defined_primary_key if available
n/a	2025-06-26	48673	Update dependencies
0.1.19	2025-05-28	60906	Allow Unicode characters in database/table names
0.1.18	2025-03-01	54737	Update airbyte-cdk to ^6.0.0 in destination-motherduck
0.1.17	2024-12-26	50425	Fix bug overwrite write method not saving all batches
0.1.16	2024-12-06	48562	Improved handling of config parameters during SQL engine creation.
0.1.15	2024-11-09	48405	Updated docs and hover text for schema, API key, and database name.
0.1.14	2024-10-30	48006	Fix bug in _flush_buffer, explicitly register DataFrame before inserting
0.1.13	2024-10-30	47969	Preserve Platform-generated id in state messages.
0.1.12	2024-10-30	47987	Disable PyPi publish.
0.1.11	2024-10-30	47979	Rename package.
0.1.10	2024-10-29	47958	Add state counts and other fixes.
0.1.9	2024-10-29	47950	Fix bug: add double quotes to column names that are reserved keywords.
0.1.8	2024-10-29	47952	Fix: Add max batch size for loads.
0.1.7	2024-10-29	47706	Fix bug: incorrect column names were used to create new stream table when using multiple streams.
0.1.6	2024-10-29	47821	Update dependencies
0.1.5	2024-10-28	47694	Resolve write failures, move processor classes into the connector.
0.1.4	2024-10-28	47688	Use new destination table name format, explicitly insert PyArrow table columns by name and add debug info for column mismatches.
0.1.3	2024-10-23	47315	Fix bug causing MotherDuck API key to not be correctly passed to the engine.
0.1.2	2024-10-23	47315	Use saas_only mode during connection check to reduce ram usage.
0.1.1	2024-10-23	47312	Fix: generate new unique destination ID
0.1.0	2024-10-23	46904	New MotherDuck destination