Multi-DB Schemas

Create and share a single schema across multiple databases.

Turso allows you to create a single schema and share it across multiple databases. This is useful for creating a multi-tenant application where each tenant has their own database.

This feature is currently in beta. Join us in Discord to provide feedback and report any issues.

How it works

1. You create a database that is used as the parent schema database.
2. You create one or more databases that are used as the child databases.
3. You apply schema changes to the parent database, child databases are automatically updated with the new schema.

Usage

You can create and manage parent or child databases using the Turso CLI, and Platform API.

Turso CLI

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

1. Create Parent Database

   Create a single database using the --type flag set to schema:

   turso db create parent-db --type schema
   
2. Create Schema

   Connect to your database using the shell to CREATE TABLE, CREATE TRIGGER, and anything else to setup your schema:

   turso db shell parent-db
   
3. Create Child Database(s)

   Create one or more child databases using the --schema flag with the name of the parent database:

   turso db create child-db --schema parent-db
   
4. Apply Additional Schema Changes

   You can now apply additional schema changes to the parent database, and the child databases will be automatically updated:

   turso db shell parent-db "CREATE TABLE users (id INT PRIMARY KEY, name TEXT);"
   

Platform API

Make sure you have an API Token, and know your Organization name:

1. Create Parent Database

   Create a database and set the is_schema field to true:

   curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/databases' \
     -H 'Authorization: Bearer TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
         "name": "parent-db",
         "group": "default",
         "is_schema": true
     }'
   
2. Create Schema

   Connect to your database using the shell, SDK, or migration script to CREATE TABLE, CREATE TRIGGER, and anything else to setup your schema:

   Turso CLI

   turso db shell parent-db
   
3. Create Child Database(s)

   Create one or more child databases and pass the schema field the name of your parent database:

   curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/databases' \
     -H 'Authorization: Bearer TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
         "name": "child-db",
         "group": "default",
         "schema": "parent-db"
     }'
   
4. Apply Additional Schema Changes

   You can now apply additional schema changes to the parent database, and the child databases will be automatically updated:

   turso db shell parent-db "CREATE TABLE users (id INT PRIMARY KEY, name TEXT);"
   

Things to know

• You can INSERT rows into the parent database that can be querified by the child database(s).
  • Be aware of any constraints that may conflict with the child database(s).
• You can’t delete a parent database if it has one or more child databases.
• You can’t create or delete a database if there are any migrations running.
  • Make sure any application querying the child databases handle any databases not yet updated with the schema.