> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turso.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi-DB Schemas (Deprecated)
> Create and share a single schema across multiple databases.
This feature is now deprecated for all new users. Existing paid users can
continue to use Multi-DB Schemas — [read the
announcement](https://turso.tech/blog/upcoming-changes-to-the-turso-platform-and-roadmap)
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.
**Using TypeScript?** To provision databases programmatically, use the [`@tursodatabase/api`](https://www.npmjs.com/package/@tursodatabase/api) client rather than calling the REST API directly. See the [SDK quickstart](/api-reference/introduction#quickstart-with-the-typescript-sdk).
Try the [Turso Per User Starter](https://github.com/notrab/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](/cli/db/create), and [Platform API](/api-reference/databases/create).
### Turso CLI
Make sure you have the [Turso CLI](/cli/installation) installed, and [logged in](/cli/auth/login).
Create a single database using the `--type` flag set to `schema`:
```bash theme={null}
turso db create parent-db --type schema
```
Connect to your database using the shell to `CREATE TABLE`, `CREATE TRIGGER`, `CREATE VIEW`, and anything else to setup your schema:
```bash theme={null}
turso db shell parent-db
```
Create one or more child databases using the `--schema` flag with the name of the parent database:
```bash theme={null}
turso db create child-db --schema parent-db
```
You can now apply additional schema changes to the parent database, and the child databases will be automatically updated:
```bash theme={null}
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:
Create a database and set the `is_schema` field to `true`:
```bash theme={null}
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
}'
```
Connect to your database using the shell, [SDK](/sdk), or migration script to `CREATE TABLE`, `CREATE TRIGGER`, `CREATE VIEW`, and anything else to setup your schema:
```bash Turso CLI theme={null}
turso db shell parent-db
```
Create one or more child databases and pass the `schema` field the name of your parent database:
```bash theme={null}
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"
}'
```
You can now apply additional schema changes to the parent database, and the child databases will be automatically updated:
```bash theme={null}
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](/sdk/http/reference#schema-migration-jobs).