@rippledb/db-turso

An adapter for Turso and libSQL, perfect for edge deployments and serverless functions.

Installation

pnpm add @rippledb/db-turso @libsql/client

pnpm add @rippledb/db-turso @libsql/client

npm install @rippledb/db-turso @libsql/client

npm install @rippledb/db-turso @libsql/client

yarn add @rippledb/db-turso @libsql/client

yarn add @rippledb/db-turso @libsql/client

Basic Usage

import { defineSchema, s } from "@rippledb/core";
import { TursoDb } from "@rippledb/db-turso";

const schema = defineSchema({
  todos: { id: s.string(), title: s.string(), done: s.boolean() },
});

const db = new TursoDb({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
  schema,
});

// Append changes
await db.append({
  stream: "user-123",
  changes: [
    /* ... */
  ],
});

// Pull changes
const { changes, nextCursor } = await db.pull({
  stream: "user-123",
  cursor: null,
});

// Close when done
db.close();

With Materialization

import { defineSchema, s } from "@rippledb/core";
import { TursoDb } from "@rippledb/db-turso";
import { createMaterializer } from "@rippledb/materialize-db";

const schema = defineSchema({
  todos: { id: s.string(), title: s.string(), done: s.boolean() },
});

const db = new TursoDb({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
  schema,
  materializer: ({ db, schema }) =>
    createMaterializer({
      schema,
      db,
      dialect: "sqlite",
      tableMap: { todos: "todos" },
      fieldMap: { todos: { id: "id", title: "title", done: "done" } },
    }),
});

Options

`url`

Turso database URL. Formats:

Remote: libsql://your-db-name.turso.io
Local file: file:./local.db
In-memory: :memory:

`authToken?`

Authentication token from your Turso dashboard. Not needed for local files.

`schema`

Schema descriptor used for entity/field discovery and type inference.

`materializer`

Optional materializer factory. Receives { db, schema } and returns a materializer adapter.

Local Development

Use a local SQLite file during development:

const db = new TursoDb({
  url: "file:./dev.db",
  authToken: "", // Not needed for local files
  schema,
});

Environment Variables

# .env
TURSO_DATABASE_URL=libsql://your-db-name.turso.io
TURSO_AUTH_TOKEN=your-auth-token

Turso Features

Edge Locations

Turso replicates your database to edge locations worldwide. Your RippleDB data benefits from:

Low-latency reads from nearby replicas
Automatic failover
Global distribution

Embedded Replicas

For local-first patterns, Turso supports embedded replicas:

import { createClient } from "@libsql/client";

const client = createClient({
  url: "file:./local-replica.db",
  syncUrl: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

Embedded replicas require additional setup. See the Turso docs for details.

Limitations

Batch transactions: Uses libSQL's batch() which is atomic but doesn't return lastInsertRowid easily
No prepared statements: Each query is sent individually (libSQL handles optimization)

When to Use

Use Case	Recommendation
Edge/serverless	db-turso
Local server	db-sqlite
Global distribution	db-turso
Development	Either (Turso supports `file:`)

db-sqlite — Local SQLite adapter
materialize-db — SQL-based materializer
Server Reference — Full Db interface

db-turso

On this page