Sirannon documentation
Sirannon is an open source library that puts real SQLite on every runtime, with replication, failover, offline device sync, change data capture, and a database for every user and every AI agent.
Getting started
1 guide
Core features
9 guides
Queries and transactions8 min readRun parameterised SQL, batch statements, wrap work in transactions, and tune the connection pool behind every database.Bulk load9 min readImport a large dataset in one transaction under relaxed durability, then restore the configured writer durability, so a big load crosses one durability barrier for the whole dataset.Change data capture6 min readSubscribe to row-level insert, update, and delete events as they commit, with filters and ordered sequence numbers.Live queries10 min readKeep a query result current from change events, applying each change to the rows you already hold, locally, over the network, and in React.Migrations13 min readDefine your schema migrations as SQL files, inline objects, or bundled assets, run them inside a transaction with checksum and concurrency guards, squash old history into a baseline, roll back to any version, and apply one set across every database the registry opens.SQLite extensions6 min readLoad a compiled SQLite extension into every connection a database holds, including the ones it opens later, and learn which runtimes can load one at all.Hooks, metrics, and lifecycle6 min readIntercept operations with before and after hooks, feed timings into your metrics system, and let the lifecycle manager own multi-tenant database handles.Integer fidelity4 min readSee which values return as plain numbers, which return as exact BigInt, and how to keep 64-bit precision on every runtime.Writer worker10 min readMove writes onto a dedicated worker thread so that a slow disk write never blocks the event loop, with a bounded queue, a write deadline, and error codes separating a rejected write from one whose outcome is unknown.
Backups
5 guides
Backups9 min readCopy an open database to a file while it keeps serving writes, read what the copy moved, and repeat that copy on a cron schedule that clears older files off disk.Backup destinations13 min readSend a copy of an open database to storage you supply, in fixed-size pieces, watch it move, and turn those pieces back into a database file.Continuous backups15 min readCopy a database once, then send only the write-ahead log frames written since the previous run, and read the chain those runs build at your destination.Restoring a database11 min readWork out what a restore to a given moment reads, rebuild the database from that moment, and find the backups no restore still needs.Backups in a replication group10 min readGive every node of a replication group the same backup settings and let one of them take the backups, with a preference you set and a skip report you can alert on.
Networked access
8 guides
Server24 min readExpose any Sirannon instance over HTTP and WebSocket with one function call, backed by uWebSockets.js.Registered operations10 min readName every read and write the server may run, declare the arguments a caller may pass, fill the rest from the authenticated identity, and let clients invoke them by name, with no SQL on the wire.Code generation5 min readEmit typed operation references from the registry your server is built from, so a client calls each read and write by name with the argument and row types the server serves.Client SDK12 min readCall a remote Sirannon server from the browser or Node.js by name, with typed rows, live queries, automatic reconnection, and subscription restore.Value encoding over JSON8 min readSend 64-bit integers and BLOBs over HTTP and WebSocket, and decode the tagged envelopes in any language without the client SDK.Subscription resumption9 min readResume a WebSocket change feed after a disconnect with sequence cursors and epochs, and recover cleanly when the server forces a resync.Device sync26 min readPush an end-user device's writes to a server, pull everyone else's live over a WebSocket, resolve conflicts on both sides, and read what the sync loop is doing at any moment.Device sync recovery16 min readHandle the three situations a device can't sync its way out of, checking that the server can sync devices at all, giving a device a full copy of the database from a snapshot, and reconciling the schema through the migration handshake.
AI agents
9 guides
Overview4 min readWhat an AI agent needs from a database, which part of its memory Sirannon holds, and what each guide in this section builds.A database per AI agent17 min readGive every AI agent a database file of its own, decide where the boundary falls when you build the identifier, let the registry open each file on the first question and close it once the agent goes quiet, and delete every file a departing customer's agents wrote.Memory and forgetting18 min readGive every fact a source and an expiry date, mark the old row as replaced when a new value supersedes it, read back the price that was current on a date you choose, and delete the rows no query returns.Rewinding memory14 min readWork out how far back an AI agent's memory reaches, read what a rewind to the moment you name would contain before you run it, rebuild that memory beside the live one, and carry forward the work the agent did after that moment.AI agent tools22 min readRegister the reads and writes an AI agent may call, let the server fill the customer identifier from the authenticated session, read the five refusals it answers a bad call with, and generate the model's tool list from the registry itself.Shared state11 min readSettle which AI agent holds a job inside the statement that claims it, let the agent that loses move to the next job on its own, and give a person a board the change log keeps current.Auditing a fleet14 min readWrite one record of everything a fleet of AI agents does, from a single hook on the registry, so that an agent can answer a question put months later and name what a rule refused.Retrieval with Narsil13 min readAnswer a question asked in a person's own words by filling a Narsil index from an AI agent's notes and keeping it in step with Sirannon's change feed, and keep one agent's search out of another agent's notes.Offline AI agents7 min readGive an AI agent a database on the device it works from, let it answer with no connection at all, and keep every later answer current from one live query as device sync reconciles the two sides.
Distributed
2 guides
Distributed replication19 min readReplicate a SQLite database across nodes over gRPC, bootstrap new replicas automatically, choose write concerns, and fail over through etcd.Topology-aware routing5 min readRoute reads and writes across the nodes of a replication group from one client, with static or coordinator discovery, read preferences, and a refresh on every error that means the client's view of the cluster is out of date.
Operations
3 guides
Configuration reference21 min readEvery option the registry, a database, the backup cycle, the server, the client, the device sync controller, and the replication engine accept, with its type and its default.Security13 min readUnderstand the built-in protections, then put the right boundary around the server before anything untrusted can reach it.Error codes15 min readEvery code Sirannon can raise, grouped by the part that raises it, with what each one means, which ones are safe to retry, and how each maps to an HTTP status.