Backups

Backups protect the databases Sirannon owns without stopping traffic. One-shot backups use SQLite's VACUUM INTO, which produces a consistent, compacted snapshot while readers and writers keep working. This page builds one file, backup.ts, step by step: you open a database, take a single snapshot, and then move to a scheduled backup that rotates old files off disk.

Take a one-shot snapshot

Start backup.ts with a driver, a Sirannon instance, and an open database. db.backup(path) writes a consistent snapshot to the destination while the database keeps serving reads and writes.

import { Sirannon } from '@delali/sirannon-db'
import { betterSqlite3 } from '@delali/sirannon-db/driver/better-sqlite3'
 
const driver = betterSqlite3()
const sirannon = new Sirannon({ driver })
 
const db = await sirannon.open('orders', './data/orders.db')
 
await db.backup('./backups/orders-snapshot.db')

The destination path passes the same validation as migration paths: null bytes, .. segments, and control characters are rejected before any filesystem access.

Schedule rotating backups

A single snapshot is a manual step. A long-running service needs backups on a timer without filling its disk. Swap the one-shot call for db.scheduleBackup, which runs on a cron expression and rotates old files automatically.

import { Sirannon } from '@delali/sirannon-db'
import { betterSqlite3 } from '@delali/sirannon-db/driver/better-sqlite3'
 
const driver = betterSqlite3()
const sirannon = new Sirannon({ driver })
 
const db = await sirannon.open('orders', './data/orders.db')
 
await db.backup('./backups/orders-snapshot.db') 
 
db.scheduleBackup({ 
  cron: '0 */6 * * *',
  destDir: './backups',
  maxFiles: 10,
  onError: (err) => console.error('Backup failed:', err),
})

The cron expression 0 */6 * * * runs a backup every six hours. maxFiles keeps the ten most recent files in destDir and removes older ones, so a service running for months never fills its disk with snapshots. Always supply onError: scheduled backups run in the background, so the callback is the only place a failure is reported.

Backups triggered directly also raise BackupError with the code BACKUP_ERROR, which separates them from query and migration failures in shared error handling.