# Connection string parameters > Reference for MotherDuck connection string parameters, including attach_mode, saas_mode, session_name, dbinstance_inactivity_ttl, and connection_timeout. You can configure a MotherDuck connection by appending parameters to the connection string, separated by `&`: ```text md:?=&= ``` ## Parameters | Parameter | Values | Default | Description | | --- | --- | --- | --- | | [`motherduck_token`](#motherduck_token) | An access token | None | Authenticates the connection. | | [`attach_mode`](#attach_mode) | `workspace`, `single` | `workspace` | Attaches your full workspace, or scopes the connection to a single database. | | [`saas_mode`](#saas_mode) | `true`, `false` | `false` | Restricts MotherDuck's ability to interact with your local environment. | | [`session_name`](#session_name) | Any string | None | Names the session, and routes each end user to a dedicated duckling with read scaling. | | [`dbinstance_inactivity_ttl`](#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`](#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 ```bash duckdb 'md:my_db?attach_mode=single&session_name=user1' ``` ### Python ```python import duckdb conn = duckdb.connect("md:my_db?attach_mode=single&session_name=user1") ``` ### Node.js ```javascript 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: ```sql 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](/integrations/language-apis-and-drivers/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](/sql-reference/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/?options=--attach_mode=single`. ### `motherduck_token` Authenticates the connection with a MotherDuck [access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md#authentication-using-an-access-token). If the `motherduck_token` environment variable is set, clients use it automatically. ```bash duckdb 'md:my_db?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](/key-tasks/authenticating-and-connecting-to-motherduck/attach-modes/attach-modes.md). ```bash 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](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md#authentication-using-saas-mode). ```bash duckdb 'md:my_db?motherduck_token=&saas_mode=true' ``` ### `session_name` Gives your session a name. The name appears in the `SESSION_NAME` column of [query history](/sql-reference/motherduck-sql-reference/md_information_schema/query_history/), making it easy to identify and group queries. When you connect with a [read scaling token](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/read-scaling.mdx), 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](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck.md#session-names) for usage, and [Session affinity and routing](/concepts/scaling-patterns/#session-affinity-and-routing) for when to use it and how routing works. ```bash 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](https://duckdb.org/docs/stable/sql/functions/datepart.html#part-specifiers-usable-as-date-part-specifiers-and-in-intervals), such as `30s`, `5m`, or `1h`. See [Setting custom database instance cache time (TTL)](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck.md#setting-custom-database-instance-cache-time-ttl) for how instance caching works. ```bash 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](https://duckdb.org/docs/stable/sql/functions/datepart.html#part-specifiers-usable-as-date-part-specifiers-and-in-intervals), such as `30s` or `2m`. ```bash 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: ```text 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](/sql-reference/postgres-endpoint) or the [Wasm client](/getting-started/interfaces/client-apis/other/wasm). 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. --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fconnection-string-parameters%2F&page_title=Connection%20string%20parameters&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.