ADBC Driver for MotherDuck¶
Driver Version v0.1.0-alpha.1 Release Date 2026-11-16 Tested With MotherDuck latest
Warning
This is documentation for a prerelease version.
This driver provides access to MotherDuck , a serverless cloud data warehouse built on DuckDB.
Installation & Quickstart¶
The driver can be installed with dbc :
dbc install --pre motherduck
Connecting¶
The driver connects to MotherDuck’s PostgreSQL protocol endpoint and uses your
MotherDuck token as the password. Set the token in the MOTHERDUCK_TOKEN
environment variable, which keeps it out of connection strings and logs, and
give the database to connect to and your account’s region. Find your region
with md_user_info().
from adbc_driver_manager import dbapi
with dbapi.connect(
driver="motherduck",
db_kwargs={
"uri": "motherduck:///my_db",
"motherduck.region": "us-east-1",
},
) as conn:
with conn.cursor() as cursor:
cursor.execute("SELECT 42")
print(cursor.fetch_arrow_table())
The region sets the host, so the URI can leave it out. us-east-1 connects to
pg.us-east-1-aws.motherduck.com. Without the option, put the host in the URI
instead: motherduck://pg.us-east-1-aws.motherduck.com/my_db.
The URI’s scheme names the driver, so an ADBC driver manager can pick this
driver from a motherduck:// URI alone. Pass the URI in place of the driver
name:
from adbc_driver_manager import dbapi
with dbapi.connect(
"motherduck:///my_db",
db_kwargs={"motherduck.region": "us-east-1"},
) as conn:
...
A driver manager matches the scheme against the driver’s name, so it doesn’t
find the driver from an md:// or md: URI. When you use those, name the
driver as well, with driver="motherduck".
By default the driver connects in single attach mode, which attaches only the
database named in the connection. To work across every database in the account,
connect to md: and set motherduck.attach_mode to workspace.
Connection String Format¶
The URI is a motherduck:// URI:
motherduck://[USER[:TOKEN]@][HOST[:PORT]]/DATABASE[?PARAMETER=VALUE&...]
Two short forms are accepted: md://, with the same syntax, and DuckDB’s
md:[DATABASE][?PARAMETER=VALUE&...], which has no host, so set
motherduck.region too. md: alone is the workspace, the same as
md%3A as the database. The driver accepts no other scheme, and the scheme is
lowercase.
Components:
DATABASE: the MotherDuck database to connect to, ormd:(writtenmd%3Ain a URI) inworkspaceattach mode.HOSTandPORT: the endpoint, such aspg.us-east-1-aws.motherduck.com. Optional whenmotherduck.regionis set; the port is then 5432 unless the URI sets one.USER: optional. The default ispostgres, which MotherDuck expects.TOKEN: the MotherDuck token. PreferMOTHERDUCK_TOKENor a database option to putting it in the URI.
The query takes the driver options by name, such as
motherduck:///my_db?motherduck.region=us-east-1&motherduck.connect_timeout=10.
Percent-encode values; an empty value is unset. Every option except
motherduck.token can be set this way (a token doesn’t belong in a query, which
is more likely to be logged than the URI’s password), and an option set on the
database takes precedence over the URI’s. Any other query parameter, including
the PostgreSQL settings below, is rejected with INVALID_ARGUMENT.
Authentication¶
The driver takes the token from the first of these that is set:
The
passworddatabase option, or its aliasmotherduck.token.The password in the URI.
The
MOTHERDUCK_TOKENenvironment variable.
Without a token, connecting fails with UNAUTHENTICATED.
Driver Options¶
Option |
Level |
Description |
|---|---|---|
|
Database |
|
|
Database |
The MotherDuck region, such as |
|
Database |
MotherDuck’s session name , which routes connections with the same name to the same replica under read scaling. |
|
Database |
Your application’s name. The driver adds |
|
Database |
The longest time to wait while connecting, in whole seconds, as a string or an integer. Unset by default, which sets no timeout of its own. |
|
Database |
The schema every new connection starts in. Connecting fails if it doesn’t exist. |
|
Connection |
Changes a single connection’s schema, in its current database. |
|
Database |
Alias for the standard |
|
Database |
Optional; unset by default, which uses the OS’s trusted CA certificates. A PEM file of root certificates to verify the server with instead, such as a corporate CA bundle. Uses |
|
Database |
Optional. |
Differences from the PostgreSQL Driver¶
Applications may have used the ADBC PostgreSQL driver
(adbc_driver_postgresql) to connect to MotherDuck’s PostgreSQL protocol
endpoint. This driver builds on that implementation with connection handling
and metadata support adapted for MotherDuck. If you are migrating an existing
application from the PostgreSQL driver, review the differences below:
A separate driver. Load
motherduck, notpostgresql.MotherDuck only. The driver connects only to MotherDuck’s PostgreSQL endpoint. Plain PostgreSQL servers aren’t supported, because every connection sets
attach_mode.Connection URI. The URI must use the
motherduck://scheme (ormd://, ormd:), notpostgresql://.Connection settings. The MotherDuck token is the password, and the user defaults to
postgres.PGUSER,PGPASSWORD,PGAPPNAME, and password files are never used, andsslmodedefaults toverify-full. Themotherduck.*options have no PostgreSQL equivalent.Options that differ.
adbc.postgresql.use_copydefaults tofalse, and setting it totruefails.adbc.postgresql.type_resolver_modeis accepted and ignored.adbc.connection.db_schemanames a schema, not an arbitrarysearch_path; useUSE <database>to change databases.Results and errors. DML and DDL return an empty stream, and
rows_affectedforUPDATEandDELETEis the number of rows changed. Data conversion errors map toINTERNALinstead ofINVALID_DATA.Missing features. Bulk ingest, COPY result reads, statistics, and others don’t work; the feature table below shows what is supported.
PostgreSQL settings are not supported¶
The PostgreSQL client library has additional settings that are not part of this driver’s supported interface. They may change or stop working in a future version, including a version that no longer uses that library:
URI query parameters, such as
sslmode,sslrootcert,optionsandservice. These are rejected: the URI’s query takes only themotherduck.*options.PostgreSQL environment variables, such as
PGHOST,PGPORT,PGSSLMODE,PGSSLROOTCERTandPGOPTIONS, and files such as~/.pg_service.conf. Some are read today and some are ignored.
Use the motherduck.* options and the standard ADBC options instead,
such as motherduck.tls_root_cert_path and motherduck.tls_verify
for certificate verification. By default the driver verifies the server’s
certificate with the OS’s trusted CA certificates (or SSL_CERT_FILE), so most
connections need no TLS settings. If the driver finds no CA certificates,
connecting fails; install the OS’s CA certificates (such as the
ca-certificates package) or use one of those options.
Feature & Type Support¶
| Feature | MotherDuck | |
|---|---|---|
| Bind Parameters | ✅ | |
| Bulk Ingestion | Create | ❌ |
| Append | ❌ | |
| Create/Append | ❌ | |
| Replace | ❌ | |
| Temporary Table | ❌ | |
| Target Catalog | ❌ | |
| Target Schema | ❌ | |
| Non-nullable fields are marked NOT NULL | ❌ | |
| Catalog (GetObjects) | depth=catalogs | ✅ |
| depth=db_schemas | ✅ | |
| depth=tables | ❌ | |
| depth=columns (all) | ❌ | |
| Get Parameter Schema | ✅ | |
| Get Table Schema | ✅ | |
| Prepared Statements | ✅ | |
| Transactions | ✅ | |
Types¶
Database to Arrow¶
| Database Type | MotherDuck |
|---|---|
|
TIMESTAMP(0) |
timestamp[us] |
|
TIMESTAMP(p) (1 <= p <= 3) |
timestamp[us] |
|
TIMESTAMP(p) (4 <= p <= 6) |
timestamp[us] |
|
bigint |
int64 |
|
bool |
bool |
|
bytea |
binary |
|
date |
date32[day] |
|
double precision |
double |
|
integer |
int32 |
|
json |
extension<arrow.json> |
|
numeric |
extension<arrow.opaque[storage_type=string, type_name=numeric, vendor_name=PostgreSQL]> |
|
real |
float |
|
smallint |
int16 |
|
text |
string |
|
time |
time64[us] |
|
timestamp |
timestamp[us] |
|
timestamptz |
timestamp[us] (with time zone) |
|
uuid |
extension<arrow.uuid> |
Arrow to Database¶
| Arrow Type | MotherDuck Type | |
|---|---|---|
| Bind | Ingest | |
|
binary |
bytea |
❌ |
|
binary_view |
bytea |
❌ |
|
bool |
bool |
❌ |
|
date32[day] |
date |
❌ |
|
decimal128 |
numeric |
❌ |
|
double |
double precision |
❌ |
|
extension<arrow.uuid> |
uuid |
❌ |
|
fixed_size_binary |
bytea |
❌ |
|
float |
real |
❌ |
|
halffloat |
real |
(NA/not tested) |
|
int16 |
smallint |
❌ |
|
int32 |
integer |
❌ |
|
int64 |
bigint |
❌ |
|
large_binary |
bytea |
❌ |
|
large_string |
text |
❌ |
|
list |
(NA/not tested) |
❌ |
|
string |
text |
❌ |
|
string_view |
text |
❌ |
|
time32[ms] |
time |
❌ |
|
time32[s] |
time |
❌ |
|
time64[ns] |
time |
❌ |
|
time64[us] |
time |
❌ |
|
timestamp[ms] |
timestamp |
❌ |
|
timestamp[ms] (with time zone) |
timestamptz |
❌ |
|
timestamp[ns] |
duckdb_timestamp_ns |
❌ |
|
timestamp[ns] (with time zone) |
timestamptz |
❌ |
|
timestamp[s] |
timestamp |
❌ |
|
timestamp[s] (with time zone) |
timestamptz |
❌ |
|
timestamp[us] |
timestamp |
❌ |
|
timestamp[us] (with time zone) |
timestamptz |
❌ |
Compatibility¶
This driver was tested against the MotherDuck cloud service.