oneliteDocs
onelite docs
Everything about OneLite: getting started, the happy-path API and the ADO.NET provider, FTS3/4/5, R*Tree and vec0, backup and blob I/O, SQLCipher-4-compatible encryption and the project’s own review of it, measured compatibility with SQLite 3.53.4, and how the storage layer and engine are built and checked. OneLite is a preview, 0.2.0-preview.2.
Start
Getting startedInstall OneLite 0.2.0-preview.2 for .NET 10, create a SQLite database, write to it and query it, in C# with no native library. OneLite is an embedded SQL database written on the .NET base class library alone that reads and writes SQLite files.OverviewOneLite is a pure-managed, SQLite-compatible embedded SQL database for .NET. It is written in C# on the base class library alone, with no native code, so it runs wherever .NET runs: trimmed and NativeAOT builds, and the browser.
Using OneLite
The happy pathAn opinionated layer in the core package (RecursiveAI.OneLite) for application code: interpolated queries, write transactions as functions, a thin typed table, source-generated mapping and migrations. It sits on the engine layer (Database, Connection, Statement) and uses…ADO.NET providerA standard ADO.NET provider on the engine layer: DbConnection, DbCommand, DbDataReader, DbTransaction, DbBatch, DbDataSource. It references only the core package. Dapper and other DbConnection consumers work unchanged. Where ADO.NET SQLite providers document a behaviour, this…Clearer errorsOneLite's errors say the same thing SQLite-compatible libraries say, and then say more. Nothing about the default behaviour changes.Readable plansConnection.Explain(sql, analyze), Connection.ExplainAsync and Statement.Plan return a QueryPlan: a tree of PlanNodes with a text rendering (Render()) and a structured form (Root, Children, Kind, Table, Index, Detail, Reason, Rejected, Runs, EstimatedRows, ActualRows, Loops).…ATTACH and per-database pragmasNormative notes for the engine layer. Behaviour is that of the pinned sqlite3 (lang_attach, lang_detach, pragma, atomiccommit §5); where the documentation is silent the text below records what the shell does, found by running it.Backup, VACUUM INTO and blob I/ONormative notes for the three features. The reference behaviour is the pinned SQLite release; every rule below was checked against it by running the same script on its native library and on this engine (tests/OneLite.Tests/Engine/BackupTests.cs, VacuumIntoTests.cs, BlobTests.cs).In the browserNormative notes for the browser storage backends (RecursiveAI.OneLite.Storage.Vfs.Browser) and the headless-browser test host. Sources: the File System Standard (fs.spec.whatwg.org: FileSystemFileHandle, FileSystemWritableFileStream, FileSystemSyncAccessHandle, the origin…
Search and extensions
FTS5CREATE VIRTUAL TABLE t USING fts5(...) is built into the core (RecursiveAI.OneLite.Extensions.Fts5). Its shadow tables (t_data, t_idx, t_content, t_docsize, t_config) have the layout the reference writes, so a database is read and modified by both engines. Tokenizers…FTS3 and FTS4CREATE VIRTUAL TABLE t USING fts3(...), fts4(...) and fts4aux(t) are built into the core (RecursiveAI.OneLite.Extensions.Fts3). The shadow tables (t_content, t_segments, t_segdir, t_docsize, t_stat) have the layout the reference writes (sqlite.org/fts3.html, "Data…R*Tree and dbstatBehaviour of rtree, rtree_i32 and dbstat as OneLite implements it, with what was settled by observing the pinned shell. Results are compared with the shell by tools/OneLite.RTreeDiff (seeded random scripts, statement by statement, then the shell's own checks on the file…vec0: vector searchvec0 is an opt-in virtual table for exact k-nearest-neighbour search. Its SQL surface follows sqlite-vec's documented API (vec0, vec_* functions, vec_each); its storage is OneLite's own. A database that holds a vec0 table is a standard SQLite file. A sqlite3 without the…Virtual tablesNormative notes for the virtual-table interface (RecursiveAI.OneLite.VirtualTables), built on SQLite's documented virtual-table model (vtab, c3ref/index_info, c3ref/c_index_constraint_eq). Results follow the pinned SQLite release; plans are OneLite's own.
Encryption
SQLCipher-compatible encryptionStatus: the page codec, key derivation and a whole-file transform are verified against files written by SQLCipher, and the pager uses them: a database opened with a key is encrypted in the database file, the rollback journal and the WAL, and can be rekeyed online (see In the…Encryption review (the project’s own)The project's own review (not an external audit) of OneLite's SQLCipher-compatible encryption: Storage/Crypto/*, Storage/Pager/Pager.Crypto.cs and the places where the pager encodes and decodes pages (cache reads, spills, commits, journal records, WAL frames, playback…
Compatibility and how it is checked
Compatibility with SQLite 3.53.4OneLite aims to behave exactly like one pinned SQLite release: SQLite 3.53.4 (the sqlite3 command-line shell from sqlite.org, with the compile options it reports through PRAGMA compile_options). Results, result codes, extended codes and error messages are compared against…sqllogictest runnertools/OneLite.SqlLogicTest runs sqllogictest scripts against an engine and reports, per file and per directory, how many records passed. It is our own implementation of the script format as the project describes it (the about.wiki page of the corpus mirror) plus what the…Differential fuzzertools/OneLite.Differential generates a database and a batch of queries from a seed, runs them on OneLite and on the pinned sqlite3 shell, and reports every difference. It also applies three metamorphic oracles (Rigger and Su) that need no second engine. Everything is…Interop and durability harnessHow the repository proves two things against the pinned sqlite3 (3.53.4): files written by either side are read identically by the other, and no committed transaction is lost or half-applied when a writer is killed. Everything here lives under tools/ and runs oracles as…Durability and crash sequencesWhat the pager writes, in what order, and what a crash at each point leaves behind. Sources: sqlite.org atomiccommit, fileformat2, lockingv3, pragma. Everything marked observed was seen by running the pinned reference shell (3.53.4, Linux x64, ext4) under strace and by…History checkertools/OneLite.History records transactional histories from concurrent clients and checks them against isolation levels. It is the proof tool for BEGIN CONCURRENT and a regression check for plain SQLite-style locking.
Inside the engine
Engine and supported SQLThe engine layer: Database, Connection, Statement, the sync and async drivers, and the SQL surface (queries, writes, DDL, transactions). This page began with the first, read-only slice; the sections below describe the engine as it now is, family by family. Results, result…SQL parserNormative notes for the code in src/OneLite/Sql/ that later units (name resolution, planner, VM) build on. The target is SQLite's documented dialect (lang_*, lang_keywords, lang_expr, datatype3, limits) as the pinned sqlite3 3.53.4 accepts it. Anything the documents leave…The write pathHow OneLite runs transactions and INSERT, UPDATE, DELETE, CREATE TABLE/INDEX and DROP TABLE/INDEX. Everything here is written to the behaviour of the pinned sqlite3 (see docs/engine.md for the read side); where the documentation was silent the behaviour was settled by running…WAL modeImplements sqlite.org's wal and walformat pages, with pragma (journal_mode, wal_checkpoint, wal_autocheckpoint, journal_size_limit, synchronous). Observed call sequences are in durability.md. The WAL code is part of the pager (partial class Pager.Wal*.cs) because commit…PagerNormative notes for the storage layer's page manager (RecursiveAI.OneLite.Storage.Pager). Sources: sqlite.org fileformat2, atomiccommit, lockingv3, tempfiles, pragma (synchronous, journal_mode, cache_size), rescode. The sync points that can suspend are listed in the…B-tree and recordsNormative notes for RecursiveAI.OneLite.Storage.Record and RecursiveAI.OneLite.Storage.BTree. Sources: sqlite.org fileformat2 (§1.6 B-tree pages, §1.7 pointer maps, §2.1 records, §2.2 serial types), datatype3, limits, and Comer, "The Ubiquitous B-Tree" (table trees are…VFS and lockingNormative notes for the storage layer's lowest level (RecursiveAI.OneLite.Storage.Vfs). Sources: sqlite.org lockingv3, atomiccommit, walformat, howtocorrupt, fileformat2, tempfiles, c3ref (io_methods).Forensic readerNormative notes for RecursiveAI.OneLite.Storage.Forensics. Sources: sqlite.org fileformat2 (§1.3 database header, §1.5 varints, §1.6 B-tree pages, freeblocks and the cell formats, §1.7 pointer maps and overflow pages, §2.1 records, rollback journal format), walformat (WAL…