Skip to content
Rowsafe
Docs

Fork a database

Clone a database into a new, independent one, as it was now, at any second or at a Mark.

A fork is a new, independent copy of a database as it was now, at any second, or at a Mark, on a server you pick. Use it to give staging real data (with personal data masked), try a migration, or look at yesterday's state. Production isn't touched: the fork is restored from backups.

This page describes PostgreSQL. Other engines: MySQL and MariaDB, ClickHouse, MongoDB, Redis and Valkey, SQLite.

What you need

  • Backups running, with at least one full backup, and the source's server reporting. A server that's gone can't hand over its backups: restore to another server instead.
  • A server with the Rowsafe agent (the same one or another), with the same PostgreSQL major version, a place for the fork, and free disk of the source's size plus 10%.
  • To be an owner or admin.

A fork counts toward your plan's databases. Its backups go to the fork server's own bucket, with that server's passphrase.

Fork in the dashboard

Start

Open the database and click Fork.

When

Pick Now, a time in the recovery window, or a Mark.

Where

Pick the server, then the place on it, for example "A new PostgreSQL 18 on port 5440 (Rowsafe creates it)". A server that can't take the fork says why.

Name and masking

Name the fork, for example app-staging (2 to 40 lowercase letters, digits and dashes). Turn on Mask personal data for any copy people outside production use. See Mask personal data.

Confirm

For another server, confirm its key fingerprint (see Security). Click Fork.

The page shows each step live:

StepWhat happens
Save a Mark on appOnly for Now: Rowsafe saves a Mark and forks exactly from it.
Hand over access to app's backupsOnly for another server: the source's server sends what's needed to read its backups, encrypted to the fork server's key.
Create a new PostgreSQL on db-2Creates the new cluster, or checks the empty one ("Prepare PostgreSQL on db-2").
Restore app as it was at ...Downloads the backup and replays changes up to your moment, privately.
Mask personal dataOnly with masking.
Start the forkYour apps can connect.
Turn on its own backupsIn the fork server's bucket.
Take its first backupFrom then on, the fork is protected.

Then the fork is an ordinary database in your list.

Clone to a new server

No server for the copy? On a PostgreSQL, MySQL or MariaDB database's Fork tab, click Clone. Pick the moment, where it runs (Rowsafe Cloud, billed by the hour, or a connected cloud account), region, size and Delete after (4 hours, 1 day, 7 days or never). Rowsafe creates the server and forks onto it.

  • Delete after counts from when it's ready. An hour before, its creator gets an email. Then Rowsafe deletes the clone's server (never the source). Change it or delete it yourself any time.
  • MySQL clones get MySQL 8.4 and MariaDB clones 11.8, so older versions can't be cloned this way. MySQL needs an Intel or AMD size.
  • If something fails, Rowsafe deletes the server it made and offers Try again.
  • Owners, admins and read-write API keys can clone; each is in the audit log. AI agents can clone onto Rowsafe Cloud as the person who connected them, after telling you the price.

Fork with the CLI

rowsafe fork app --to db-2 --name app-staging --mask

This forks app now to a new cluster on db-2, masked, and prints:

app-staging is ready on db-2:5440, restored to 2026-09-25 10:12:09 CEST (08:12:09 UTC), with its own backups. Open it with: rowsafe status app-staging
Masked 6 columns in 2 tables (1204 rows).

More examples:

rowsafe fork app --to db-1                                  # the same server, a new port; named app-fork
rowsafe fork app --to db-2 --at "2026-09-24 14:04"          # a time, in your time zone
rowsafe fork app --to db-2 --at "10m ago"
rowsafe fork app --to db-2 --mark before-migration-42       # a Mark
rowsafe fork app --to db-2 --port 5441                      # pick the new cluster's port
rowsafe fork app --to db-2 --into-port 5433                 # use an existing empty cluster
rowsafe forks app                                           # the forks made from app

Without --name, it's named <source>-fork. Without --to, the CLI lists the servers that can take it. For another server, type its fingerprint when asked (or pass --fingerprint). All flags: CLI reference.

Choose when

  • Now: Rowsafe saves a Mark (fork-<id>) and forks from it.
  • A time: any second between the oldest kept full backup and the last archived change. --at takes 2026-09-24 14:04, 14:04, 10m ago (your time zone) or RFC 3339.
  • A Mark: in your bucket, after a full backup, like a restore to a Mark.

Choose where

