Skip to content

Latest commit

 

History

History
153 lines (95 loc) · 3.77 KB

attach-database.mdx

File metadata and controls

153 lines (95 loc) · 3.77 KB
title description
Attach Database
Attach and read data across multiple databases.

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.

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

turso db config attach allow <database-name>

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

turso db show <database-name>

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

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

ATTACH "<database-id>" AS my_db;

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.

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

turso db config attach allow <database-name>

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

turso db show <database-name>

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>

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