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.
The page shows each step live:
| Step | What happens |
|---|---|
| Save a Mark on app | Only for Now: Rowsafe saves a Mark and forks exactly from it. |
| Hand over access to app's backups | Only 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-2 | Creates 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 data | Only with masking. |
| Start the fork | Your apps can connect. |
| Turn on its own backups | In the fork server's bucket. |
| Take its first backup | From 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 --maskThis 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 appWithout --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.
--attakes2026-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 like | Become |
|---|---|
email, contact_email | user.<random>@example.com |
first_name, last_name, full_name, display_name; name in tables such as users, customers or members | Fake names |
phone, mobile; ssn, iban, passport, tax_id, card_number; api_key, token, secret | Other digits and letters in the same format |
address, street; city | Fake addresses and cities |
ip, last_sign_in_ip, and every inet column | Private addresses (10.x.x.x) |
password, password_hash, encrypted_password | bcrypt 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, dob | Moved by up to 30 days |
JSON columns named address, contact, profile, personal or pii | Emptied (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 targetIf 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, checkcron.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
0660with the folder's default ACL,0640without. - 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-cloneson 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:
| Message | What 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 use | Run 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 version | Install 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 server | Pick 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 empty | Start 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 sent | Check 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 server | Wait until it has finished. |
this database uses 1 tablespace; Rowsafe can't fork those to another server yet | Not 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 first | Add a fork target, see Choose where. |
the PostgreSQL container didn't start on the fork | The 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:
- Stop managing it:
rowsafe remove app-staging --keep-archiving. - Drop its cluster on the fork server:
sudo pg_dropcluster --stop 18 app_staging. In Docker, remove the two services and their volumes. - When you no longer need its backups, delete
/rowsafe/app-stagingfrom 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 progressPOST 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.