On Debian or Ubuntu, Rowsafe can create a cluster (pg_createcluster) on a port from 5440 to 5499, named after the fork, for example postgresql@18-app_staging. It starts at boot.

Root must allow it. The installer asks:

Create a new PostgreSQL cluster here (ports 5440-5499), when someone forks a database to this server? [Y/n]

Or pass --allow-create-cluster. To allow it later: sudo rowsafe-allow restart create-cluster (permissions). A sandboxed unit creates the cluster and lists it in /etc/rowsafe/created-clusters, so Rowsafe may later stop and start it on request.

A new or empty cluster keeps its own postgresql.conf and pg_hba.conf; ALTER SYSTEM settings come along. A new cluster listens on localhost only.

Mask personal data

Mask personal data (--mask) replaces personal data with fake values before anyone can connect, in every database of the fork. It goes by column name (and type):

Columns named likeBecome
email, contact_emailuser.<random>@example.com
first_name, last_name, full_name, display_name; name in tables such as users, customers or membersFake names
phone, mobile; ssn, iban, passport, tax_id, card_number; api_key, token, secretOther digits and letters in the same format
address, street; cityFake addresses and cities
ip, last_sign_in_ip, and every inet columnPrivate addresses (10.x.x.x)
password, password_hash, encrypted_passwordbcrypt hashes become the hash of rowsafe-copy, so you can sign in to your app on the fork as any user; other hashes become random
birth_date, dobMoved by up to 30 days
JSON columns named address, contact, profile, personal or piiEmptied (NULL)
  • The same value gets the same fake value everywhere, so joins work. The key is thrown away, so nobody can map values back.
  • Triggers don't fire. Masked tables are rewritten (VACUUM FULL) so old values leave the files.
  • Your Guard masking choices apply too.
  • The fork lists every masked column. Read that list before you give anyone access.

MySQL, MariaDB and MongoDB are masked in a private copy before loading. ClickHouse is masked right after the restore, before hand-over (key columns are skipped and listed). Safe copy limits apply. SQLite clones can't be masked yet.

Know what masking doesn't do

  • Real data reaches the fork's server first, and deleted files aren't wiped. If a server must never hold personal data, don't fork to it.
  • It goes by column names. Emails in notes, or personal data in free text, aren't found.
  • JSON isn't masked field by field. Personal-looking JSON columns are emptied if they allow NULL; others keep their data.
  • If masking fails, the fork fails. It never starts unmasked.

What happens

The restore runs with no network listener (private socket only), and it can't write into the source's backups. After masking, the fork starts for real and gets its own backups, Proof, Pulse and Rewind. It isn't linked to the source.

If a step fails, the server is left as it was. A cluster Rowsafe created stays, empty: pick it as an empty cluster next time.

Security

On the same server, nothing moves. To another server, the source's agent encrypts its bucket keys and passphrase to the fork server's key, as for a standby. Rowsafe never sees them, and the fork server deletes them after the restore.

Compare the fingerprint shown with what the fork server prints:

sudo -u postgres rowsafe-agent key
docker compose exec rowsafe-agent-staging rowsafe-agent key   # a Docker fork target

If they differ, stop.

Fork only to servers you trust with the source

While the fork restores, the fork server could read all of the source's backups.

ROWSAFE_STANDBY=pinned (with ROWSAFE_STANDBY_PEERS) limits handoffs to listed fingerprints; off blocks them. See Agent configuration.

Only owners and admins can fork. AI agents can't (only clone), because a person must compare the key (Rowsafe refuses). Every fork is in the audit log.

Limits

  • The same major version on the fork server.
  • The whole cluster: all its databases, users and passwords. If staging is less trusted, change the passwords on the fork.
  • No tablespaces outside the data directory.
  • New clusters only on Debian and Ubuntu, ports 5440 to 5499.
  • Extensions must be installed on the fork server. Missing preloaded libraries are dropped, with a warning. If the fork preloads pg_cron, check cron.job: production's jobs would run there.
  • One fork restore at a time per server.
  • Docker: one fork per fork target. A Docker server can't create clusters.
  • Rowsafe doesn't delete forks: see Remove a fork.

MySQL and MariaDB

  • The place is an empty server of the same version series, kept ready at install (--mysql-standby, or say yes when asked).
  • The agent restores in a private copy, then loads everything, logins included. Nothing restarts.
  • If the binary log is off there, the fork's backup plan turns it on (a restart).

