Drizzle ORM + Turso: Edge SQLite Database Pattern 2026 Production

1pnpm add drizzle-orm @libsql/client
2pnpm add -D drizzle-kit

1// drizzle.config.ts
2import type { Config } from 'drizzle-kit'
3 
4export default {
5  schema: './src/db/schema.ts',
6  out: './drizzle',
7  dialect: 'turso',
8  dbCredentials: {
9    url: process.env.TURSO_DATABASE_URL!,
10    authToken: process.env.TURSO_AUTH_TOKEN!,
11  },
12} satisfies Config

1curl -sSfL https://get.tur.so/install.sh | bash
2 
3# Login
4turso auth login
5 
6# Create a database (automatically the nearest region)
7turso db create my-app
8 
9# Get credentials
10turso db show my-app --url
11turso db tokens create my-app

1// src/db/schema.ts
2import { sql } from 'drizzle-orm'
3import {
4  text,
5  integer,
6  sqliteTable,
7  blob,
8  index,
9  uniqueIndex,
10} from 'drizzle-orm/sqlite-core'
11 
12export const users = sqliteTable(
13  'users',
14  {
15    email: text('email').notNull().unique(),
16    name: text('name').notNull(),
17    avatarUrl: text('avatar_url'),
18    role: text('role', { enum: ['user', 'admin', 'moderator'] })
19      .notNull()
20      .default('user'),
21    createdAt: integer('created_at', { mode: 'timestamp' })
22      .notNull()
23      .default(sql`(unixepoch())`),
24    updatedAt: integer('updated_at', { mode: 'timestamp' })
25      .notNull()
26      .default(sql`(unixepoch())`)
27      .$onUpdate(() => new Date()),
28  },
29  (table) => ({
30    emailIdx: uniqueIndex('users_email_idx').on(table.email),
31    roleIdx: index('users_role_idx').on(table.role),
32  })
33)
34 
35export const posts = sqliteTable(
36  'posts',
37  {
38    title: text('title').notNull(),
39    content: text('content').notNull(),
40    slug: text('slug').notNull().unique(),
41    authorId: text('author_id')
42      .notNull()
43      .references(() => users.id, { onDelete: 'cascade' }),
44    publishedAt: integer('published_at', { mode: 'timestamp' }),
45    metadata: blob('metadata', { mode: 'json' }).$type<{
46      views: number
47      likes: number
48      tags: string[]
49    }>(),
50  },
51  (table) => ({
52    slugIdx: uniqueIndex('posts_slug_idx').on(table.slug),
53    authorIdx: index('posts_author_idx').on(table.authorId),
54  })
55)
56 
57// Type inference from schema - no need to write a separate interface
58export type User = typeof users.$inferSelect
59export type NewUser = typeof users.$inferInsert
60export type Post = typeof posts.$inferSelect
61export type NewPost = typeof posts.$inferInsert
62 
63// Partial update type (all fields optional except id)
64export type UserUpdate = Partial<Omit<NewUser, 'id'>>

1// The User type is derived automatically:
2type User = {
3  email: string
4  name: string
5  avatarUrl: string | null
6  role: 'user' | 'admin' | 'moderator'
7  createdAt: Date
8  updatedAt: Date
9}

1// src/db/relations.ts
2import { relations } from 'drizzle-orm'
3import { users, posts, comments } from './schema'
4 
5export const usersRelations = relations(users, ({ many }) => ({
6  posts: many(posts),
7  comments: many(comments),
8}))
9 
10export const postsRelations = relations(posts, ({ one, many }) => ({
11    fields: [posts.authorId],
12    references: [users.id],
13  }),
14  comments: many(comments),
15}))

