v0.4.13 · November 1, 2026

Get Started

Get Started

Get Started

Two ways in: the fsqlite shell, if you want to poke at a database file, or the fsqlite crate, if you want it inside a Rust program. Both work against ordinary SQLite files.

The fsqlite shell

The installer downloads a signed release binary, checks its SHA-256 against the signed manifest (and the minisign signature, if minisign is installed), then runs a version check and a SQL smoke test before it reports success. Linux builds are fully static, so the same binary works on glibc and musl systems.

terminal
01# Linux / macOS: signed prebuilt binary, checksum-verified02curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/frankensqlite/main/install.sh?$(date +%s)" | bash03 04# Or build it yourself05cargo +nightly install fsqlite-cli --locked06 07# Open a database (stock SQLite files work)08fsqlite app.db09 10fsqlite> CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);11fsqlite> INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob');12fsqlite> .mode column13fsqlite> SELECT * FROM users;14id  name15--  -----161   Alice172   Bob18 19# One-shot commands 
for
scripts
20fsqlite app.db -c "SELECT count(*) FROM users;"21fsqlite app.db -c ".schema"
Syntax_Validation_Active
UTF-8_ENCODED

Windows (PowerShell):

powershell
01irm "https://raw.githubusercontent.com/Dicklesworthstone/frankensqlite/main/install.ps1?$([DateTime]::UtcNow.Ticks)" | iex
Syntax_Validation_Active
UTF-8_ENCODED

What the shell does today

  • Multi-line statements, an interactive REPL, piped batch mode, and -c / --command for one-shot queries.
  • Dot commands: .open, .tables, .schema, .dump, .read, .mode (list, column, csv, tabs, line, quote), .headers, .timer.
  • Not yet: persistent history, tab completion, and most of the less common sqlite3 dot commands.

Add the crate

The engine is published on crates.io as fsqlite (plus the fsqlite-* crates it is built from). Its API is async and runs on , so you add that too:

terminal
01# FrankenSQLite builds on a pinned nightly toolchain (edition 2024).02cargo add fsqlite03cargo add asupersync --no-default-features
Syntax_Validation_Active
UTF-8_ENCODED

Requirements

  • Nightly Rust. The workspace pins a dated nightly in rust-toolchain.toml (edition 2024) and uses at least one unstable feature, so stable toolchains will not build it.
  • Linux, macOS or Windows. Prebuilt CLI binaries are published for all three.
  • The default features include FTS5, JSON1, R-tree, ICU and the misc extensions. Turn off default-features and opt back in to slim the build.

Quickstart

Open a file, create a table, insert with parameters, read it back. Every call returns a future, so the program builds a single-threaded runtime and blocks on it.

src/main.rs
01#![recursion_limit = "512"] // the engine's futures nest deeply02 03
use
asupersync::runtime::RuntimeBuilder;
04
use
fsqlite::{Connection, SqliteValue};
05 06
fn
main() -> Result<(), Box<dyn std::error::Error>> {
07 // A small blocking pool for file I/O, the same setup the fsqlite CLI uses.08
let
runtime = RuntimeBuilder::current_thread().blocking_threads(1, 2).build()?;
09 runtime.block_on(
async
{
10
let
conn = Connection::open("app.db").
await
?;
11 12 conn.execute(13 "CREATE TABLE IF NOT EXISTS users (14 id INTEGER PRIMARY KEY,15 name TEXT NOT NULL,16 email TEXT UNIQUE17 );",18 )19 .
await
?;
20 21 conn.execute_with_params(22 "INSERT INTO users (name, email) VALUES (?1, ?2);",23 &[SqliteValue::from("Alice"), SqliteValue::from("alice@example.com")],24 )25 .
await
?;
26 27 // Prepared statements borrow the connection; drop them before close().28 {29
let
stmt = conn.prepare("SELECT id, name FROM users WHERE name = ?1;").
await
?;
30
for
row
in
stmt.query_with_params(&[SqliteValue::from("Alice")]).
await
? {
31 println!("{:?} {:?}", row.get(0), row.get(1));32 }33 }34 35 conn.close().
await
36 })?;37 Ok(())38}
Syntax_Validation_Active
UTF-8_ENCODED

Things that will bite you

  • Connection is !Send and !Sync. Keep each one on the thread that opened it. For several connections on one thread, use asupersync's local spawn APIs.
  • Prepared statements borrow the connection. Drop them before calling close().
  • Finish transactions with commit() or rollback(). A dropped transaction is rolled back before the next statement on that connection runs.

Concurrent writers

This is the reason the project exists. Give each writer its own thread and its own connection to the same file. Plain autocommit writes and plain BEGIN both run as concurrent transactions by default. Writers that land on different pages commit without waiting for each other; when two hit the same page, the later committer gets a transient SQLITE_BUSY_SNAPSHOT error and should retry.