ClickHouse

  • The place is an empty server of the same version or newer, kept ready at install (--clickhouse-clones). Rowsafe restores straight into it.
  • Users and grants aren't copied: create them. Tables reaching other systems (Kafka, S3 queues, MySQL...) and refreshable materialized views are left out.
  • ClickHouse Keeper (Replicated*) databases or tables can't be forked.

MongoDB

  • The place is an empty server of the same version or newer, kept ready at install (--mongodb-clones). Rowsafe restores privately, then copies databases and indexes in.
  • Users and roles aren't copied: create them.
  • For restores to any second on the fork, that server must be a replica set (one member is enough).

SQLite

For SQLite, click Clone: you get a new database file with its own backups, on the same server or another one.

  • Only in folders root allowed at install (--sqlite-clone-dir /srv/sqlite-clones; in Docker, ROWSAFE_SQLITE_CLONE_DIRS). Until then, Clone shows the flag.
  • Never overwrites: the file (and its -wal, -shm, -journal) must not exist.
  • Keeps the source's journal mode. Mode 0660 with the folder's default ACL, 0640 without.
  • No masking yet: use a safe copy.
  • CLI: rowsafe fork app app-staging --host db-2 --file /srv/sqlite-clones/staging.sqlite3.

Redis and Valkey

  • Where: install with --redis-clones on the fork's host. Rowsafe creates a server (ports 6390 to 6399) or takes an empty one, same version or newer.
  • Restored privately, masked if you ask, then copied key by key.
  • Users aren't copied. A server Rowsafe created accepts local connections only until you add users.
  • Masking removes keys of module types. Details: Protect Redis or Valkey.

If it fails

The failed step says why:

MessageWhat to do
Can't fork app now: its server isn't reporting. If it's lost, restore app to another server instead.Wait for the server, or restore to another server.
Rowsafe isn't allowed to create a PostgreSQL cluster there, and there's no empty cluster it may useRun the installer there again with --allow-create-cluster, or give it an empty cluster.
PostgreSQL 17 isn't installed there, and a fork needs the same major versionInstall that version (apt-get install postgresql-17), or pick another server.
its Rowsafe agent is too old to receive a fork (or forks are turned off there)Update the agent there. With ROWSAFE_STANDBY=off, fork on the same server.
not enough free disk in ...: the fork needs about ...Free up disk, or pick another server.
no free port between 5440 and 5499 / port ... is already used on this serverPick another port, or stop what uses it.
the cluster on port 5433 isn't empty (...)Use an empty cluster, or let Rowsafe create one.
the cluster on port 5433 must be running so Rowsafe can check it's emptyStart it: sudo systemctl start postgresql@18-staging.
The fingerprint doesn't match ...'s agent key / the target server's key has fingerprint ..., not ... as confirmed: nothing was sentCheck again with sudo -u postgres rowsafe-agent key on the fork server before you retry.
handing this database's bucket settings to another server is turned off here (ROWSAFE_STANDBY=off ...)Fork on the same server, or change ROWSAFE_STANDBY on the source's server.
another fork is being restored on this serverWait until it has finished.
this database uses 1 tablespace; Rowsafe can't fork those to another server yetNot supported yet.
... (if the time is after the last change that reached the backups, pick an earlier one)Pick an earlier time, or Now.
PostgreSQL runs in Docker there: set it up as a fork target firstAdd a fork target, see Choose where.
the PostgreSQL container didn't start on the forkThe postgres service's entrypoint must wait for rowsafe-fork.done, as in the example.
masking: ... (the fork was never reachable, and it was removed)The reason names the table and what PostgreSQL refused, for example a check constraint the fake values don't meet.

Remove a fork

Rowsafe doesn't delete forks. To remove one:

  1. Stop managing it: rowsafe remove app-staging --keep-archiving.
  2. Drop its cluster on the fork server: sudo pg_dropcluster --stop 18 app_staging. In Docker, remove the two services and their volumes.
  3. When you no longer need its backups, delete /rowsafe/app-staging from the fork server's bucket.

API

GET  /v1/databases/{ref}/forks    forks made from a database, its recovery window, Marks and the servers it can go to
POST /v1/databases/{ref}/forks    start a fork (202, with its progress)
GET  /v1/forks/{id}               one fork and its progress

POST takes name, host_id (ID or name), and optionally placement (new_cluster, empty_cluster or docker), port, at (RFC 3339) or mark, mask, and fingerprint for another server. Without at and mark, it forks now. Needs an API key that can write.

Edit on GitHub