Skip to main content

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 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.

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:

  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​

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.