FrankenSQLite: A Rust Rewrite of SQLite That Trades Single-Writer Limits for Page-Level MVCC

The Single-Writer Bottleneck It Attacks

SQLite allows one writer at a time. The README pins the cause to a single lock byte, WAL_WRITE_LOCK at wal.c:3698, which serializes all writers regardless of core count. For write-heavy workloads that is a hard ceiling. FrankenSQLite is built for engineers who hit that ceiling and want a drop-in replacement that keeps the SQLite file format. The project is not a C-to-Rust translation; it is a ground-up reimplementation in Rust, using the C source only as a behavioral reference. The target user is a Rust developer who needs SQLite compatibility but wants concurrent writers, memory safety, and a type-system-enforced engine core.

Page-Level MVCC and SSI: The Core Mechanism

The core architectural change is page-level Multi-Version Concurrency Control. Instead of a file-level lock, writers that touch different B-tree pages can overlap their page version work. Commit validation and publication still coordinate shared metadata, but the page-level granularity maps naturally to SQLite's B-tree structure. The engine also implements Serializable Snapshot Isolation (SSI) by default, which tracks write-skew dependencies. That means transactions can abort and retry when they detect dependency conflicts, not just on page contention. The README is explicit that row-level MVCC would break the file format and require VACUUM, while table-level would conflict on every write to a shared table. Page-level is a deliberate middle ground. The current live path, however, is not fully concurrent: same-page base drift aborts and retries. There is a safe write-merge ladder (intent replay plus structured page patches) that is dormant test implementation, not wired into the live commit path.

File Format Compatibility: UTF-8 Only for Now

Compatibility with standard SQLite databases is non-negotiable for the project. The current runtime works over standard .db files with rollback-journal or WAL files. But there is a hard boundary introduced in v0.2.0: the database text encoding must be encoding 1, which is UTF-8. Valid SQLite UTF-16le and UTF-16be headers are recognized and rejected rather than decoded or rewritten unsafely. That is a deliberate safety choice, but it means any existing database with UTF-16 text will not open. The README lists UTF-16 support as a parity target. If your production SQLite databases are UTF-16, FrankenSQLite is not usable for them today. This is a concrete constraint to check before adopting.

Installation and First Run: Real Commands

The README provides two installation paths. On Linux and macOS, the one-liner is: curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/frankensqlite/main/install.sh?$(date +%s)" | bash. On Windows PowerShell, the equivalent is: irm "https://raw.githubusercontent.com/Dicklesworthstone/frankensqlite/main/install.ps1?$([DateTime]::UtcNow.Ticks)" | iex. The installers select the native release artifact, require a SHA-256 entry, authenticate a signed checksum manifest when minisign is available, and run exact-version plus SQL smoke tests before reporting success. Linux artifacts are fully static, so the same downloads work on glibc- and musl-based distributions. For Rust users, there is cargo install fsqlite-cli --locked. The install script supports exact-version, air-gapped, custom-destination, source-build, and post-install verification controls, documented via install.sh --help or Get-Help ./install.ps1 -Detailed. Note that prebuilt installer support covers v0.1.16-v0.1.17 and resumes with v0.2.0; v0.1.18-v0.1.19 did not publish native signed artifact sets. If minisign is present, a missing or invalid signature fails closed.

Safety and Unsafe Surface: Where the Rust Pays Off

The engine core is safe Rust. The root Cargo workspace lints forbid unsafe_code in most crates, including the engine, pager, parser, and VDBE. Two crates override this locally: fsqlite-vfs, which needs raw pointers for mmap and shared-memory regions, and the optional fsqlite-c-api, which is an FFI shim for a SQLite-compatible C ABI. If you use the Rust crates or the CLI, you never touch the C ABI shim. The design goal is to keep the unsafe surface minimal and the engine itself safe. This is a genuine advantage over C SQLite, where memory safety depends on careful manual coding. But the README also notes that data races are possible in C SQLite; the Rust type system prevents them inside the engine. That is a concrete benefit, but it does not extend to the VFS layer or the optional C API.

What Is Not Ready: RaptorQ, Encryption, and Concurrent Writers

The README is unusually honest about what is not live. The RaptorQ durability research is described as building blocks and partial native-mode integration. The v0.2.0 compatibility WAL commit and recovery path neither writes nor consults RaptorQ repair symbols, so there is no self-healing or numeric durability claim in the live runtime. Page-level encryption exists as an XChaCha20-Poly1305 DEK/KEK implementation in fsqlite-pager, but no PRAGMA key or rekey dispatch is wired into Connection. The concurrent-writer feature is blocked on correctness gates, and the v0.2.0 candidate remains blocked on those gates. The table compares features, but the caveat is that many are design or partial implementation. If you adopt this for durability guarantees or encryption, you will be disappointed. The current engine is real but hybrid: compatibility mode over standard SQLite files is the live path.

Alternatives and the Real Trade-off

The obvious alternative is C SQLite in WAL mode, which supports many readers and one writer. If your workload is read-heavy or you can serialize writes, C SQLite is mature, battle-tested, and supports UTF-16, encryption via SEE, and a full SQL dialect. FrankenSQLite's parser coverage exceeds execution parity, but the execution engine is still catching up. Another alternative is a server database like PostgreSQL, which offers row-level MVCC and true concurrent writers, but it breaks the embedded, zero-config model and the SQLite file format. The trade-off is clear: FrankenSQLite aims to keep the SQLite file format and embedded nature while adding concurrency, but it is not there yet. For production, C SQLite remains the safer choice until the concurrent-writer gates pass.

Maintenance and License Implications

The project is active, with recent releases v0.3.11, v0.3.10, and v0.3.9 in August 2026. That suggests rapid iteration, but also that the API and behavior may shift between releases. The license is listed as NOASSERTION, which means the repository does not declare a standard open-source license. That is a significant adoption risk. Without a clear license, you cannot legally use the code in your own projects without explicit permission. The README does not clarify the licensing terms. Before adopting FrankenSQLite, you should contact the maintainers or check the LICENSE file for a definitive statement. The installation process includes signed checksum manifests, which is a good supply-chain practice, but the license ambiguity is a blocker for many organizations.

Editorial conclusion

Adopt FrankenSQLite if you need a Rust-native SQLite-compatible engine with a path to concurrent writers and you can live with the v0.2.0 boundary: UTF-8 only, no encryption, and no self-healing in the live path. Do not adopt it for production write-heavy workloads yet, because the concurrent-writer feature is blocked on correctness gates and the current commit path still aborts on same-page drift. Before using it, verify that your database text encoding is UTF-8, check the latest release notes for the concurrent-writer gate status, and run the installer's smoke tests on your exact platform. If you need stable concurrency today, stick with C SQLite in WAL mode or a server database like PostgreSQL.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes