# Attach Modes > Understand Workspace and Single attach modes ## MotherDuck attach modes: workspace and single modes This guide explains MotherDuck's two connection modes: **workspace** and **single**. Workspace mode is designed for working with multiple databases persistently across sessions, while single mode uses a non-persistent, isolated session that does not reuse your saved workspace. Your attach mode decides which MotherDuck databases a connection starts with, and whether changes to that list are saved for your next session. While both modes let you `ATTACH` more databases after you connect, they differ in whether those attachments are saved for the next time you connect. :::tip **TL;DR** Workspace mode is "my environment": use it for personal work in the MotherDuck UI, the DuckDB CLI or your AI agent. Single mode is "just this database, for this job": use it for service accounts, automated workflows, and BI tools. ::: | | Workspace mode (default) | Single mode | | --------------------------------- | ------------------------------------------------- | ---------------------------------------------- | | Connection string | `md:` or `md:` | `md:?attach_mode=single` | | What's attached when you connect | Every database in your saved workspace | Only the database you name | | Attaching more databases later | Yes, and they're saved for future sessions | Yes, but they last only for this session | | Detaching a database | Saved for future sessions | Lasts only for this session | | Other open workspace connections | Stay in sync with this one | Unaffected | | Best for | Personal work across sessions | Service accounts, automated workflows, and BI tools | ### Workspace mode Workspace mode is the default. It attaches every database in your saved workspace, the same list you see in the MotherDuck UI. * When you attach or detach a database, that change is saved and restored the next time you connect. * Parallel workspace-mode connections stay in sync. For example, detaching a database in one client detaches it in every other client connected in workspace mode. * `md:` still attaches your whole workspace. It only makes `` the active database. * The MotherDuck UI always connects in workspace mode. ### Single mode Single mode starts a temporary, isolated session with one database. It doesn't load your saved workspace and doesn't change it. * After you connect, you can attach more databases, including databases shared with you. For example, start with your own database, then attach a share: ```sql ATTACH 'md:_share//'; ``` * Those attachments, and any detachments, last only for this session. They aren't saved to your workspace, so they're gone the next time you connect. * It doesn't affect the attachments of other connections to MotherDuck. * It keeps the catalog small, which helps automated workflows and BI tools that only support one attached database at a time. * You must name the initial database. `md:?attach_mode=single` isn't allowed. ### How the mode is set The first MotherDuck connection in a session sets the mode, and you can't switch modes in the middle of a session. | How you connect | Mode | | --------------------------------------------------------------------- | --------- | | `duckdb 'md:'` or `duckdb.connect('md:')` | Workspace | | `duckdb 'md:'` | Workspace | | `duckdb 'md:?attach_mode=single'` | Single | | Open `duckdb` without `md:`, then run `ATTACH 'md:'` | Workspace | | Open `duckdb` without `md:`, then run `ATTACH 'md:'` | Single | The last two rows run `ATTACH` after you've already opened a DuckDB session that isn't connected to MotherDuck, so that `ATTACH` is the session's first MotherDuck connection and sets the mode. If the session is already connected to MotherDuck, `ATTACH` doesn't change the mode. :::note `ATTACH 'md:'` run this way defaults to single mode, while the same string as a connection string defaults to workspace mode. Once a session is in single mode, `ATTACH 'md:'` can't attach your whole workspace. ::: To choose the mode explicitly, set it before you connect: ```sql LOAD motherduck; SET motherduck_attach_mode = 'workspace'; -- or 'single' ATTACH 'md:foo'; -- a database created by your account ``` --- ## 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=%2Fkey-tasks%2Fauthenticating-and-connecting-to-motherduck%2Fattach-modes%2F&page_title=Attach%20Modes&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.