Skip to content
Rowsafe
Docs

Protect SQLite

Backups, restore to any second, Proof, Rewind and Pulse for your apps' SQLite files.

A SQLite database is a file your app opens itself (Rails 8, Django, Laravel, PocketBase, many Go and Node apps). Rowsafe treats each file as one database and protects it like PostgreSQL: encrypted backups in your bucket, restore to any second (in WAL mode), Marks, a weekly Proof, Rewind and Pulse. Features that need a database server don't apply: see Limits. Under the hood: How SQLite backups work.

Before you start

  • The file is on local disk (or a Docker volume on it). Network drives (NFS, SMB/CIFS, sshfs...) are refused: SQLite's locking isn't reliable there.
  • For restores to any second, WAL mode (journal_mode=WAL, the Rails 8 default). Without it you get daily backups, and Pulse offers to turn WAL on.
  • A bucket and an encryption passphrase. See Adopt an existing database.

Turn on backups

Run this on the server, then approve the server in your browser when it prints the link:

curl -fsSL https://rowsafe.sh | sudo sh -s -- --account

Or copy the command from Servers, then Add a server (it holds a one-time token):

curl -fsSL https://rowsafe.sh | sudo sh -s rse_...

The installer finds your SQLite files. Nothing restarts.

The files. It lists SQLite files open by running apps (also in Docker containers) and asks which to protect and what to call them. For a file it can't see (app stopped), add --sqlite /srv/app/db/production.sqlite3. Repeat for several.

Access to the file. The agent runs as user rowsafe. Root gives it read and write access to the file, its -wal and -shm files and their folder, with a POSIX ACL (installing acl if needed) and a default ACL so later -wal/-shm files are covered. Without ACL support, it adds rowsafe to the file's group when that group is the app user's own and can already write. The installer prints what it changed. Owner and everyone else's access stay as they were.

The plan. You review it and say yes. The file doesn't change. Rowsafe checks a backup reaches your bucket and opens with your key, takes the first full copy and, in WAL mode, starts copying every change.

Unattended: --protect NAME --sqlite PATH, with storage settings in the environment (Automate it):

curl -fsSL https://rowsafe.sh | sudo sh -s -- --protect app --sqlite /srv/app/db/production.sqlite3

Safe next to your app

Rowsafe opens the file like your app does, with SQLite's own locking, so it's safe next to your app.

  • It never locks your app out. Copies use SQLite's online backup API. In WAL mode, writes never wait for Rowsafe. In rollback-journal mode, a write can wait a moment, as behind any reader.
  • Your app comes first. The agent gets lower CPU and IO weight, and holds the write lock only a few milliseconds at a time.
  • It retries when the file is busy. Pulse counts those moments: many mean your app keeps long transactions open.

What Rowsafe does

How
Full backupA consistent copy through SQLite's online backup API while your app writes, compressed and encrypted on your server. Daily by default, newest 7 kept. Pages checked (quick_check), row counts recorded. Needs about the file's size free for a temporary file; Rowsafe says so if there isn't room.
Every changeIn WAL mode, every committed transaction reaches your bucket within a few seconds, encrypted.
RestoreTo any second or a Mark (WAL mode): the newest backup plus every transaction committed by then. In rollback-journal mode, to a daily backup.
MarksA named point, from the dashboard, rowsafe mark app before-migration or an AI agent through Guard. Exact. Needs WAL mode.
ProofWeekly: restore into a scratch file, run PRAGMA integrity_check and foreign_key_check, compare row counts, delete it.
RewindA copy at any second or Mark next to the live file. Compare table by table and bring missing rows back.
Rewind the whole databasePuts the whole file back in place while your app runs. Undo for 7 days.
PulseFile and -wal size, free pages, journal mode, backup lag, last integrity check, busy/locked moments, stale statistics. Most findings have a fix.
FilesYour app's folders (uploads), restored to the same moment.
Second copyBackups and changes also go to a second bucket with its own passphrase.
Find the momentWhen rows were deleted or changed, or a table dropped, with the point just before to rewind to. Worked out on a private copy on your server. Needs WAL mode.
SecurityFiles open to every user, in a web-served or world-writable folder, or with readable copies nearby. Close to other users in one click.
RecommendationsFrom the schema: foreign keys without an index (tested on a copy, then Create index), tables without a primary key, AUTOINCREMENT, missing statistics.
Migration previewYour migration on a restored copy: time, rows, rebuilt tables, indexes, how long writes would wait. Also for AI agents.
Safe copiesA masked or structure-only copy, as a file only the agent's user can read.
CloneThe file at any second or Mark, as a new file in a folder root allowed, here or on another server, protected as a new database.

Restore

From the Rewind tab (Restore a database), pick a second or a Mark, then:

  • Restore a copy into a separate file on the same server. Your app keeps using the live file.
  • Compare table by table: deleted, added and changed rows, matched by primary key (or rowid, which VACUUM can change; the page says so). Virtual tables (full-text search...) aren't compared.
  • Bring back rows into the live file in one transaction. Existing rows are never overwritten.
  • Rewind the whole database, for the worst case: the copy is written into the live file while your app runs, and open connections see the new content. Writes wait a few seconds. Undo rewind for 7 days.

Only owners and admins can restore (or their AI agents, acting as them). A copy needs about the file's size free on the same disk, and so does the file kept for Undo.

Restore without Rowsafe

Your backups don't need Rowsafe's servers. With the agent binary and your bucket settings and passphrase in the environment (ROWSAFE_REPO_*, as in /etc/rowsafe/agent.env), restore to a new file, at the newest point, a moment or a Mark:

