@tursodatabase/rivet-experimental

Turso Cloud database provider for RivetKit actors. Every actor gets its own Turso database, provisioned automatically on first use and opened locally through the Turso sync engine with partial sync, so actors read from a local replica and only fetch the pages they touch.

Usage

import { actor, setup } from "rivetkit";
import { db } from "@tursodatabase/rivet-experimental";

const counter = actor({
	db: db({
		onMigrate: async (db) => {
			await db.execute(
				"CREATE TABLE IF NOT EXISTS counter (id INTEGER PRIMARY KEY, count INTEGER NOT NULL)",
			);
		},
	}),
	actions: {
		increment: async (c) => {
			await c.db.execute(
				"INSERT INTO counter (id, count) VALUES (1, 1) ON CONFLICT (id) DO UPDATE SET count = count + 1",
			);
			const rows = await c.db.execute<{ count: number }>(
				"SELECT count FROM counter WHERE id = 1",
			);
			return rows[0]?.count ?? 0;
		},
	},
});

export const registry = setup({ use: { counter } });

Configuration

Provisioning goes through @tursodatabase/sdk-experimental and requires these environment variables:

• TURSO_API_TOKEN: Turso platform API token.
• TURSO_ORG: organization slug.
• TURSO_GROUP: group to provision databases in.

Options accepted by db(...):

• databaseName: map an actor ID to a database name. Default: actor-${actorId}.
• localPath: map a database name to the local replica path. Default: OS temp directory.
• encryption: encrypt the database at rest with a key you control.
• bootstrapStrategy: partial sync bootstrap strategy. Default: first 128 KiB.
• segmentSize: partial sync segment size in bytes. Default: 128 KiB.
• remoteWrites: route writes to the remote server. Default: true. When false, writes stay on the local replica until c.db.push() runs or the actor shuts down.
• onMigrate: run migrations before the actor starts.

Sync controls

The client exposed as c.db extends the standard raw SQL surface with:

• c.db.pull(): pull new remote changes into the local replica.
• c.db.push(): push local writes to the remote database (only meaningful with remoteWrites: false).