--- sidebar_position: 1 title: ATTACH description: Attach local databases, MotherDuck databases, or public shares to your session --- # ATTACH The `ATTACH` command in MotherDuck can be used to: - Attach a local database to access local data - Re-attach a previously detached MotherDuck database or [share](/key-tasks/sharing-data/sharing-overview/) - Attach a public [share](/key-tasks/sharing-data/) created by any MotherDuck user in the same cloud region as your Organization, including users outside your Organization :::note "Aliasing Databases" Aliasing behavior in MotherDuck considers your relationship to the database itself. For databases owned by your user, aliases are not allowed. You will see an error that says `Database aliases are not yet supported by MotherDuck in workspace mode` when attempting to do this. For shares, database aliases are _optional_, the default name is the string following `_share`, i.e. `ATTACH md:_share/birds/e9ads7-dfr32-41b4-a230-bsadgfdg32tfa;` will have the alias `birds`. When attaching a share, the alias name remains in effect for as long as the database is attached. If the database is detached for any reason, the associated alias name is automatically cleared as well. **Important:** If the shared database contains views or other objects that reference tables using fully-qualified paths (for example, `my_db.main.my_table`), you must alias the share to match the original database name. Otherwise, those references can't be resolved and queries against those views fail. See [Views and fully-qualified table references](/key-tasks/sharing-data/sharing-overview/#views-and-fully-qualified-table-references) for details. ::: ## Attaching databases ### Syntax for databases ```sql ATTACH 'md:' ``` Parameters: * `database_name`: The name of the database to which to connect. If omitted, it defaults to 'workspace', which connects to all databases. :::note Shares are region-scoped based on your Organization's cloud region. MotherDuck Organizations are scoped to a single cloud region that must be chosen at Org creation when signing up. ::: ### Examples of database attachment ```sql -- Connect to a specific MotherDuck database ATTACH 'md:'; -- Connect to all MotherDuck databases in the workspace: ATTACH 'md:'; -- Connect to a local database ATTACH '/path/to/my_database.duckdb'; ATTACH 'a_new_local_duckdb'; ``` :::note Shares are region-scoped based on your Organization's cloud region. MotherDuck Organizations are scoped to a single cloud region that must be chosen at Org creation when signing up. ::: ### Important notes for database attachment * Local database `ATTACH` operations: * Are temporary and last only for the current session * Data stays local and isn't uploaded to MotherDuck * Use file paths instead of share URLs * MotherDuck database `ATTACH` operations: * Are persistent, as they attach the database/share to your MotherDuck account. * Requires read/write permissions for the database. * The database must have been created by the active user and must have already been detached. * If the remote database was not detached prior to running the `ATTACH` command, using the `md:` prefix will produce an error rather than creating a local database and attaching it. * For a remote MotherDuck database, the database name is used to indicate what to attach and no alias is permitted. ## Attaching shares Sharing in MotherDuck is done through shares. Recipients of a share must `ATTACH` the share, which creates a read-only database. This is a zero-copy, zero-cost, metadata-only operation. [Learn more about sharing in MotherDuck](/key-tasks/sharing-data/sharing-overview.md). ### Syntax for shares ```sql ATTACH [AS ]; ``` ### Shorthand convention for shares You may choose to name the new database by using `AS `. If you omit this clause, the new database will be given the same name as the source database that's being shared. ### Examples of attaching shares ```sql ATTACH 'md:_share/ducks/0a9a026ec5a55946a9de39851087ed81' AS birds; # attaches the share as database `birds` ATTACH 'md:_share/ducks/0a9a026ec5a55946a9de39851087ed81'; # attaches the share as database `ducks` ``` ## Troubleshooting ### Finding share URL The Share URL is provided when you [create a share](/key-tasks/sharing-data/sharing-overview/#creating-a-share). You can also see shares available for attachment by querying the [`MD_INFORMATION_SCHEMA.SHARED_WITH_ME`](/sql-reference/motherduck-sql-reference/md_information_schema/shared_with_me/) view. ### Handling name conflicts between local and remote databases In case of name conflict between a local database and a remote database, there are two possible paths: 1. Attach the local database with a different name using an alias with `AS`. For instance : `ATTACH 'my_db.db' AS my_new_name` 2. Create a share out of your remote database and attach it with an alias. Shares are read-only. ### Using `SHARES` with [read scaling replicas](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) A database cannot be attached with a [read_scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/#understanding-read-scaling-tokens) token. Databases should first be attached by an account + token with read_write permission, then accessed through read_scaling tokens. For more information, see the [Attach & Detach](/key-tasks/database-operations/detach-and-reattach-motherduck-database) guide.