@delali/sirannon-db 0.2.3-next.35 → 0.2.3-next.37

package/README.md

@@ -66,6 +66,7 @@ React Native uses the same shape through `expoSqlite()` with `readPoolSize: 1`.
 | `@delali/sirannon-db` | Core library: queries, transactions, CDC, live queries, migrations, backups, hooks, metrics, lifecycle |
 | `@delali/sirannon-db/driver/*` | SQLite driver adapters (see the table above) |
 | `@delali/sirannon-db/file-migrations` | Load `.up.sql` and `.down.sql` files from a directory |
+| `@delali/sirannon-db/backup` | Backup destination types, chain records, and `restoreBackup` |
 | `@delali/sirannon-db/backup-scheduler` | Cron-scheduled backup runner with file rotation |
 | `@delali/sirannon-db/server` | HTTP and WebSocket server powered by uWebSockets.js |
 | `@delali/sirannon-db/client` | Client SDK with auto-reconnect, subscription restore, and device sync |
@@ -93,7 +94,7 @@ const balance = await db.transaction(async tx => {
 })
 ```
 
-A large import runs faster through `bulkLoad`, which trades durability for speed inside one transaction and restores the configured level afterwards. The [core engine guide](../../docs/core.md) covers it, along with migrations, backups, hooks, metrics, and the multi-tenant lifecycle.
+A large import runs faster through `bulkLoad`, which trades durability for speed inside one transaction and restores the configured level afterwards. The [core engine guide](../../docs/core.md) covers it, along with migrations, hooks, metrics, and the multi-tenant lifecycle. Backups have a [guide of their own](../../docs/backups.md).
 
 ## Change data capture and live queries
 
@@ -225,7 +226,8 @@ The [security guide](https://sirannon.sondelali.com/docs) covers each of these i
 
 | Guide | What it covers |
 | --- | --- |
-| [Core engine](../../docs/core.md) | Bulk load, live queries, migrations, backups, hooks, metrics, and the multi-tenant lifecycle |
+| [Core engine](../../docs/core.md) | Bulk load, live queries, migrations, hooks, metrics, and the multi-tenant lifecycle |
+| [Backups](../../docs/backups.md) | Copies to a file or to storage you supply, the chain of changes after one, and restoring from a moment you name |
 | [Server](../../docs/server.md) | HTTP routes, WebSocket messages, authentication, write shapes, the writer worker, and value encoding |
 | [Registered operations](../../docs/operations.md) | Naming the statements a server runs, identity-filled arguments, capabilities, and code generation |
 | [Live queries](../../docs/live-queries.md) | Maintained query results locally, over the network, and in React |

package/dist/backup/index.d.ts

@@ -1,6 +1,6 @@
-import { e as BackupDestination, f as BackupRunReport } from '../types-GuxbxlwL.js';
-export { g as BackupChain, h as BackupChainBase, i as BackupChainChange, j as BackupChainPosition, k as BackupChainRecord, l as BackupCycle, m as BackupCycleOptions, n as BackupPiece, o as BackupProgress, p as BackupToDestinationOptions, q as DEFAULT_CHAIN_NAME, r as chainLogName, s as readBackupChains } from '../types-GuxbxlwL.js';
-export { B as BackupCapabilities, a as BackupRestorePlan, b as BackupSafeToDeleteOptions, c as backupPiecesSafeToDelete, p as planBackupRestore } from '../chain-queries-BFRYrmNE.js';
+import { j as BackupDestination, k as BackupRunReport, a as SQLiteDriver } from '../types-Xb0L3o3w.js';
+export { g as BackupChain, e as BackupChainBase, f as BackupChainChange, l as BackupChainPosition, h as BackupChainRecord, m as BackupCycle, n as BackupCycleOptions, o as BackupGroupMembership, p as BackupGroupSource, q as BackupNodePreference, r as BackupPiece, s as BackupProgress, t as BackupSkip, u as BackupSkipReason, v as BackupToDestinationOptions, w as DEFAULT_CHAIN_NAME, x as chainLogName, y as readBackupChains } from '../types-Xb0L3o3w.js';
+export { B as BackupCapabilities, a as BackupRestorePlan, b as BackupSafeToDeleteOptions, c as backupPiecesSafeToDelete, p as planBackupRestore } from '../chain-queries-D5aZ-8v2.js';
 import '../query-types-Cv8N7pXj.js';
 
 /** What one assembled file took to build.
@@ -15,12 +15,11 @@ interface AssembleResult {
     fingerprint?: string;
 }
 /**
- * Builds a local file from the pieces a destination holds, fetching one piece
- * at a time and writing it where its index places it, so a piece SQLite never
- * wrote leaves zeros rather than moving every later byte.
+ * Builds a local file from the pieces a destination holds, checking the result
+ * against what the run that wrote them reported.
  *
  * @param destination - Where the pieces are read from.
- * @param report - What the run that wrote those pieces recorded, which the assembly checks its result against.
+ * @param report - What the run that wrote those pieces recorded.
  * @param destPath - Path the assembled file is written to.
  * @returns The bytes and pieces the assembly wrote, and the fingerprint it computed.
  *
@@ -28,4 +27,125 @@ interface AssembleResult {
  */
 declare function assembleFromDestination(destination: BackupDestination, report: BackupRunReport, destPath: string): Promise<AssembleResult>;
 
-export { type AssembleResult, BackupDestination, BackupRunReport, assembleFromDestination };
+/** How far one restore has got, reported after every piece it fetches.
+ * @public
+ */
+interface BackupRestoreProgress {
+    /** Whether the restore is fetching the full copy or replaying the change pieces on top of it. */
+    phase: 'full-copy' | 'changes';
+    /** Pieces the restore has fetched. */
+    piecesFetched: number;
+    /** Bytes it has fetched. */
+    bytesFetched: number;
+    /** Change pieces it has replayed. */
+    changesApplied: number;
+    /** Change pieces the plan holds altogether. */
+    changesTotal: number;
+}
+/**
+ * How Sirannon rebuilds a database from a moment you name.
+ *
+ * @public
+ */
+interface BackupRestoreOptions {
+    /** Where the backups and their records are stored. */
+    destination: BackupDestination;
+    /** Driver the restore opens the rebuilt database through, so it can fold each batch of changes in. */
+    driver: SQLiteDriver;
+    /** Path Sirannon writes the rebuilt database to. A file already there stops the restore unless you set {@link BackupRestoreOptions.replaceExisting}. */
+    destPath: string;
+    /**
+     * Whether to replace a database already at that path. It defaults to false,
+     * because a restore removes the write-ahead log beside the path it writes to
+     * and any commit that log still held would go with it. Set this where you
+     * mean to restore over a database you no longer want.
+     */
+    replaceExisting?: boolean;
+    /** Epoch milliseconds you want back. Defaults to now, which reaches the newest backup the destination holds. */
+    moment?: number;
+    /** Name the list of chains is stored under. Defaults to `sirannon-backup-chain`. */
+    chainName?: string;
+    /**
+     * How many change pieces to replay between one checkpoint and the next.
+     * Defaults to 16. This is what bounds the log the restore writes beside the
+     * database, so lower it where disk is tight and raise it where a long chain
+     * takes too many checkpoints.
+     */
+    batchSize?: number;
+    /** Milliseconds one call to the destination may take before the restore stops with an error. Defaults to 10 minutes, and zero leaves the calls unbounded. */
+    destinationTimeoutMs?: number;
+    /** Called after every piece the restore fetches. */
+    onProgress?: (progress: BackupRestoreProgress) => void;
+}
+/** What one finished restore produced.
+ * @public
+ */
+interface BackupRestoreReport {
+    /** The chain the restore read. */
+    chainId: string;
+    /** Path of the rebuilt database. */
+    destPath: string;
+    /** Name the full copy underneath it is stored under. */
+    baseName: string;
+    /** Epoch milliseconds the rebuilt database reflects, which is when the last piece replayed was captured. */
+    restoresTo: number;
+    /** Pieces the restore fetched, counting the full copy and every change piece. */
+    pieceCount: number;
+    /** Bytes it fetched. */
+    bytesFetched: number;
+    /** Change pieces it replayed. */
+    changesApplied: number;
+    /** Log frames those pieces held. */
+    framesApplied: number;
+    /** Batches it replayed them in, each one folded into the database by a checkpoint of its own. */
+    batchCount: number;
+    /** Epoch milliseconds the restore started. */
+    startedAt: number;
+    /** Epoch milliseconds it finished. */
+    finishedAt: number;
+    /** Milliseconds it took. */
+    durationMs: number;
+}
+
+/**
+ * Rebuilds a database from the moment you name and leaves it at a path of your
+ * choosing.
+ *
+ * Sirannon reads the chain records at your destination and takes the newest
+ * full copy finished at or before that moment. It then replays every change
+ * piece captured from that copy up to the same moment, fetching one stored
+ * piece and applying it before it asks for the next. One stored piece is
+ * therefore all a restore holds, however large the database it rebuilds.
+ *
+ * Two kinds of gap fail the call. A chain missing a change piece fails with
+ * `BACKUP_CHAIN_BROKEN` naming the piece its sequence stops at, and a
+ * destination missing one of the numbered pieces a file was stored in fails
+ * with `BACKUP_DESTINATION_ERROR` naming that piece. Sirannon also checks each
+ * file against the byte count and the fingerprint its backup recorded, both of
+ * which cover the whole file.
+ *
+ * Sirannon assembles the rebuilt database beside the path you named and renames
+ * it onto that path once the last batch is folded in. A restore that fails, or
+ * one the machine kills part-way, therefore leaves that path holding whatever
+ * it held before. Where a database already sits at that path, Sirannon folds its
+ * write-ahead log back into it before the rename, so a machine that stops the
+ * restore between those two steps leaves that database whole. Where the fold
+ * cannot empty that log, because another connection holds the database or
+ * SQLite cannot open the file at all, Sirannon removes that database together
+ * with its log, so a machine stopping there leaves the path plainly empty
+ * rather than quietly short of its last commits. A database already there stops
+ * the call unless you set `replaceExisting`, because the rename leaves the
+ * rebuilt database at that path and nothing of the one it replaced.
+ *
+ * The disk this needs is the finished database, plus one stored piece, plus the
+ * log Sirannon writes for one batch of change pieces. `batchSize` sets that
+ * last part.
+ *
+ * @param options - Where to read from, what moment to reach, and where to put the result.
+ * @returns The chain it read, the moment the result reflects, and what the restore fetched and replayed.
+ *
+ * @public
+ */
+declare function restoreBackup(options: BackupRestoreOptions): Promise<BackupRestoreReport>;
+
+export { type AssembleResult, BackupDestination, type BackupRestoreOptions, type BackupRestoreProgress, type BackupRestoreReport, BackupRunReport, assembleFromDestination, restoreBackup };