Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 26 additions & 52 deletions content/200-orm/050-overview/500-databases/900-turso.mdx
Original file line number Diff line number Diff line change
@@ -1,22 +1,20 @@
---
title: 'Turso'
metaTitle: 'Turso (Early Access)'
metaTitle: 'Turso'
metaDescription: 'Guide to Turso'
tocDepth: 3
---

This guide discusses the concepts behind using Prisma ORM and Turso, explains the commonalities and differences between Turso and other database providers, and leads you through the process for configuring your application to integrate with Turso.

Prisma ORM support for Turso is currently in [Early Access](/orm/more/releases#early-access). We would appreciate your feedback in this [GitHub discussion](https://github.com/prisma/prisma/discussions/21345).
::::note[Preview feature]
There's a Turso preview feature that integrates with Prisma CLI workflows. See the [GitHub discussion](https://github.com/prisma/prisma/discussions/21345) and share feedback there.
::::

## What is Turso?

[Turso](https://turso.tech/) is an edge-hosted, distributed database that's based on [libSQL](https://turso.tech/libsql), an open-source and open-contribution fork of [SQLite](https://sqlite.org/), enabling you to bring data closer to your application and minimize query latency. Turso can also be hosted on a remote server.

:::warning
Support for Turso is available in [Early Access](/orm/more/releases#early-access) from Prisma ORM versions 5.4.2 and later.
:::

## Commonalities with other database providers

libSQL is 100% compatible with SQLite. libSQL extends SQLite and adds the following features and capabilities:
Expand Down Expand Up @@ -104,68 +102,44 @@ const prisma = new PrismaClient({ adapter })

You can use Prisma Client as you normally would with full type-safety in your project.

## Using Prisma Migrate via a driver adapter in Prisma Config

As of [Prisma v6.6.0](https://github.com/prisma/prisma/releases/tag/6.6.0) we added support for the Prisma Config file. You can use the Prisma Config file to perform `prisma db push` and make changes to your database schema. You can learn more about [the Prisma Config file in our reference page](/orm/reference/prisma-config-reference).

### 1. Install the LibSQL driver adapter

Run this command in your terminal:

```termina
npm install @prisma/adapter-libsql
```

### 2. Set environment variables

In order to set up the LibSQL adapter, you'll need to add a few secrets to a `.env` file:
## Manage schema changes with Turso

- `LIBSQL_DATABASE_URL`: The connection URL of your Turso database instance.
- `LIBSQL_DATABASE_TOKEN`: The token of your Turso database instance.
Prisma CLI commands such as `prisma migrate dev` or `prisma db push` require a local SQLite connection. To roll out schema changes to Turso, use this workflow:

You can then add these to your `.env` file or use them directly if they are stored in a different secret store:
1. **Configure Prisma CLI to target a local SQLite file.**
Update `.env` and `prisma.config.ts` so Prisma CLI commands write to the local file instead of your remote Turso database:

```bash file=.env
LIBSQL_DATABASE_URL="..."
LIBSQL_DATABASE_TOKEN="..."
```bash file=.env showLineNumbers
LOCAL_DATABASE_URL="file:./dev.db"
```

### 3. Set up Prisma Config file

Make sure that you have a [`prisma.config.ts`](/orm/reference/prisma-config-reference) file for your project. Then, set up the [migration driver adapter](/orm/reference/prisma-config-reference#adapter-removed) to use `PrismaLibSQL`:

```ts file=prisma.config.ts
import path from 'node:path'
import { defineConfig } from 'prisma/config'
import { PrismaLibSQL } from '@prisma/adapter-libsql'

// import your .env file
```ts file=prisma.config.ts showLineNumbers
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
experimental: {
adapter: true,
schema: 'prisma/schema.prisma',
migrations: {
path: 'prisma/migrations',
},
datasource: {
url: env('LOCAL_DATABASE_URL'),
},
schema: path.join('prisma', 'schema.prisma'),
async adapter() {
return new PrismaLibSQL({
url: process.env.LIBSQL_DATABASE_URL,
authToken: process.env.LIBSQL_DATABASE_TOKEN,
})
}
})
```

### 4. Migrate your database

Prisma Migrate now will run migrations against your remote Turso database based on the configuration provided in `prisma.config.ts`.
2. **Generate migrations locally.**
Run `prisma migrate dev --name <migration-name>` to update the local SQLite database and produce SQL files in `prisma/migrations`.

To create your first migration with this workflow, run the following command:
3. **Apply the generated SQL using the Turso CLI.**
Use the [`turso db shell` command](https://docs.turso.tech/cli/introduction) to run the SQL against your remote database (replace `test` with your database name):

```terminal
npx prisma db push
```bash showLineNumbers
turso db shell test < ./prisma/migrations/20251118131940_init/migration.sql
```

Replace the database name (`test`) and migration folder (`20251118131940_init`) with the values produced by `prisma migrate dev`.

## Embedded Turso database replicas

Turso supports [embedded replicas](https://turso.tech/blog/introducing-embedded-replicas-deploy-turso-anywhere-2085aa0dc242). Turso's embedded replicas enable you to have a copy of your primary, remote database _inside_ your application. Embedded replicas behave similarly to a local SQLite database. Database queries are faster because your database is inside your application.
Expand Down
Loading