Turso + Vercel Integration

Zero-config SQLite databases for Vercel Functions.

Turso · Docs · Blog & Tutorials

⚠️ Warning: This software is in BETA. It may still contain bugs and unexpected behavior. Use caution with production data and ensure you have backups.

Features

• Zero-config databases — Databases are created automatically on first use
• Local SQLite — Fast reads from a local database copy in the serverless function
• Automatic sync — Writes are automatically pushed to Turso when the database connection is closed
• Partial sync — Sync only the data you need for efficient cold starts

Install

npm install @tursodatabase/vercel-experimental

Setup

1. Get your Turso API token:

   turso auth api-tokens mint my-vercel-token

2. Get your organization slug:

   turso org list

3. Add environment variables to your Vercel project:

   TURSO_API_TOKEN=your-api-token
   TURSO_ORG=your-org-slug
   TURSO_DATABASE=your-database-name
   

Important: Store TURSO_DATABASE as a secret environment variable in Vercel, just like your API token. The API token grants access to your entire Turso organization, so if an attacker can control the database name passed to createDb(), they could access any database in your org. By keeping the database name in a secret environment variable, you ensure it cannot be injected or tampered with.

Quickstart

import { createDb } from "@tursodatabase/vercel-experimental";

// Get or create a database using the secret database name from environment
const db = await createDb(process.env.TURSO_DATABASE!);

// Create tables
await db.execute(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE
  )
`);

// Insert data
await db.execute(
  "INSERT INTO users (name, email) VALUES (?, ?)",
  ["Alice", "alice@example.com"]
);

// Query data
const result = await db.query("SELECT * FROM users");
console.log(result.rows);

API Reference

createDb(name, options?)

Creates or retrieves a database instance.

const db = await createDb(process.env.TURSO_DATABASE!, {
  group: "default",        // Database group (optional)
  partialSync: true,       // Enable partial sync (optional)
});

db.query(sql, params?)

Execute a SELECT query and return results.

const result = await db.query(
  "SELECT * FROM users WHERE id = ?",
  [1]
);

console.log(result.columns); // ["id", "name", "email"]
console.log(result.rows);    // [[1, "Alice", "alice@example.com"]]

db.execute(sql, params?)

Execute an INSERT, UPDATE, DELETE, or DDL statement.

await db.execute(
  "UPDATE users SET name = ? WHERE id = ?",
  ["Bob", 1]
);

db.push()

Manually push local changes to the remote Turso database.

await db.execute("INSERT INTO users (name) VALUES (?)", ["Charlie"]);
await db.push();

db.pull()

Pull latest changes from the remote Turso database.

await db.pull(); // Get latest data from Turso

Examples

Next.js Server Component

import { createDb } from "@tursodatabase/vercel-experimental";

async function getUsers() {
  const db = await createDb(process.env.TURSO_DATABASE!);
  const result = await db.query("SELECT * FROM users");
  return result.rows;
}

export default async function UsersPage() {
  const users = await getUsers();

  return (
    <ul>
      {users.map((user) => (
        <li key={user[0]}>{user[1]}</li>
      ))}
    </ul>
  );
}

Next.js Server Action

import { createDb } from "@tursodatabase/vercel-experimental";
import { revalidatePath } from "next/cache";

async function addUser(formData: FormData) {
  "use server";

  const name = formData.get("name") as string;
  const db = await createDb(process.env.TURSO_DATABASE!);

  await db.execute("INSERT INTO users (name) VALUES (?)", [name]);
  await db.push();

  revalidatePath("/users");
}

API Route

import { createDb } from "@tursodatabase/vercel-experimental";
import { NextResponse } from "next/server";

export async function GET() {
  const db = await createDb(process.env.TURSO_DATABASE!);
  const result = await db.query("SELECT * FROM users");

  return NextResponse.json(result.rows);
}

export async function POST(request: Request) {
  const { name } = await request.json();
  const db = await createDb(process.env.TURSO_DATABASE!);

  await db.execute("INSERT INTO users (name) VALUES (?)", [name]);
  await db.push();

  return NextResponse.json({ success: true });
}

Documentation

Visit our official documentation for more details.

Support

Join us on Discord to get help using this SDK. Report security issues via email.