src/bin/writers.rs
01#![recursion_limit = "512"]02 03
use
asupersync::runtime::RuntimeBuilder;
04
use
fsqlite::{Connection, FrankenError, SqliteValue};
05
use
std::thread;
06 07
const
DB: &str = "events.db";
08 09
fn
main() -> Result<(), Box<dyn std::error::Error>> {
10 RuntimeBuilder::current_thread().blocking_threads(1, 2).build()?.block_on(
async
{
11
let
conn = Connection::open(DB).
await
?;
12 conn.execute("CREATE TABLE IF NOT EXISTS events (writer INTEGER, seq INTEGER);")13 .
await
?;
14 conn.close().
await
15 })?;16 17 // Connection is !Send: each writer gets its own thread, runtime and connection.18
let
writers: Vec<_> = (0..4_i64)
19 .map(|writer| {20 thread::spawn(
move
|| -> Result<(), FrankenError> {
21
let
runtime = RuntimeBuilder::current_thread()
22 .blocking_threads(1, 2)23 .build()24 .expect("runtime");25 runtime.block_on(
async
{
26
let
conn = Connection::open(DB).
await
?;
27
for
seq
in
0..1_000_i64 {
28
let
params = [SqliteValue::from(writer), SqliteValue::from(seq)];
29
let
mut
retries = 0_u8;
30 loop {31
match
conn
32 .execute_with_params(33 "INSERT INTO events (writer, seq) VALUES (?1, ?2);",34 &params,35 )36 .
await
37 {38 Ok(_) => break,39 // Same-page conflicts (SQLITE_BUSY_SNAPSHOT) are transient.40 // Retry them, with backoff in real code.41 Err(e)
if
e.is_transient() && retries < 8 => retries += 1,
42 Err(e) =>
return
Err(e),
43 }44 }45 }46 conn.close().
await
47 })48 })49 })50 .collect();51 52
for
writer
in
writers {
53 writer.join().expect("writer thread panicked")?;54 }55 Ok(())56}
Syntax_Validation_Active
UTF-8_ENCODED

Several processes writing the same file is a different story: shared-memory coordination exists, but MVCC authority is still per process and multi-process support is only proven up to the scale the swarm harness has run. Read the concurrency contract before building on it.

Useful PRAGMAs

Beyond the standard SQLite PRAGMAs, these are specific to FrankenSQLite and work in the current release. The are safe to query while a workload is running.

sql
01-- What mode am I 
in
?
02PRAGMA fsqlite_concurrency; -- e.g. begin_promotes_to | BEGIN CONCURRENT03 04-- Concurrency05PRAGMA fsqlite.concurrent_mode = OFF; -- plain BEGIN goes back to one writer at a time06PRAGMA fsqlite.serializable = OFF; -- snapshot isolation instead of SSI07PRAGMA fsqlite.retry_slo_ms = 50; -- opt-
in
cap on busy-retry latency (off by default)
08 09-- Transaction telemetry (safe to query under load)10PRAGMA fsqlite_txn_stats; -- lifecycle counters11PRAGMA fsqlite_transactions; -- one row per active transaction12PRAGMA fsqlite_txn_advisor; -- long_txn, large_read_set, rollback_pressure, ...13PRAGMA fsqlite_txn_timeline_json; -- JSON
for
timeline tooling
14PRAGMA fsqlite.conflict_stats; -- MVCC conflict counters15 16-- Advisor thresholds17PRAGMA fsqlite.txn_advisor_long_txn_ms = 5000;18PRAGMA fsqlite.txn_advisor_large_read_ops = 256;19 20-- WAL repair symbols per group on native file-backed connections (default 2, 0 = off)21PRAGMA raptorq_repair_symbols = 4;22 23-- Opt-
in
VDBE JIT
24PRAGMA fsqlite.jit_enable = 1;25PRAGMA fsqlite_jit_stats;
Syntax_Validation_Active
UTF-8_ENCODED

Time-travel queries Partial

On an in-memory database, every commit snapshots the state into a ring of up to 256 entries, and FOR SYSTEM_TIME AS OF reads from one of them. You can address a snapshot by commit sequence number or by timestamp. File-backed databases return an explicit error for now.

sql (:memory:)
01-- Time travel currently works on :memory: databases only.02-- Each commit gets a sequence number. Use explicit transactions:03-- 
in
v0.4.9, plain autocommit statements don't always get their own snapshot.
04CREATE TABLE prices (item TEXT PRIMARY KEY, price REAL); -- commit 105 06BEGIN; INSERT INTO prices VALUES ('widget', 9.99); COMMIT; -- commit 207BEGIN; UPDATE prices SET price = 14.99 WHERE item = 'widget'; COMMIT; -- commit 308 09SELECT price FROM prices; -- 14.9910SELECT price FROM prices FOR SYSTEM_TIME AS OF COMMITSEQ 2; -- 9.9911 12-- A commit that isn't
in
the snapshot ring is an error,
13-- never a silent read of current data.14SELECT price FROM prices FOR SYSTEM_TIME AS OF COMMITSEQ 999; -- error
Syntax_Validation_Active
UTF-8_ENCODED