1// src/db/queries.ts
2import { db } from './client'
3import { users, posts } from './schema'
4import { eq, desc, and, gte } from 'drizzle-orm'
5 
6// Type-safe query - return type is inferred automatically
7export async function getPostsWithAuthors(limit = 10) {
8  return db.query.posts.findMany({
9    limit,
10    orderBy: [desc(posts.publishedAt)],
11    where: (posts, { isNotNull }) => isNotNull(posts.publishedAt),
12    with: {
13        columns: {
14          name: true,
15          avatarUrl: true,
16          // exclude sensitive fields like password
17        },
18      },
19      comments: {
20        limit: 3,
21        orderBy: [desc(comments.createdAt)],
22      },
23    },
24  })
25}
26 
27// Return type: Array<Post & { author: Pick<User, 'id' | 'name' | 'avatarUrl'>, comments: Comment[] }>

1// src/db/client.ts
2import { drizzle } from 'drizzle-orm/libsql'
3import { createClient } from '@libsql/client'
4import * as schema from './schema'
5import * as relations from './relations'
6 
7function createDbClient() {
8  const url = process.env.TURSO_DATABASE_URL
9  const authToken = process.env.TURSO_AUTH_TOKEN
10 
11  if (!url) throw new Error('TURSO_DATABASE_URL is required')
12 
13  // Embedded replica or remote?
14  if (process.env.NODE_ENV === 'production' && process.env.USE_EMBEDDED_REPLICA === 'true') {
15    // Embedded replica in production
16    return createClient({
17      url: 'file:local.db',
18      syncUrl: url,
19      authToken,
20      syncInterval: 60, // sync every 60 seconds
21    })
22  }
23 
24  // Remote client (development or edge)
25  return createClient({ url, authToken })
26}
27 
28// Singleton pattern - prevents recreation on hot reload in Next.js dev mode
29declare global {
30  // eslint-disable-next-line no-var
31  var __db: ReturnType<typeof drizzle> | undefined
32}
33 
34function getDb() {
35  if (!global.__db) {
36    const client = createDbClient()
37    global.__db = drizzle(client, { schema: { ...schema, ...relations } })
38  }
39  return global.__db
40}
41 
42export const db = getDb()

1# .env.local
2TURSO_DATABASE_URL=libsql://my-app-username.turso.io
3TURSO_AUTH_TOKEN=eyJ...
4 
5# .env.production
6TURSO_DATABASE_URL=libsql://my-app-username.turso.io
7TURSO_AUTH_TOKEN=eyJ...
8USE_EMBEDDED_REPLICA=true

1// src/app/actions/post.actions.ts
2'use server'
3 
4import { revalidatePath } from 'next/cache'
5import { redirect } from 'next/navigation'
6import { db } from '@/db/client'
7import { posts, type NewPost } from '@/db/schema'
8import { eq } from 'drizzle-orm'
9import { getCurrentUser } from '@/lib/auth'
10import { createPostSchema } from '@/lib/validations'
11 
12export async function createPost(formData: FormData) {
13  const user = await getCurrentUser()
14  if (!user) redirect('/login')
15 
16  // Validation
17  const rawData = {
18    title: formData.get('title') as string,
19    content: formData.get('content') as string,
20    slug: formData.get('slug') as string,
21  }
22 
23  const parsed = createPostSchema.safeParse(rawData)
24  if (!parsed.success) {
25    return { error: parsed.error.flatten().fieldErrors }
26  }
27 
28  const { title, content, slug } = parsed.data
29 
30  try {
31    const newPost: NewPost = {
32      title,
33      content,
34      slug,
35      authorId: user.id,
36    }
37 
38    const [created] = await db
39      .insert(posts)
40      .values(newPost)
41      .returning()
42 
43    revalidatePath('/blog')
44    redirect(`/blog/${created.slug}`)
45  } catch (error) {
46    if (error instanceof Error && error.message.includes('UNIQUE constraint')) {
47      return { error: { slug: ['This slug is already in use'] } }
48    }
49    throw error
50  }
51}
52 
53export async function updatePost(postId: string, data: Partial<NewPost>) {
54  const user = await getCurrentUser()
55  if (!user) redirect('/login')
56 
57  // Permission check
58  const existing = await db.query.posts.findFirst({
59    where: eq(posts.id, postId),
60    columns: { authorId: true },
61  })
62 
63  if (!existing || (existing.authorId !== user.id && user.role !== 'admin')) {
64    return { error: 'Unauthorized operation' }
65  }
66 
67  await db.update(posts).set(data).where(eq(posts.id, postId))
68  revalidatePath(`/blog`)
69  return { success: true }
70}

