Data-based: Going Beyond the DataframeLivestream + Demo - Nov 20th

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 or share
  • Attach a public share created by any MotherDuck user outside your organization in the same cloud region
"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 aliase 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.

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

Shares are region-scoped based on your Organization's cloud region. MotherDuck Organizations are currently scoped to a single cloud region that must be chosen at Org creation when signing up.

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';
note

Shares are region-scoped based on your Organization's cloud region. MotherDuck Organizations are currently 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.

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.