What not to rely on yet

Encryption

Built, not wired

PRAGMA key parses, returns success, and does nothing. Like SQLite, FrankenSQLite ignores PRAGMAs it doesn't recognize, and the encryption code in the pager is not hooked up to one yet. Your database is written unencrypted. Use full-disk or filesystem encryption in the meantime.

Automatic corruption repair

Partial

File-backed connections write RaptorQ repair symbols for the WAL to a -wal-fec sidecar in the background, but opening a damaged database doesn't use them automatically yet (an explicit fsqlite::compat::recovery::repair_and_open exists on Unix). Back up your data the same way you would with SQLite.

Two engines on one file at the same time

FrankenSQLite and stock SQLite can each open a database the other wrote, but don't run them against the same file concurrently; that combination has a data-loss report against it. Checkpoint, close, then hand the file over. For the same reason, never let a 0.3.x and a 0.4.x FrankenSQLite share one WAL database.

PRAGMA fsqlite.mode = native

Design

Native (ECS) storage is under construction and is not a stable switch on Connection. Everything on this page runs in compatibility mode, on standard SQLite files.

FAQ

What is FrankenSQLite?

A from-scratch Rust implementation of SQLite. It reads and writes the same file format, speaks the same SQL, and differs mainly in one way: more than one connection can write at the same time, using page-level with serializable isolation. It was not translated from the C source; the C code was used as a behavioral reference.

Can I swap it in for SQLite today?

For a Rust program, possibly, but test it first. It opens existing databases and stock sqlite3 can read what it writes. The Rust API is its own (async, Connection is !Send), not rusqlite's, and the optional C shim covers only a common subset of the sqlite3_* API. Don't run it and stock SQLite against the same file at the same time; hand files over after a checkpoint. The project is pre-1.0, ships frequent fixes, and lists its known failures in each release.

How many writers can run at once?

There's no fixed cap. Inside one process, open one Connection per thread and they can write concurrently. Writers on different pages overlap freely. If two touch the same page, the second to commit gets SQLITE_BUSY_SNAPSHOT and should retry. Several processes writing the same file is partly supported; see the concurrency contract for exactly what is covered.

Why page-level MVCC instead of row-level?

Row versions would mean changing SQLite's file format and adding a vacuum process, the way PostgreSQL does. Pages are already SQLite's unit of storage and locking, so versioning them keeps the format intact. The cost is that two writers touching different rows on the same leaf page still conflict.

Does it prevent deadlocks?

Page-lock acquisition never waits: if a page is taken, the transaction fails fast with a busy error. With no waiting there is no wait-for cycle, so page locks cannot deadlock. Your retry loop needs backoff, though.

Is there any unsafe Rust?

Some, in two places. The workspace forbids unsafe by default. fsqlite-vfs overrides that for mmap and shared-memory regions, and the optional fsqlite-c-api needs it for FFI. If you use the Rust crates or the CLI, the C shim isn't in your build at all.

Is my data encrypted if I set PRAGMA key?

No. The encryption code exists in the pager but isn't connected. PRAGMA key is accepted and ignored, the way SQLite ignores unknown PRAGMAs, and the database is written in plain text. Use disk-level encryption until this is wired up.

Does RaptorQ repair my database automatically?

Not yet. File-backed connections generate for the WAL into a -wal-fec sidecar, and on Unix an explicit repair_and_open call can use them to rebuild damaged WAL frames. Normal opens don't do that automatically. Keep your backups.

How does it compare to Turso?

Both are Rust reimplementations of SQLite. Turso's MVCC is opt-in (BEGIN CONCURRENT in MVCC mode), versions rows, and gives snapshot isolation, so write skew is allowed. FrankenSQLite versions pages, is concurrent by default, and validates for serializability. Turso is further along as a product, with bindings, sync and a polished simulation-testing story.

Is it fast?

There is no current performance number to quote. The May 2026 benchmark matrix looked very good: FrankenSQLite was ahead of C SQLite on 79 of 93 scenarios, with the biggest wins on multi-writer workloads, and behind on small single-threaded write loops, where every row paid MVCC bookkeeping that C SQLite skips. In July the project declared those results non-citable. The storage stack had moved to async I/O, and some of the older runs lacked provenance or compared asymmetric settings. Until a clean, reproducible matrix exists for the current code, the README makes no numeric claims, and neither does this site.

Who built it, and how?

Jeffrey Emanuel, working with a large fleet of coding agents and his own tooling: Beads for issue tracking, MCP Agent Mail for coordination, cass for searching past agent sessions. The full spec and its revision history are public, and the Spec Evolution page on this site lets you step through how it changed.