Lumosql

Documentation
Login

Documentation

LumoSQL documentation

Start with the top-level README if you have not built LumoSQL yet.

These are the more detailed documentation sections:

Documents marked historical are kept because the reasoning still matters but they may not describe current code.

Using LumoSQL: lumo-*

Document What it covers
lumo-build-benchmark.md The meta-build and benchmark system in full: the test matrix, target naming, options and every make target. The companion to the top-level README.
lumo-benchmark-filter.md Querying results with tool/benchmark-filter.tcl: comparisons, statistics, TSV export for graphing.
lumo-benchmark-schema.md The schema of benchmarks.sqlite, for writing your own queries against the results.
lumo-build-nixos.md Building on NixOS, and what additions the Fossil example needs on NixOS.
lumo-proposed-debug.md A proposal to SQLite upstream for a superset of compile-time debug options. Temporary; can be deleted once upstream adopts it.
lumo-malbrain-backend.md Karl Malbrain's C btree code assessed as a candidate backend. Historical: the code has not been touched in six years.

See also ../benchmark/README.md for the questions the benchmark suite sets out to answer, and ../test/README.md for the SQL test suite and its cross-binary directives.

Purpose and design: about-*

Document What it covers
about-goals.md What LumoSQL is trying to achieve, and the development goals that follow from it.
about-backends.md The storage backends LumoSQL supports, what the shim interface buys, and which backends have come and gone.
about-not-forking-tool.md Why not-forking exists and what it does. The tool's own documentation is maintained with the tool.
about-encryption.md LumoSQL's approach to encryption, and how it compares with SQLCipher and SEE.
about-legal-aspects.md Licensing: SQLite's public domain status, and LumoSQL's promise to come with terms no less favourable.
about-design-philosophy.md Enforcing rules through data guarantees rather than through application code. Historical.

Background research: context-*

Document What it covers
context-development-landscape.md The reach of the SQLite codebase and what has been built on it before, documented as a whole for the first time.
context-relevant-codebases.md SQLite derivatives and related codebases, most of them dead, and what each is worth to LumoSQL.
context-relevant-knowledgebase.md Key-value stores and other technologies that could serve as backends. There are not many.
context-online-database-servers.md How server databases differ from embedded ones, with architecture diagrams.
context-wals.md Write-ahead logging, and how LumoSQL's architecture departs from SQLite's.
context-about-sync.md How sync behaves through the SQLite, LMDB and LumoSQL layers, and the durability tradeoffs at each.
context-about-ephemeral-tables.md The temporary btrees SQLite builds for the life of a single statement, and what a backend must supply.
context-about-meta-slots.md SQLite's per-database integer meta slots, and how a backend stores them.
context-what-are-savepoints.md SAVEPOINT in the SQL standard against SQLite's implementation, and what it asks of a storage engine.

Proposals: design-*

Document What it covers
design-backend-generator.md How backend-rename.mod, backend-new-files.mod and the lumo_* shims are generated. Read this before changing the file lists in not-fork.d/sqlite3/.
design-api.md The points in SQLite's API where backends, front-end parsers, encryption and networking can be intercepted.
design-corruption-detection-and-magic.md Row-level corruption detection by storing a hash with each row, which is where rowsums came from. Historical.
design-rbac.md A minimal at-rest discretionary access control system. Historical.
design-virtual-machine.md A shim for matching backend capabilities against what SQLite expects, whether a superset or a subset. Historical.