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
- Attach a shared database from another user
Attaching Databases
Syntax for Databases
ATTACH 'md:<database_name>'
Parameters:
database_name
: The name of the database to which to connect. If omitted, it defaults to 'workspace', which connects to all databases.
Examples of Database Attachment
-- Connect to a specific MotherDuck database
ATTACH 'md:<database_name>';
-- 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';
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 themd:
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.
Syntax for Shares
ATTACH <share URL> [AS <database name>];
Shorthand Convention for Shares
You may choose to name the new database by using AS <database name>
. If you omit this clause, the new database will be given the same name as the source database that's being shared.
Examples of Share Attachment
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
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:
- Attach the local database with a different name using an alias with
AS
. For instance :ATTACH 'my_db.db' AS my_new_name
- Create a share out of your remote database and attach it with an alias. Shares are read-only.
Using SHARES
with Read-Scaling Replicas
A database cannot be attached with a read_scaling token. Databases should first be attached by an account + token with read_write permission, then accessed via read_scaling tokens.
For more information, see the Attach & Detach guide.