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.

Try the Turso Per User Starter to get started with a multi-tenant application using Next.js, Drizzle, Clerk, libSQL, and Turso Multi-DB Schemas.

​
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, CREATE VIEW, 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/{organizationSlug}/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, CREATE VIEW, 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/{organizationSlug}/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

  • Schema databases cannot be shared across groups or globally via an organization/account.
  • You can (but not recommended) INSERT rows into the parent database that can be queried 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.
  • When a migration is applied to the schema database:
    • It’s first run as a dry-run on the schema and all other associated databases.
    • If successful, a migration job is created.
    • Tasks are created for each database that references this schema.
    • The migration is then applied to each referencing database.
    • Finally, if all tasks succeed, the migration is applied to the schema database itself.
    • You can’t create or delete a database if there are any migrations running.
  • During a migration, all databases are locked to write operations.
  • Make sure any application querying the child databases handle any databases not yet updated with the schema.
  • You cannot apply schema changes to a child database directly. You must use the parent (schema) database.
  • You can check the status of a migration using the /jobs endpoint — learn more.

Was this page helpful?

Turso + AkamaiAttach Database