Turso (beta)

The Rust rewrite of SQLite (@tursodatabase/database) with MVCC concurrent writes via BEGIN CONCURRENT — OR remote Turso Cloud (libsql://) with embedded-replica sync via @libsql/client. Routed by URL scheme. SQLite-compatible SQL. Single-node local, beta. VIRTUAL generated columns supported, no STORED generated columns or FTS; numeric ids drop AUTOINCREMENT; no Alpine/musl or Intel-mac prebuilts on the local engine.

Turso is the Rust rewrite of SQLite (@tursodatabase/database, formerly Limbo). It speaks SQLite's SQL dialect, file format, and a better-sqlite3-shaped driver — so the framework reuses the entire SQLite-family store and SQL compiler. The ONE thing it adds over the sqlite dialect is the reason to pick it: MVCC concurrent writes via BEGIN CONCURRENT. Where sqlite serializes every write through a single connection, turso runs a connection POOL where multiple transactions commit concurrently; a write-write conflict is detected and the framework retries it transparently.

The turso dialect has two live backends, routed by the connection URL scheme — not two versions of the same thing, but a real config choice:

  • Local Rust engine (file: / :memory:) — the embedded @tursodatabase/database engine described above: pooled, single-process, MVCC concurrent writes. beta (0.x).
  • Remote Turso Cloud (libsql:// / https:// / wss://) — a connection to a hosted Turso Cloud database over the official @libsql/client, with an auth token. Also supports an embedded replica: a local file: copy that periodically syncs from a remote primary (local-latency reads, writes forwarded to the primary).

Treat the local engine as "SQLite for a single node that needs real write concurrency", not a production-hardened engine; treat the remote/replica backend as "your app runs against managed Turso Cloud". For multi-instance scale-out with sub-second local reactivity use postgres / mysql / mariadb / mssql; for a rock-stable single-process embed use sqlite.

Configuration

The URL scheme picks the backend — local engine vs remote Turso Cloud vs embedded replica:

DB_DIALECT=turso

# ── Local Rust engine ─────────────────────────────────────────
DB_URL=file:./db.turso        # relative path (resolved against cwd)
DB_URL=file:/abs/path/db.turso
DB_URL=:memory:               # ephemeral, pool forced to size 1 (see below)
DB_MAX_CONNECTIONS=8          # pool size = the MVCC write-concurrency knob. Default 4.

# ── Remote Turso Cloud ────────────────────────────────────────
DB_URL=libsql://your-db.turso.io   # or https:// / wss://
DB_AUTH_TOKEN=<token>              # from `turso db tokens create <db>` — never logged/baked

# ── Embedded replica (local file that syncs from a remote primary) ─
DB_URL=file:./replica.db           # the LOCAL replica file
DB_SYNC_URL=libsql://your-db.turso.io   # the remote primary it syncs FROM
DB_AUTH_TOKEN=<token>
DB_SYNC_INTERVAL=30                # optional: pull-sync every N seconds (else sync on boot only)

The scheme routes the connection: file: / :memory: → the local Rust engine; libsql:// / https:// / wss:// → remote Turso Cloud (needs DB_AUTH_TOKEN); a file: URL paired with DB_SYNC_URL → an embedded replica. So the same file: scheme means "local engine" without a sync URL and "libsql embedded replica" with one. A remote URL without an auth token, or a DB_SYNC_URL without one, fails loud at boot with an actionable message. The token comes from DB_AUTH_TOKEN (alias TURSO_AUTH_TOKEN) — it is never logged or baked into the build.

On the local engine, a transaction that does not use MVCC concurrency (migrations, schema changes, the workflow engine) opens with BEGIN IMMEDIATE and runs one at a time across the pool. Low-level readers that must see one snapshot while the app keeps writing use TursoClient.withReadTransaction(effect) instead: a deferred BEGIN that takes neither the write lock nor a turn in that queue. A write inside it fails rather than upgrading, and it cannot be nested in another transaction.

import { Effect } from 'effect'
import { TursoClient } from '@voltro/sql-turso'

const snapshot = Effect.gen(function* () {
  const sql = yield* TursoClient
  return yield* sql.withReadTransaction(sql.unsafe('SELECT 1 AS value'))
})

Remote Turso Cloud + embedded replicas

Temporary libSQL native fix

Voltro temporarily resolves @libsql/client through @voltro/libsql-client@0.18.0-voltro.1. Its SDK code, types and exports are unchanged; package metadata selects @voltro/libsql@0.5.29-voltro.1, which backports native statement cleanup to the stable driver. Failed statements release their locks without reopening the connection or discarding session state. This covers the libSQL backend, including embedded replicas and their local readers. The separate local @tursodatabase/database engine is unchanged.

The dependency is included transitively. Application configuration and imports stay the same; no project-level override is required. This is temporary until an official compatible release passes the SDK, embedded-replica, lock-recovery and platform-installation checks. Voltro will then remove the temporary aliases.

Transactions and synchronization

Embedded replicas manage their own journal configuration. Although their local URL uses file:, Voltro does not issue a local PRAGMA journal_mode=WAL during replica startup; that statement is reserved for standalone libSQL files. Replica startup still performs the initial synchronization before serving reads.

Low-level readers can use LibsqlClient.withReadTransaction(effect) to open an explicit libSQL read transaction instead of the normal write transaction:

import { Effect } from 'effect'
import { LibsqlClient } from '@voltro/sql-turso'

const snapshot = Effect.gen(function* () {
  const sql = yield* LibsqlClient
  return yield* sql.withReadTransaction(sql.unsafe('SELECT 1 AS value'))
})

The callback must contain read-only work. This selects the driver's transaction mode; it is not an authorization guard against writes. It cannot be nested inside an existing transaction. Failure or interruption releases the transaction, and subsequent ordinary transactions retain their write mode. Concurrent reader/writer behavior still depends on the database journal and remote service; the local libSQL file adapter enables WAL. Timeline source readers use this capability when available, but this alone does not enable Turso source capture during normal application boot.

For an embedded replica, read transactions use a separate local-only connection to the already synchronized replica file. They do not open a transaction against the primary, so an existing replica remains readable during a primary outage. Each such transaction enables SQLite query_only; ordinary statements and write transactions keep using the syncing client and forward writes to the primary. A read snapshot remains stable while replication advances, and a later snapshot sees the new local state. The local reader uses the configured file encryption key. Initial synchronization still requires the primary; this does not enable offline writes or activate Timeline capture automatically.

The syncing client of an embedded replica runs in a child process owned by the SQL layer. Native synchronization and forwarded writes therefore do not block the application event loop. Interrupting a worker request terminates and joins that worker; other requests or transactions pinned to it fail too. The interrupted operation is never automatically replayed because a write may already have reached the primary. A later independent operation can initialize a fresh worker against the same replica file; that initialization again requires the primary. Explicit local read transactions continue to use their separate local reader. Closing the SQL layer also joins its worker, including during a primary outage.

The remote backend connects through the official @libsql/client:

File-backed libsql connections enable WAL at startup, allowing readers from completed interactive transactions to coexist with subsequent writers. Remote transports leave journal configuration to the server. Local-file tests prove the client seam, not Cloud authentication or real replica synchronization.

  • Remote Turso Cloud (libsql:// / https:// / wss://): every statement runs against your hosted Turso database; ctx.store.transactional(...) opens an interactive libsql transaction('write'). Turso Cloud serialises writes server-side (there's no client-side BEGIN CONCURRENT here — that's the local engine's mechanism), and a transient busy/conflict is retried by the same transaction-retry the local engine uses.
  • Embedded replica (file: + DB_SYNC_URL): the client keeps a local copy of the database that reads with local latency and syncs from the remote primary. The framework does an initial client.sync() at boot so the first reads see a warm replica; if DB_SYNC_INTERVAL is set, the driver keeps pulling on that cadence. Writes are forwarded to the primary. Optional DB_READ_YOUR_WRITES (default on) makes a local read after a write wait until the replica has caught up; DB_ENCRYPTION_KEY encrypts the local replica file at rest.

Everything above this seam is identical to the local engine — the same reused SQLite-family DataStore, the same schema/query/mutation code. Only the transport differs.

The local Rust engine and the remote/replica backend are a deliberate config choice, not a versioned split. Pick file:/:memory: for an embedded single-process DB with MVCC write concurrency; pick libsql:// (± an embedded replica) to run against managed Turso Cloud.

MVCC is mandatory — journal_mode=experimental_mvcc

BEGIN CONCURRENT is only accepted when MVCC is enabled, so every pooled connection runs PRAGMA journal_mode=experimental_mvcc at open. This is not optional for the dialect — it's what the whole thing is for. The store's DML transactions run as BEGIN CONCURRENT, so every ctx.store.transactional(...) (i.e. every mutation) opens a concurrent transaction. DDL keeps plain BEGIN (Turso rejects DDL inside a concurrent transaction), so the @effect/sql client defaults to BEGIN and the store upgrades its own transactions per-fiber — migrations (including the workflow engine's) still work.

For the local engine, connection initialization is coordinated per database file across pools in the same process. Only opening the connection and setting its pragmas take turns; ordinary queries and MVCC transactions retain their concurrency. Different database files initialize independently. This avoids a native startup race where the driver reports MVCC as enabled but rejects a concurrent transaction. It does not enable multi-process access to a local Turso file.

Concurrent writes + automatic retry

Two mutations that touch the same row run on two different pooled connections, each with its own MVCC snapshot. The loser of the commit race gets a Write-write conflict; the framework's transaction retry (exponential backoff, a few attempts) replays the whole transaction body on a fresh snapshot that now sees the winner's commit. Your handler code is unchanged — write a normal transactional mutation and the concurrency + retry happen underneath.

Size the pool (DB_MAX_CONNECTIONS) to the concurrent-mutation count you expect. :memory: is per-connection (each connection is a private database), so the pool is forced to size 1 there — :memory: is for tests, not for exercising concurrency.

Driver: @tursodatabase/database (native NAPI)

Async driver (connect() → prepare() → run/get/all), wrapped in Effect. The framework's decodeRowsFromSchema post-processor handles the same SQLite read quirks as the sqlite dialect:

  • boolean() columns: 0/1 → false/true
  • json() columns: TEXT → object (JSON.parse)
  • timestamp() / date() columns: ISO string → Date

On write, the same coercion converts Date → ISO string and boolean → 0/1 before binding.

Prebuilt binaries ship for linux-x64-gnu, linux-arm64-gnu, win32-x64-msvc, darwin-arm64 only — there is NO Alpine/musl or Intel-mac binary. A Node Docker image on Alpine will fail to install the driver; use a glibc base image (node:22-bookworm-slim, etc.). This applies to the local engine only — the remote / embedded-replica backend goes through @libsql/client (pure JS + its own bindings) and is not bound by the local engine's prebuilt matrix.

No cluster — runnerStorage: 'memory'

Like sqlite, Turso is single-node here. The workflow engine boots with runnerStorage: 'memory': workflows run durably within ONE process (crash + restart resumes from the journal), multi-replica scale-out is not possible, and DB_REPLICA_URLS is a no-op with a warning. (The pool gives concurrent writes on one node — it does NOT give horizontal scale-out.)

CDC — in-process EventEmitter

Same as sqlite: an in-process Node EventEmitter fans insert/update/delete events to the dispatcher. Sub-millisecond, single-process. No LISTEN/NOTIFY, no triggers.

Every table is reactive by default — nothing to opt into. .nonReactive() turns it off for one table on every dialect: no subscriber fires, locally or across instances. The write still happens; only the notification is suppressed. See the schema overview.

Not supported on Turso (beta gaps)

These are SQLite features the sqlite dialect has but Turso's MVCC mode does not. The framework fails LOUD at migrate rather than emit DDL the engine rejects:

  • STORED generated columns on the native engine (.generatedAs(expr, { stored: true })) remain unsupported. VIRTUAL generated columns (.generatedAs(expr)) work with MVCC; the adapter enables the required engine capability automatically. The libSQL backend supports both STORED and VIRTUAL columns. The schema emitter preserves the requested mode and does not silently downgrade STORED to VIRTUAL.
  • Full-text search (.fullTextIndex(...)). MVCC has no virtual tables (FTS5) — migrate throws. Use sqlite / postgres for FTS.
  • AUTOINCREMENT. Numeric ids (id({ scheme: 'numeric' })) emit plain INTEGER PRIMARY KEY (still auto-allocating, just without the no-reuse-of-deleted-ids guarantee). The default TypeID/ULID schemes are unaffected.

Supported features include RETURNING, ON CONFLICT upserts, json_object/json_group_array eager-loads, PRAGMA introspection, partial + expression indexes, CHECK constraints, file-backed namespace ATTACH (multi-tenant physical isolation). Native recursive CTEs remain unsupported; see recursive queries.

DDL runs in autocommit

Turso rejects DDL inside a BEGIN CONCURRENT transaction ("DDL statements require an exclusive transaction"). So voltro migrate / auto-migrate runs each DDL statement in autocommit on turso (sequential, idempotent CREATE … IF NOT EXISTS). A partial failure simply recovers on the next boot; DML transactions still use BEGIN CONCURRENT.

Identifier quoting

"name" — double quotes. Same as postgres + sqlite.

File vs :memory:

  • :memory: — ephemeral, per-connection, pool clamped to 1. Tests + smoke fixtures.
  • file:./db.turso — durable. Pool of N connections share the one file; MVCC coordinates concurrent writers.

Where it lives

  • voltro/packages/sql-turso/src/sqlLayer.ts — the URL-scheme ROUTER: connectionFromConfig parses a ConnectionConfig (+ token/sync env) into a local (Rust engine) or remote (libsql) connection and builds the matching layer
  • voltro/packages/sql-turso/src/sqlClient.ts — the LOCAL pooled @effect/sql client: async connection, per-connection prepare cache, Pool acquirers, beginTransaction: 'BEGIN' (DDL-safe default; the store upgrades its own DML transactions to BEGIN CONCURRENT per-fiber via ConcurrentTransaction), MVCC pragma, :memory: size-1 clamp
  • voltro/packages/sql-turso/src/libsqlClient.ts — the REMOTE @effect/sql client over @libsql/client: autocommit client.execute, an interactive client.transaction('write') for transactional() (with BEGIN as a no-op and COMMIT/ROLLBACK mapped onto the tx object), and the embedded-replica sync (syncUrl + initial client.sync()). The auth token is config/env-sourced and never logged
  • voltro/packages/sql-turso/src/retry.ts — isTursoRetryableFailure (matches the "Write-write conflict" / busy MESSAGE; the local engine tags every error with a generic code, so the retry identity is the message)
  • voltro/packages/sql-turso/src/index.ts — tursoDialect (id: 'turso'); reuses makeSqliteStore from @voltro/sql-sqlite with the routed client + retry predicate
  • voltro/packages/sql-sqlite/src/store.ts — the shared SQLite-family store (driver + retry predicate + span name are injected)
  • voltro/packages/database/src/migrate.ts — Turso DDL branch (numeric-id without AUTOINCREMENT; SQLite-family generated-column syntax; FTS guard; autocommit DDL)

SQL integer precision

The libSQL adapter decodes signed 64-bit SQL integers without rounding. Raw SQL results return safely representable integers as JavaScript number and larger integers as bigint, including positional results and transactions. This also applies to remote HTTP connections and embedded replicas: large workflow journal identifiers must not fail decoding before they reach the framework. Schema-level field conversion still applies when reading through the data store.

Native statement cancellation

The native Turso promise API cannot cancel a statement already in flight. When an Effect is interrupted, the adapter waits for that statement to settle before returning its connection, closing its statement or rolling back the transaction. This prevents a shutdown from starting cleanup concurrently on the same connection. Interruption does not undo an autocommit write that already completed; transactional changes still use rollback.

Workflow runner topology

A direct remote primary uses shared SQL workflow runners with row leases in development and compiled production. Local files and embedded replicas keep single-process memory runners. The dialect exposes this decision through SqlDialect.workflowRunnerStorage(connection), using the same connection parser as its SQL layer; custom hosts should preserve that decision when selecting runner storage. See workflow cluster coordination.

Attached tenant databases and the native pool

File-backed tenant namespaces are shared across the native client's connection pool. After an ATTACH DATABASE succeeds, subsequent queries on any connection resolve that namespace to the same file. This applies to the SQLite-family store's attachNamespace() helper and raw migration provisioning SQL. DETACH DATABASE also propagates before subsequent queries; reattaching an alias invalidates cached statements so they do not keep reading the previous database.

The pool retains its configured concurrency. Attachments are synchronized when a connection needs them, including connections constructed after provisioning. Duplicate aliases and failed file opens remain errors and do not replace a working tenant mapping. Provision and detach tenant databases outside active application transactions; the native engine's transaction restrictions still apply.

A private :memory: attachment cannot be shared across multiple native connections. Use a file-backed tenant database for a pooled application. A private attachment is rejected and undone when the pool has more than one connection. This describes the local native backend, not remote libSQL attachment support.