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 -- --accountOr 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.sqlite3Safe 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 backup | A 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 change | In WAL mode, every committed transaction reaches your bucket within a few seconds, encrypted. |
| Restore | To any second or a Mark (WAL mode): the newest backup plus every transaction committed by then. In rollback-journal mode, to a daily backup. |
| Marks | A named point, from the dashboard, rowsafe mark app before-migration or an AI agent through Guard. Exact. Needs WAL mode. |
| Proof | Weekly: restore into a scratch file, run PRAGMA integrity_check and foreign_key_check, compare row counts, delete it. |
| Rewind | A copy at any second or Mark next to the live file. Compare table by table and bring missing rows back. |
| Rewind the whole database | Puts the whole file back in place while your app runs. Undo for 7 days. |
| Pulse | File and -wal size, free pages, journal mode, backup lag, last integrity check, busy/locked moments, stale statistics. Most findings have a fix. |
| Files | Your app's folders (uploads), restored to the same moment. |
| Second copy | Backups and changes also go to a second bucket with its own passphrase. |
| Find the moment | When 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. |
| Security | Files open to every user, in a web-served or world-writable folder, or with readable copies nearby. Close to other users in one click. |
| Recommendations | From the schema: foreign keys without an index (tested on a copy, then Create index), tables without a primary key, AUTOINCREMENT, missing statistics. |
| Migration preview | Your migration on a restored copy: time, rows, rebuilt tables, indexes, how long writes would wait. Also for AI agents. |
| Safe copies | A masked or structure-only copy, as a file only the agent's user can read. |
| Clone | The 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, whichVACUUMcan 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.
| Problem | Button | What Rowsafe does |
|---|---|---|
The -wal file keeps growing | Shrink the -wal file | Once 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) pages | Give free space back | Rebuilds 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 date | Refresh statistics | Runs PRAGMA optimize. |
| Continuous backups are off (rollback-journal mode) | Turn on continuous backups | Switches 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;
-waland-shmfiles 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_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:
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 appKeep 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-agentLimits
No database server. SQLite runs inside your app, so these features don't exist for it:
| Feature | Why |
|---|---|
| Restart | No database server to restart. |
| Standby | No database server to replicate. |
| Connection pooling | No network connections to pool. |
| Updates | SQLite is updated with your app. |
| Major upgrades | SQLite is upgraded with your app. |
| Databases & users | One file, no users of its own. |
| Logs | No 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)orRESTART, Rowsafe steps aside after about two seconds, then takes a fresh full copy each time. Rowsafe checkpoints itself once changes are copied, so-waldoesn't grow. - A fresh full copy starts by itself when the stream of changes breaks (file replaced, page size changed, or
-walreset 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
VACUUMcan 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.