rowsafe-agent sqlite restore --stanza app --to /tmp/restored.sqlite3 --at 2026-10-04T09:30:00Z

--stanza is the database's bucket folder (on its Settings page). It never touches the live file and runs PRAGMA integrity_check on the result.

Pulse and one-click fixes

Pulse reads the file about every minute (statistics every 30 minutes). Each finding has a button, with a confirmation when it could disturb your app.

ProblemButtonWhat Rowsafe does
The -wal file keeps growingShrink the -wal fileOnce changes are in your bucket, moves them into the database file and shrinks -wal, then takes a fresh full copy. A long-open transaction or reader blocks it; the finding says so.
Many unused (free) pagesGive free space backRebuilds the file (VACUUM). Writes wait while it runs (the confirmation says how long), and it needs about the file's size free. With auto_vacuum=incremental, uses PRAGMA incremental_vacuum instead, no rebuild.
Query statistics are missing or out of dateRefresh statisticsRuns PRAGMA optimize.
Continuous backups are off (rollback-journal mode)Turn on continuous backupsSwitches the database to WAL mode. See below.

A failed integrity check raises an alert pointing to Rewind, to restore the file from before the damage.

Turn on continuous backups

Turn on continuous backups switches the file to WAL mode (PRAGMA journal_mode=WAL), needed for restores to any second and Marks:

  • your app keeps working; nothing restarts;
  • -wal and -shm files appear next to it;
  • it stays on unless your app switches it back.

Refused on a network drive.

Docker

The installer on the host finds SQLite files in containers too. To keep Rowsafe inside your compose project instead, run the agent as a sidecar: mount the app's volume read-write and run as the same user as your app.

You need an enrollment token (rowsafe hosts enroll-token), a bucket and its keys, and a passphrase saved in your secret manager first. Put them in rowsafe-agent.env, chmod 600 it and never commit it:

rowsafe-agent.env
ROWSAFE_ENROLL_TOKEN=rse_...        # first start only; delete it afterwards
ROWSAFE_REPO_S3_ENDPOINT=<account-id>.eu.r2.cloudflarestorage.com
ROWSAFE_REPO_S3_BUCKET=app-rowsafe
ROWSAFE_REPO_S3_KEY=...
ROWSAFE_REPO_S3_KEY_SECRET=...
ROWSAFE_REPO_CIPHER_PASS=...

Add the agent to your compose file:

compose.yml
services:
  app:
    image: ghcr.io/example/app:latest
    user: "1000:1000"
    volumes:
      - appdata:/rails/storage                      # production.sqlite3 lives here

  rowsafe-agent:
    image: ghcr.io/rowsafe/agent:sqlite
    hostname: db-1                                  # the host name Rowsafe shows
    user: "1000:1000"                               # the same user as your app
    restart: unless-stopped
    environment:
      ROWSAFE_SQLITE_PATHS: /data/production.sqlite3   # several: separate them with ":"
    env_file: rowsafe-agent.env
    volumes:
      - appdata:/data                               # the app's volume, read-write
      - rowsafe-state:/var/lib/rowsafe

volumes:
  appdata:
  rowsafe-state:

ROWSAFE_SQLITE_PATHS are paths inside the agent's container. Keep the volume on local disk, never tmpfs or a network drive. Start it and add the database (Databases, then Add database, or the CLI):

docker compose up -d rowsafe-agent
rowsafe adopt app --host db-1 --engine sqlite --path /data/production.sqlite3
rowsafe apply app

Keep the rowsafe-state volume: it holds the host's identity. Lose it and you enroll again.

To update, pull the newest image and recreate only the agent (your app keeps running):

docker compose pull rowsafe-agent && docker compose up -d rowsafe-agent

Limits

No database server. SQLite runs inside your app, so these features don't exist for it:

FeatureWhy
RestartNo database server to restart.
StandbyNo database server to replicate.
Connection poolingNo network connections to pool.
UpdatesSQLite is updated with your app.
Major upgradesSQLite is upgraded with your app.
Databases & usersOne file, no users of its own.
LogsNo log of its own; your app's logs have its errors.

Not available for SQLite:

  • Tuning: your app sets SQLite's options when it opens the file.
  • Moving in from Turso or Cloudflare D1 isn't available yet.

Also good to know:

  • Restores to any second and Marks need WAL mode. Otherwise, only to a backup (daily by default).
  • Network drives are refused (NFS, SMB/CIFS, sshfs...).
  • Let Rowsafe checkpoint. If your app runs PRAGMA wal_checkpoint(TRUNCATE) or RESTART, Rowsafe steps aside after about two seconds, then takes a fresh full copy each time. Rowsafe checkpoints itself once changes are copied, so -wal doesn't grow.
  • A fresh full copy starts by itself when the stream of changes breaks (file replaced, page size changed, or -wal reset while the agent was stopped). Everything before the break stays restorable up to it.
  • Restores are to the second: each change is stamped within about a second of its commit.
  • Virtual tables aren't compared in Rewind; tables without a primary key are matched by row number, which VACUUM can change.
  • Find the moment, previews, safe copies and clones work on restored copies, each needing about the file's size free under /var/lib/rowsafe (clones: in their folder).
  • No query statistics, so no slow queries or unused-index checks; recommendations come from the schema.
  • Safe copies have no password: they're files only the agent's user and root can read. Copy one to your computer with your own server access.
  • Clones aren't masked yet, go only into folders root allowed (--sqlite-clone-dir), and never overwrite a file.
  • Security fixes need root's permission (--allow-sqlite-modes) and only ever remove other users' access.
Edit on GitHub