Docs / Surfaces / Databases

Databases

SafeGrd backs up four database engines, connecting with a read-only role you create. Each backup reads one consistent snapshot with the engine's own tools. The host compresses and encrypts it before it goes to locked storage. Each engine has its own page.

  1. Your database one consistent snapshot, read-only role
  2. The engine's own tools pg_dump and COPY, mysqldump, mongodump
  3. The host compresses, then encrypts with age
  4. Storage locked under Object Lock
DatabaseWhat is capturedThe host needs
PostgreSQLSchema from pg_dump, rows over binary COPY, one snapshotpg_dump at least as new as the server
MySQL and MariaDBmysqldump --single-transactionThe MySQL client
MongoDBmongodump --archiveThe MongoDB Database Tools
SQLiteOne committed state, through SQLite's online backupNothing

A first backup, and the next one

The first backup each month uploads every table. Later backups read every table again and upload only what changed. Both runs below are real: a host backing up a PostgreSQL database of 70,000 rows to hosted storage.

prod-app-01
$ safegrd daemon run --once
SafeGrd daemon dev started
   Surfaces:            1
   State directory:     /home/safegrd/.safegrd
Surface shop (postgres) is due for backup.
[shop] Epoch e202610-06bca287 opened (first backup). Every table is uploaded once this month.
[shop] 3 tables, 70,240 rows, 3.1 MiB read, 386.9 KiB stored in 2 packs, 532ms.
[shop] Snapshot snap-20261018-024047-450e5d complete. Locked until 2026-11-02: the month's first backup is kept as its monthly copy. Later backups follow the surface's retention.
[shop] That date is capped: a backup is locked no longer than the objects it is built from, and no longer than a trial runs.
Backed up surface shop
prod-app-01
$ safegrd backup --surface shop
Surface shop (postgres): backing up now.
[shop] Incremental, in epoch e202610-06bca287: only what changed since the last run is uploaded.
[shop] 3 tables, 70,552 rows, 3.2 MiB read, 19.1 KiB stored in 2 packs, 453ms.
[shop] Snapshot snap-20261018-024147-da47c0 complete. Locked until 2026-11-02.
Backed up surface shop
   Snapshot ID:     snap-20261018-024147-da47c0
The next backup, after 312 new orders: it read the whole database again and uploaded 19.1 KiB.

Where the connection URL comes from

PostgreSQL, MySQL and MongoDB connect with a URL. You choose where each database's URL is kept, and you can mix the two options on one host. SQLite has no secret. Name the file as database_url: sqlite:///var/lib/app/app.db, with no credential block.

The URL stays on the host the default

The surface's credential block tells the host where to read it. Use from: env with a variable's name, from: command with a command that prints it (such as op read or vault kv get), or from: file with a path. SafeGrd sees the variable's name or the command, and never the URL.

SafeGrd holds the URL from: safegrd

SafeGrd keeps the URL sealed. The host fetches it over HTTPS when the surface backs up and keeps it in memory for that run. Enter it in the setup wizard, or under Credential in the surface's panel in the console.

surfaces:
  - id: "app-database"
    type: "postgres"
    credential:   # the URL stays on the host
      from: env
      name: "APP_DATABASE_URL"
  - id: "billing-db"
    type: "mysql"
    credential:   # SafeGrd holds the URL
      from: safegrd

Give each surface its credential in one place. If a surface has both from: safegrd and a database_url on the host, the backup stops with a configuration conflict error. Letting SafeGrd hold the database credential does not give it the encryption key. You make those two choices separately (Security and key custody).

Each table across backups

Open a database surface's panel in the console and choose the Tables tab. It has one row per table across the last 30 backups. Each row draws the table's row count as a line. A filled dot marks a backup that a drill restored to that row, and a square marks one where it could not.

Each row also shows:

You can sort by name, rows, size or change, and filter by name. Open a row to see the table's columns and what you need to restore that table alone: the sequences it owns and the tables its foreign keys point at. safegrd restore --table names those and does not load them.

The Overview tab shows the surface's trend over the last 30 days, under Trend:

The trend is computed from the figures each backup already reports, kept as one row per day. It is never read from the backup's contents. Each run is compared with the same backup that Threat Shield compared it with.

The columns come from the backup. Each PostgreSQL, MySQL, MariaDB and SQLite backup records every table's columns and a hash of its definition, read inside the backup's own transaction. A MongoDB backup records each collection's top-level fields across all its documents, with their BSON types, as the collection's columns. Threat Shield compares them between backups and warns you when a table loses a column (what each snapshot records).

What a Fire Drill checks

Both kinds of drill start from the snapshot in storage, decrypted with your key. An in-memory drill reads every row back and counts every table with no database running, which proves the data reads back whole. A sandbox drill loads the schema and rows into an empty database and counts every table there, which also proves the schema, constraints and indexes load. Both compare what they found with what the backup recorded. Snapshot from storage downloaded and decrypted with your key In memory reads every row back counts every table no database runs Sandbox loads schema and rows into an empty database counts every table there proves the data reads back whole also proves the schema, constraints and indexes load Compared with the backup tables, rows, extensions, roles
An in-memory drill checks the data. Only a sandbox drill runs the schema, so it is the one that catches a constraint or an index that will not build.
DatabaseWhat the drill checks
PostgreSQLThe number of tables, every table's rows, the extensions and the roles the schema names, against what the backup recorded. In memory, it reads every row back with no database server. A sandbox drill (--sandbox-target, or drill.sandbox_url on the host) loads the schema and the rows into an empty database, so the constraints and indexes get built too. On a plan with sandbox drills, a host with no drill.sandbox_url restores into a throwaway cluster that it starts from its own PostgreSQL server (Daemon).
MySQL and MariaDBThe dump ran to its end, and every table the backup recorded is in it, with its structure and its row count. A sandbox drill (--sandbox-target mysql://…, or drill.sandbox_url) loads the dump into a scratch database, counts the tables there and drops it (the sandbox account).
MongoDBThe archive ran to its end, and each collection's document count and checksum match what mongodump recorded. A sandbox drill restores the archive into a temporary database with mongorestore, counts each collection there and drops them (the sandbox user).
SQLiteA full restore. The database file is written out, opened and run through PRAGMA integrity_check. Every table's rows are counted against the backup, then the file is deleted.

The table on the Surfaces page compares the drills for every kind of surface, files and mail included.