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.

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".

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'