Skip to main content

ATTACH <database>

A local database can be attached in order to access local data, and a remote MotherDuck database that a user has created and has previously detached may be re-attached. To attach to a MotherDuck database, the md: prefix is used.

Syntax​

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.

Example of usage​

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

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

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.