1# Generate a migration (SQL file)
2pnpm drizzle-kit generate
3 
4# Apply the migration
5pnpm drizzle-kit migrate
6 
7# Push schema (dev environment, without generating a migration file)
8pnpm drizzle-kit push
9 
10# Introspect the existing DB schema
11pnpm drizzle-kit introspect
12 
13# Drizzle Studio (visual DB management)
14pnpm drizzle-kit studio

1-- drizzle/0001_create_posts.sql
2CREATE TABLE `posts` (
3  `id` text PRIMARY KEY NOT NULL,
4  `title` text NOT NULL,
5  `content` text NOT NULL,
6  `slug` text NOT NULL,
7  `author_id` text NOT NULL,
8  `published_at` integer,
9  `metadata` blob,
10  FOREIGN KEY (`author_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
11);
12 
13CREATE UNIQUE INDEX `posts_slug_idx` ON `posts` (`slug`);
14CREATE INDEX `posts_author_idx` ON `posts` (`author_id`);

1// scripts/migrate.ts - runs in the CI/CD pipeline
2import { migrate } from 'drizzle-orm/libsql/migrator'
3import { db } from '../src/db/client'
4 
5async function runMigrations() {
6  console.log('Starting migration...')
7 
8  try {
9    await migrate(db, { migrationsFolder: './drizzle' })
10    console.log('Migration complete')
11    process.exit(0)
12  } catch (error) {
13    console.error('Migration error:', error)
14    process.exit(1)
15  }
16}
17 
18runMigrations()

1# package.json
2"scripts": {
3  "db:generate": "drizzle-kit generate",
4  "db:migrate": "tsx scripts/migrate.ts",
5  "db:push": "drizzle-kit push",
6  "db:studio": "drizzle-kit studio"
7}

1// src/worker.ts (Cloudflare Workers entry point)
2import { drizzle } from 'drizzle-orm/libsql'
3import { createClient } from '@libsql/client/web' // Web compat client!
4import * as schema from './db/schema'
5 
6export interface Env {
7  TURSO_DATABASE_URL: string
8  TURSO_AUTH_TOKEN: string
9}
10 
11export default {
12  async fetch(request: Request, env: Env): Promise<Response> {
13    // A new client per request - there's no global state in Workers
14    const client = createClient({
15      url: env.TURSO_DATABASE_URL,
16      authToken: env.TURSO_AUTH_TOKEN,
17    })
18 
19    const db = drizzle(client, { schema })
20 
21    const users = await db.select().from(schema.users).limit(10)
22 
23    return new Response(JSON.stringify(users), {
24      headers: { 'Content-Type': 'application/json' },
25    })
26  },
27}

1// app/api/users/route.ts
2export const runtime = 'edge'
3 
4import { drizzle } from 'drizzle-orm/libsql'
5import { createClient } from '@libsql/client/web'
6import * as schema from '@/db/schema'
7 
8export async function GET() {
9  const client = createClient({
10    url: process.env.TURSO_DATABASE_URL!,
11    authToken: process.env.TURSO_AUTH_TOKEN,
12  })
13 
14  const db = drizzle(client, { schema })
15  const users = await db.query.users.findMany({ limit: 10 })
16 
17  return Response.json(users)
18}

1// Embedded replica configuration
2import { createClient } from '@libsql/client'
3 
4const client = createClient({
5  // Local SQLite file (for read operations)
6  url: 'file:/tmp/local-replica.db',
7  // Remote primary (for write and sync)
8  syncUrl: process.env.TURSO_DATABASE_URL!,
9  authToken: process.env.TURSO_AUTH_TOKEN,
10  // Sync every 60 seconds (or manual sync)
11  syncInterval: 60,
12})
13 
14// Manual sync (e.g. before a critical read)
15await client.sync()

1# Primary database (write)
2turso db create my-app --location iad  # IAD = Washington DC (US East)
3 
4# Read replicas
5turso db replicate my-app --location fra  # Frankfurt (EU)
6turso db replicate my-app --location nrt  # Tokyo (Asia)
7turso db replicate my-app --location sin  # Singapore (SEA)
8 
9# List replicas
10turso db show my-app

1// src/db/clients.ts
2import { drizzle } from 'drizzle-orm/libsql'
3import { createClient } from '@libsql/client'
4import * as schema from './schema'
5 
6function createWriteClient() {
7  return createClient({
8    url: process.env.TURSO_PRIMARY_URL!,
9    authToken: process.env.TURSO_AUTH_TOKEN,
10  })
11}
12 
13function createReadClient() {
14  // Connect to the nearest replica
15  const replicaUrl = process.env.TURSO_REPLICA_URL ?? process.env.TURSO_PRIMARY_URL!
16  return createClient({
17    url: replicaUrl,
18    authToken: process.env.TURSO_AUTH_TOKEN,
19  })
20}
21 
22export const writeDb = drizzle(createWriteClient(), { schema })
23export const readDb = drizzle(createReadClient(), { schema })

1// Usage
2import { writeDb, readDb } from '@/db/clients'
3 
4// Read - from replica
5const posts = await readDb.query.posts.findMany({ limit: 20 })
6 
7// Write - to primary
8await writeDb.insert(posts).values(newPost)

1# Create a branch from the production database
2turso db branch create my-app staging --from my-app
3 
4# Branch info
5turso db show my-app-staging
6 
7# Delete a branch
8turso db destroy my-app-staging

1// Pick a database URL based on the environment
2const dbUrl = {
3  development: process.env.TURSO_DEV_URL!,
4  staging: process.env.TURSO_STAGING_URL!,
5  production: process.env.TURSO_PROD_URL!,
6}[process.env.NODE_ENV ?? 'development']

1async function createPostAndReturn(data: NewPost) {
2  // Write - primary
3  const [created] = await writeDb.insert(posts).values(data).returning()
4 
5  // Critical read-after-write - read from primary
6  const post = await writeDb.query.posts.findFirst({
7    where: eq(posts.id, created.id),
8    with: { author: true },
9  })
10 
11  return post
12}

1// src/db/cache.ts
2import { cache } from 'react'
3import { db } from './client'
4import { users } from './schema'
5import { eq } from 'drizzle-orm'
6 
7// Per-request memoization with React cache
8export const getUser = cache(async (id: string) => {
9  return db.query.users.findFirst({
10    where: eq(users.id, id),
11  })
12})
13 
14// Cross-request caching with Next.js unstable_cache
15import { unstable_cache } from 'next/cache'
16 
17export const getPublicPosts = unstable_cache(
18  async () => {
19    return db.query.posts.findMany({
20      where: (posts, { isNotNull }) => isNotNull(posts.publishedAt),
21      orderBy: (posts, { desc }) => [desc(posts.publishedAt)],
22      limit: 20,
23    })
24  },
25  ['public-posts'],
26  { revalidate: 60 } // 60-second cache
27)

1Drizzle should be preferred:
2- Edge runtime (Cloudflare Workers, Vercel Edge)
3- Performance-critical applications
4- Developers fluent in SQL
5- Type-safe SQL queries
6- Small/medium-scale projects
7 
8Prisma should be preferred:
9- Large teams, need for strong migration tooling
10- Those who prefer code generation
11- Rich GUI (Prisma Studio)
12- Complex relational models
13- Node.js-only environments