platformatic / sqlite-js-stream

# sqlite-js-stream
A **Node.js port of Litestream** — SQLite streaming
replication and disaster recovery — written in **TypeScript** and built on the built-in `node:sqlite`.
SQLite is the most widely deployed database on the planet but it only lives on a single machine.
If that machine dies, your database is gone. This library replicates a SQLite database's **WAL
(Write-Ahead Log)** file into immutable, chronological **LTX (Log Transaction)** files on a remote
replica (S3, a local directory, etc.), and can **restore** a database from those files.
---
## Requirements
- **Node.js `>= 24`** — required for the built-in `node:sqlite`.
- Runtime dependency: `lz4js` (pure-JS LZ4 **block** decoder), matching the LTX format.
 Compression is a byte-identical TypeScript port of Go's `pierrec/lz4/v4` Fast block compressor.
The **published** package ships compiled JavaScript plus TypeScript declarations
(`dist/*.js` + `dist/*.d.ts`), built at publish time via `pnpm build`.
---
## Installation
This repository is a **pnpm workspace**. The core library lives at the root and
upload strategies (replica backends) live under `packages/`:
 [code] 
The core package is published as **`@platformatic/sqlite-js-stream`** and the S3
addon as **`@platformatic/sqlite-js-stream-s3`**:
 [code] 
Importing the addon registers the `s3` URL scheme with
`newReplicaClientFromURL('s3://bucket/prefix')`.
---
## Quick start
 [code] 
The database is written to by your **own** SQLite connection (using `node:sqlite`, `better-sqlite3`,
or anything else). After more writes, just `sync()` again:
 [code] 
### Take a full snapshot
Normal `sync()` writes **incremental** level-0 files. For a complete, point-in-time backup, take a
**level-9 snapshot** (a full database copy as an LTX file with `MinTXID = 1`):
 [code] 
### Restore a database
Restore reconstructs a SQLite database by compacting a level-9 snapshot with the subsequent
level-0 files:
 [code] 
Restore to a specific transaction ID, or to a point-in-time (the latest backup created at/before
the given time). Pass exactly one of `txID` or `timestamp`:
 [code] 
Restoring to `txID`/`timestamp` is at **backup boundaries** (the end of an LTX file), and a target
with no matching backup throws `NoMatchingBackupError`. A "latest" restore over a non-contiguous
file set throws `RestoreGapError` rather than silently returning a partial database.
### Continuously restore (follow)
`follow()` restores the latest backup, then keeps the database up to date as new backups are
replicated — maintaining a read-only replica (litestream's `restore -f`):
 [code] 
The applied TXID is recorded in a `-txid` sidecar (default ` -txid`) so a later `follow()`
resumes instead of re-restoring. The output database should only be opened **read-only**.
### Restore the local database if it is missing
 [code] 
### Manage many databases
 [code] 
### Replica URL
Replica clients are created from URLs via the factory registry:
 [code] 
The `file` scheme is built into the core. Ad