apps/docs/content/docs.v6/orm/overview/databases/turso.mdx
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.
::::note[Preview feature] There's a Turso preview feature that integrates with Prisma CLI workflows. See the GitHub discussion and share feedback there. ::::
Turso is an edge-hosted, distributed database that's based on libSQL, an open-source and open-contribution fork of SQLite, enabling you to bring data closer to your application and minimize query latency. Turso can also be hosted on a remote server.
libSQL is 100% compatible with SQLite. libSQL extends SQLite and adds the following features and capabilities:
To learn more about the differences between libSQL and how it is different from SQLite, see libSQL Manifesto.
Many aspects of using Prisma ORM with Turso are just like using Prisma ORM with any other relational database. You can still:
sqlite database connector in your schemaThere are a number of differences between Turso and SQLite to consider. You should be aware of the following when deciding to use Turso and Prisma ORM:
prisma migrate diff to create a schema migration and then apply the changes to your database using Turso's CLI.The subsequent section covers how you can create a Turso database, retrieve your database credentials and connect to your database.
:::info
Ensure that you have the Turso CLI installed to manage your databases.
:::
If you don't have an existing database, you can provision a database by running the following command:
turso db create turso-prisma-db
The above command will create a database in the closest region to your location.
Run the following command to retrieve your database's connection string:
turso db show turso-prisma-db
Next, create an authentication token that will allow you to connect to the database:
turso db tokens create turso-prisma-db
Update your .env file with the authentication token and connection string:
TURSO_AUTH_TOKEN="eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
TURSO_DATABASE_URL="libsql://turso-prisma-db-user.turso.io"
To get started, install the Prisma ORM driver adapter for libSQL packages:
npm install @prisma/adapter-libsql
Update your Prisma Client instance:
import { PrismaClient } from "../prisma/generated/client";
import { PrismaLibSQL } from "@prisma/adapter-libsql";
const adapter = new PrismaLibSQL({
url: `${process.env.TURSO_DATABASE_URL}`,
authToken: `${process.env.TURSO_AUTH_TOKEN}`,
});
const prisma = new PrismaClient({ adapter });
You can use Prisma Client as you normally would with full type-safety in your project.
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:
.env and prisma.config.ts so Prisma CLI commands write to the local file instead of your remote Turso database:LOCAL_DATABASE_URL="file:./dev.db"
import "dotenv/config";
import { defineConfig, env } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
datasource: {
url: env("LOCAL_DATABASE_URL"),
},
});
Generate migrations locally.
Run prisma migrate dev --name <migration-name> to update the local SQLite database and produce SQL files in prisma/migrations.
Apply the generated SQL using the Turso CLI.
Use the turso db shell command to run the SQL against your remote database (replace test with your database name):
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.
Turso supports embedded replicas. 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.
When your app initially establishes a connection to your database, the primary database will fulfill the query:
Turso will (1) create an embedded replica inside your application and (2) copy data from your primary database to the replica so it is locally available:
The embedded replica will fulfill subsequent read queries. The libSQL client provides a sync() method which you can invoke to ensure the embedded replica's data remains fresh.
With embedded replicas, this setup guarantees a responsive application, because the data will be readily available locally and faster to access.
Like a read replica setup you may be familiar with, write operations are forwarded to the primary remote database and executed before being propagated to all embedded replicas.
Your application's data needs will determine how often you should synchronize data between your remote database and embedded database replica. For example, you can use either middleware functions (e.g. Express and Fastify) or a cron job to synchronize the data.
To get started using embedded replicas with Prisma ORM, add the sync() method from libSQL in your application. The example below shows how you can synchronize data using Express middleware.
import express from "express";
const app = express();
// ... the rest of your application code
app.use(async (req, res, next) => {
// [!code ++]
await libsql.sync(); // [!code ++]
next(); // [!code ++]
}); // [!code ++]
app.listen(3000, () => console.log(`Server ready at http://localhost:3000`));
It could be also implemented as a Prisma Client extension. The below example shows auto-syncing after create, update or delete operation is performed.
const prisma = new PrismaClient().$extends({
query: {
$allModels: {
async $allOperations({ operation, model, args, query }) {
const result = await query(args);
// Synchronize the embedded replica after any write operation
if (["create", "update", "delete"].includes(operation)) {
await libsql.sync();
}
return result;
},
},
},
});