# Connection string parameters > Reference for MotherDuck connection string parameters, including attach_mode, saas_mode, session_name, and dbinstance_inactivity_ttl. 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. | ## 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"`. ### `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' ``` --- ## 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.