# Fork a database

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

Source: https://rowsafe.sh/docs/guides/fork

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](#mysql-and-mariadb), [ClickHouse](#clickhouse), [MongoDB](#mongodb), [Redis and Valkey](#redis-and-valkey), [SQLite](#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](https://rowsafe.sh/docs/guides/restore#server-lost-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](#choose-where), 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](#mask-personal-data).

### Confirm

For another server, confirm its **key fingerprint** (see [Security](#security)). Click **Fork**.

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](https://rowsafe.sh/docs/guides/rowsafe-cloud), billed by the hour, or a [connected cloud account](https://rowsafe.sh/docs/guides/create-a-server)), 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](https://rowsafe.sh/docs/guides/teams#audit-log). AI agents can clone onto Rowsafe Cloud [as the person who connected them](https://rowsafe.sh/docs/guides/agent-autonomy), after telling you the price.

## Fork with the CLI

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

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

```text
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:

```sh
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](https://rowsafe.sh/docs/reference/cli#fork).

## 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](https://rowsafe.sh/docs/concepts/restore-points).

## Choose where

**A new cluster**

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:

```text
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](https://rowsafe.sh/docs/guides/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.

**An empty cluster**

Rowsafe can use an existing cluster that is **empty**, **running**, the **same major version** (not a standby), and that **Rowsafe may stop and start** (`sudo rowsafe-allow restart` run after it existed). Make one with `pg_createcluster 18 staging --port 5433 --start`.

Rowsafe sets its empty data aside for 7 days and restores the fork in its place. If the fork fails, the data comes back.

**Docker**

In Docker, add a **fork target**: a `postgres` service that waits for the fork in its empty volume, plus an agent sidecar mounting that volume **read-write**. The sidecar is its own server in Rowsafe (own token, bucket and passphrase), where the fork's backups go.

```yaml title="compose.yml"
services:
  postgres-staging:
    image: postgres:17
    restart: unless-stopped
    # Waits until Rowsafe has restored the fork into the volume, then starts on it.
    entrypoint: ["sh", "-c", "until [ -e /var/lib/postgresql/data/rowsafe-fork.done ]; do sleep 2; done; exec docker-entrypoint.sh postgres"]
    volumes:
      - staging-data:/var/lib/postgresql/data
      - staging-socket:/var/run/postgresql
      - staging-spool:/rowsafe-spool

  rowsafe-agent-staging:
    image: ghcr.io/rowsafe/agent:pg17
    hostname: staging-1                           # the server name Rowsafe shows
    user: "999:999"
    restart: unless-stopped
    depends_on: [postgres-staging]
    env_file: rowsafe-agent-staging.env           # its own enrollment token, bucket settings and passphrase
    environment:
      ROWSAFE_FORK_TARGET_DIR: /var/lib/postgresql/data
    shm_size: 256m
    volumes:
      - staging-data:/var/lib/postgresql/data     # read-write: Rowsafe restores the fork into it
      - staging-socket:/var/run/postgresql
      - staging-spool:/rowsafe-spool
      - staging-agent:/var/lib/rowsafe

volumes:
  staging-data:
  staging-socket:
  staging-spool:
  staging-agent:
```

- The env file is like [Run the agent in Docker](https://rowsafe.sh/docs/guides/docker#set-up), with a new token and its own passphrase.
- For `postgres:18`+, mount the volume at `/var/lib/postgresql`, set `ROWSAFE_FORK_TARGET_DIR: /var/lib/postgresql/18/docker`, and wait for `rowsafe-fork.done` there.
- After `docker compose up -d`, the target shows under **Where**. It takes **one** fork.
- The fork has the source's users and passwords. If the source's configuration lived outside its data directory (Debian, Ubuntu), the fork gets the image's defaults, which accept password logins from any address.
- A database in Docker can be forked to another server, not to its own.

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](https://rowsafe.sh/docs/guides/safe-copies#masking) 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](https://rowsafe.sh/docs/guides/safe-copies#other-engines) 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](https://rowsafe.sh/docs/guides/standby#pairing-and-your-secrets). **Rowsafe never sees them**, and the fork server deletes them after the restore.

Compare the fingerprint shown with what the fork server prints:

```sh
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](https://rowsafe.sh/docs/reference/agent-configuration#postgresql-and-the-server).

Only owners and admins can fork. AI agents can't (only [clone](#clone-to-a-new-server)), because a person must compare the key ([Rowsafe refuses](https://rowsafe.sh/docs/guides/agent-autonomy#when-rowsafe-refuses)). Every fork is in the [audit log](https://rowsafe.sh/docs/guides/teams#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](#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](https://rowsafe.sh/docs/guides/safe-copies#sqlite).
- 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](https://rowsafe.sh/docs/guides/redis#clones).

## 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](https://rowsafe.sh/docs/guides/restore#server-lost-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](#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:

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

```text
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.
