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/databaseengine 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 localfile: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 libsqltransaction('write'). Turso Cloud serialises writes server-side (there's no client-sideBEGIN CONCURRENThere — 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 initialclient.sync()at boot so the first reads see a warm replica; ifDB_SYNC_INTERVALis set, the driver keeps pulling on that cadence. Writes are forwarded to the primary. OptionalDB_READ_YOUR_WRITES(default on) makes a local read after a write wait until the replica has caught up;DB_ENCRYPTION_KEYencrypts 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; picklibsql://(± 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/truejson()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. Usesqlite/postgresfor FTS. AUTOINCREMENT. Numeric ids (id({ scheme: 'numeric' })) emit plainINTEGER 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:connectionFromConfigparses aConnectionConfig(+ token/sync env) into alocal(Rust engine) orremote(libsql) connection and builds the matching layervoltro/packages/sql-turso/src/sqlClient.ts— the LOCAL pooled@effect/sqlclient: async connection, per-connection prepare cache,Poolacquirers,beginTransaction: 'BEGIN'(DDL-safe default; the store upgrades its own DML transactions toBEGIN CONCURRENTper-fiber viaConcurrentTransaction), MVCC pragma,:memory:size-1 clampvoltro/packages/sql-turso/src/libsqlClient.ts— the REMOTE@effect/sqlclient over@libsql/client: autocommitclient.execute, an interactiveclient.transaction('write')fortransactional()(with BEGIN as a no-op and COMMIT/ROLLBACK mapped onto the tx object), and the embedded-replica sync (syncUrl+ initialclient.sync()). The auth token is config/env-sourced and never loggedvoltro/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'); reusesmakeSqliteStorefrom@voltro/sql-sqlitewith the routed client + retry predicatevoltro/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.