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.
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 scripts20fsqlite app.db -c "SELECT count(*) FROM users;"21fsqlite app.db -c ".schema"Windows (PowerShell):
01irm "https://raw.githubusercontent.com/Dicklesworthstone/frankensqlite/main/install.ps1?$([DateTime]::UtcNow.Ticks)" | iexWhat the shell does today
- Multi-line statements, an interactive REPL, piped batch mode, and
-c/--commandfor 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
sqlite3dot 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:
01# FrankenSQLite builds on a pinned nightly toolchain (edition 2024).02cargo add fsqlite03cargo add asupersync --no-default-featuresRequirements
- 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-featuresand 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.
01#![recursion_limit = "512"] // the engine's futures nest deeply02 03 asupersync::runtime::RuntimeBuilder;04 fsqlite::{Connection, SqliteValue};05 06 main() -> Result<(), Box<dyn std::error::Error>> {07 // A small blocking pool for file I/O, the same setup the fsqlite CLI uses.08 runtime = RuntimeBuilder::current_thread().blocking_threads(1, 2).build()?;09 runtime.block_on( {10 conn = Connection::open("app.db").?;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 .?;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 .?;26 27 // Prepared statements borrow the connection; drop them before close().28 {29 stmt = conn.prepare("SELECT id, name FROM users WHERE name = ?1;").?;30 row stmt.query_with_params(&[SqliteValue::from("Alice")]).? {31 println!("{:?} {:?}", row.get(0), row.get(1));32 }33 }34 35 conn.close().36 })?;37 Ok(())38}Things that will bite you
Connectionis!Sendand!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()orrollback(). 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.
01#![recursion_limit = "512"]02 03 asupersync::runtime::RuntimeBuilder;04 fsqlite::{Connection, FrankenError, SqliteValue};05 std::thread;06 07 DB: &str = "events.db";08 09 main() -> Result<(), Box<dyn std::error::Error>> {10 RuntimeBuilder::current_thread().blocking_threads(1, 2).build()?.block_on( {11 conn = Connection::open(DB).?;12 conn.execute("CREATE TABLE IF NOT EXISTS events (writer INTEGER, seq INTEGER);")13 .?;14 conn.close().15 })?;16 17 // Connection is !Send: each writer gets its own thread, runtime and connection.18 writers: Vec<_> = (0..4_i64)19 .map(|writer| {20 thread::spawn( || -> Result<(), FrankenError> {21 runtime = RuntimeBuilder::current_thread()22 .blocking_threads(1, 2)23 .build()24 .expect("runtime");25 runtime.block_on( {26 conn = Connection::open(DB).?;27 seq 0..1_000_i64 {28 params = [SqliteValue::from(writer), SqliteValue::from(seq)];29 retries = 0_u8;30 loop {31 conn32 .execute_with_params(33 "INSERT INTO events (writer, seq) VALUES (?1, ?2);",34 ¶ms,35 )36 .37 {38 Ok(_) => break,39 // Same-page conflicts (SQLITE_BUSY_SNAPSHOT) are transient.40 // Retry them, with backoff in real code.41 Err(e) e.is_transient() && retries < 8 => retries += 1,42 Err(e) => Err(e),43 }44 }45 }46 conn.close().47 })48 })49 })50 .collect();51 52 writer writers {53 writer.join().expect("writer thread panicked")?;54 }55 Ok(())56}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.
01-- What mode am I ?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- 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 timeline tooling14PRAGMA 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- VDBE JIT24PRAGMA fsqlite.jit_enable = 1;25PRAGMA fsqlite_jit_stats;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.
01-- Time travel currently works on :memory: databases only.02-- Each commit gets a sequence number. Use explicit transactions:03-- 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 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; -- errorWhat not to rely on yet
Encryption
Built, not wiredPRAGMA 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
PartialFile-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
DesignNative (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?
Can I swap it in for SQLite today?
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?
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?
Does it prevent deadlocks?
Is there any unsafe Rust?
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?
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?
-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?
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.