Connection string parameters

You can configure a MotherDuck connection by appending parameters to the connection string, separated by &:

md:<database_name>?<parameter>=<value>&=<value>

Parameters

Parameter	Values	Default	Description
motherduck_token	An access token	None	Authenticates the connection.
attach_mode	workspace, single	workspace	Attaches your full workspace, or scopes the connection to a single database.
saas_mode	true, false	false	Restricts MotherDuck's ability to interact with your local environment.
session_name	Any string	None	Names the session, and routes each end user to a dedicated duckling with read scaling.
dbinstance_inactivity_ttl	An interval such as 30s, 5m, 1h	15m	Sets how long a database instance stays cached after the last connection is closed.
connection_timeout	An interval such as 30s, 2m	None	Fails the connection if opening it takes longer than the interval.

Passing parameters

Connection string parameters work across DuckDB clients:

CLI

duckdb 'md:my_db?attach_mode=single&session_name=user1'

Python

import duckdb

conn = duckdb.connect("md:my_db?attach_mode=single&session_name=user1")

Node.js

import { DuckDBInstance } from '@duckdb/node-api';

const instance = await DuckDBInstance.fromCache('md:my_db?attach_mode=single&session_name=user1');
const conn = await instance.connect();

Every parameter is also available as a DuckDB configuration option under its motherduck_-prefixed name. You can set it in a client's configuration dictionary, or with SET before you connect to MotherDuck:

SET motherduck_attach_mode = 'single';
SET motherduck_session_name = 'user1';
ATTACH 'md:my_db';

note

In the connection string, both the short name (attach_mode) and the prefixed name (motherduck_attach_mode) work. In configuration dictionaries, connection properties, and SET statements, use the prefixed name. Some clients, like the Go driver, parse connection string parameters into a configuration dictionary and therefore require the prefixed names in the connection string as well.

When connecting through the Postgres endpoint, pass parameters as Postgres startup options instead, for example PGOPTIONS="--attach_mode=single", or options=--attach_mode=single in a libpq connection string such as postgresql://postgres:$MOTHERDUCK_TOKEN@pg.us-east-1-aws.motherduck.com:5432/<database_name>?options=--attach_mode=single.

motherduck_token

Authenticates the connection with a MotherDuck access token. If the motherduck_token environment variable is set, clients use it automatically.

duckdb 'md:my_db?motherduck_token=<your_motherduck_token>'

attach_mode

By default, MotherDuck connects in workspace mode: it attaches every database in your saved workspace and remembers attachment changes for your next session. Set attach_mode=single for a one-time session scoped to a single database, where attachment changes aren't saved. Single mode requires a database name in the connection string. For a full comparison of the two modes, see Attach modes.

duckdb 'md:my_database?attach_mode=single'

saas_mode

Set saas_mode=true to restrict MotherDuck's ability to interact with your local environment. SaaS mode disables reading and writing local files and local DuckDB databases, installing or loading extensions, and changing DuckDB configuration. This is useful for third-party tools that host DuckDB themselves and need additional security controls. See Authentication using SaaS mode.

duckdb 'md:my_db?motherduck_token=<your_motherduck_token>&saas_mode=true'

session_name

Gives your session a name. The name appears in the SESSION_NAME column of query history, making it easy to identify and group queries. When you connect with a read scaling token, passing a session_name lets each end user get a dedicated duckling: queries with the same session name are routed to the same duckling, even when they originate from different services. See Session names for usage, and Session affinity and routing for when to use it and how routing works.

duckdb 'md:my_db?session_name=user1'

note

The older session_hint parameter still works as a deprecated alias for session_name.

dbinstance_inactivity_ttl

Sets how long a cached database instance is reused after the last connection to it is closed. The default is 15 minutes. Accepts any valid DuckDB interval part specifier, such as 30s, 5m, or 1h. See Setting custom database instance cache time (TTL) for how instance caching works.

duckdb 'md:my_db?dbinstance_inactivity_ttl=1h'

connection_timeout

Fails the connection if opening a MotherDuck database takes longer than the interval. Accepts any valid DuckDB interval part specifier, such as 30s or 2m.

duckdb 'md:my_db?connection_timeout=30s'

The timeout covers the three steps of opening md:: fetching a short-lived token, downloading the welcome pack, and attaching the first database.

Without it, the only timeout is on connectivity: network failures during those steps are retried for up to 30 seconds, and everything else waits indefinitely, including a Duckling that is still starting. Setting connection_timeout puts a deadline on all three steps, and the same value replaces that 30-second retry budget. Use it when a caller needs a bounded startup, such as a web server or a job runner that should fail over rather than block. When the deadline passes, the connection fails with:

Connection Error: Timed out connecting to MotherDuck after 30000ms. Use 'motherduck_connection_timeout' to change the timeout.

note

The value is read once, while the connection is being opened. Set it in the connection string, through the MOTHERDUCK_CONNECTION_TIMEOUT environment variable, or with SET motherduck_connection_timeout = '30s' before the first ATTACH 'md:'. Running SET motherduck_connection_timeout on a connection that already reached MotherDuck fails.

The timeout applies to DuckDB clients that load the MotherDuck extension, not to the Postgres endpoint or the Wasm client. It bounds opening md: as the database. Attaching with ATTACH 'md:' from an already-open local DuckDB still uses the timeout as its network retry budget, but a wait on a Duckling that is still starting isn't interrupted.