motherduck
The MotherDuck sink (alpha) uses DuckDB’s native MotherDuck extension and
bulk appender. It does not use the PostgreSQL wire endpoint.
Configuration
The sink opens
md:<database> with the token as DuckDB’s
motherduck_token option and creates the configured schema if it does not
exist. It prefers batches of 100,000 rows or 64 MiB. Use one sink connection
per configured snapshot worker; a DuckDB connection is never shared between
concurrent writes.
Supported write modes
Every table is fully qualified as
"database"."schema"."table". Replace promotes its staging table in a
transaction. Upsert creates a primary key from the resolved write-policy keys
and transactionally merges a keyless staging table on commit. An existing
destination whose primary key does not match those keys, such as a table an
earlier append run created, is refused when the run starts rather than
migrated. Append writes directly to the destination.
Type mapping
New tables preserve source nullability with
NOT NULL. Schema evolution is
additive. DuckDB does not currently support constraints on ADD COLUMN, so a
new non-null source field added to an existing destination is added without the
constraint.
Runtime requirements
The sink links DuckDB natively, so it is available only in the worker’s-libc image tag, which ships with the MotherDuck extension installed. The
standalone binary and the CLI do not include it.
Failure behavior
Abort removes replace and upsert staging tables. It cannot undo append rows
already flushed to a live table. The configured token is passed only as a
DuckDB option and is never included in receipts or error context by Filament.