The ATTACH statement enables you to link multiple databases within a single transaction, which is ideal for:

  • Organizing data in a modular way
  • Streamlining data access and enhancing scalability
  • Aggregating data

​
How it works

  1. You enable the ATTACH feature on the databases you want to connect to.
  2. You retrieve the Database ID for the database you want to ATTACH.
  3. You connect to the database
    • CLI: --attach flag to automatically create a token with the correct permissions.
    • SDK: Create a token with the attach permission for the database you want to attach.
  4. You invoke ATTACH to connect to the other databases within the database shell or SDK.

​
Usage

You can use the ATTACH statement to connect to other databases within a transaction using the CLI, or libSQL SDK. Once attached, you can query the attached databases as if they were part of the current database using the assigned alias.

​
Turso CLI

Make sure you have the Turso CLI installed, and logged in.

1

Enable attach on required databases

You will first need to enable the ATTACH feature on the database(s) you want to attach:

turso db config attach allow <database-name>
2

Retrieve Database ID

You now need to retrieve the Database ID for the database you want to ATTACH:

turso db show <database-name>
3

Connect to any database with attach

Now pass the names of the databases via the --attach flag when connecting to your database(s):

turso db shell <database-name> --attach <...database-name(s)>
4

ATTACH

Now once connected to the database you can invoke an ATTACH statement to connect the other database(s):

ATTACH "<database-id>" AS my_db;
5

Query

Execute a query using the alias for any attached database(s):

SELECT * FROM my_db.my_table;

​
libSQL SDKs

You can use one of the libSQL client SDKs with TypeScript, Rust, Go, Python, or over HTTP.

1

Enable attach on required databases

You will first need to enable the ATTACH feature on the database(s) you want to attach:

turso db config attach allow <database-name>
2

Retrieve Database ID

You now need to retrieve the Database ID for the database you want to ATTACH:

turso db show <database-name>
3

Create token with ATTACH permissions

Now create a token for the libSQL client with the attach permission for the database you want to attach:

turso db tokens create <database-name> --attach <another-database-name>
4

Connect to any database with ATTACH

Use a Client SDK to attach the desired database within a read transaction:

import { createClient } from "@libsql/client";

const client = createClient({
  syncUrl: "libsql://...",
  authToken: "...",
});

const txn = await db.transaction("read");

await txn.execute('ATTACH "<database-id>" AS my_db');

const rs = await txn.execute("SELECT * FROM my_db.my_table");

​
Things to know

  • You can only attach databases that have the attach feature enabled.
  • You can only attach databases belonging to a group, and in the same group.
  • There is a maximum of 10 databases that can be attached to a single transaction.
  • The attached databases are read only.
  • ATTACH statement can be used only within transactions.
  • ATTACH doesn’t support Embedded Replicas

Was this page helpful?

Multi-DB SchemasData Edge