# Safe copies

> A masked copy of your database, on its own server, for developers and AI agents to test against.

Source: https://rowsafe.sh/docs/guides/safe-copies

A **safe copy** is a copy of your database with real data shapes but fake personal data, for tests, developers and AI agents. Rowsafe restores it on the database's server from your backups, masks personal data, and only then opens it to the addresses you choose. It deletes itself after a day unless you keep it longer. Nothing leaves your server.

Works for PostgreSQL, MySQL, MariaDB, MongoDB, ClickHouse, Redis, Valkey and [SQLite](#sqlite). SQLite, Redis and Valkey copies can also be **structure only** (no rows, or no values). Engine details: [Other engines](#other-engines).

## Make one

**Dashboard**

1. Open the database, then **Guard → Safe copies**.
2. Click **Create a safe copy**. Check **Who can connect** (your address is filled in) and **Where it listens** (the server's private address by default).
3. Click **Create safe copy** and save the connection string: the password is shown only once.

It's ready a few minutes later, when the page says **Ready**.

**CLI**

```sh
rowsafe copies create app
```

It waits until the copy is ready and prints the connection string once. By default, only the address Rowsafe sees your computer connect from may use it.

| Option or command                                | What it does                                      |
| ------------------------------------------------ | ------------------------------------------------- |
| `--allow 10.8.0.0/24`                            | Allows another address or range (repeat for more) |
| `--listen public` or `--listen 203.0.113.41`     | Where it listens                                  |
| `--hours 72`                                     | Keeps it longer                                   |
| `--db NAME`                                      | The database in the connection string             |
| `rowsafe copies app`                             | Lists copies                                      |
| `rowsafe copies extend app ID` / `delete app ID` | Keeps one longer, or deletes it                   |
| `rowsafe copies password app ID`                 | Makes a new password                              |

On a server Rowsafe protects on its own (no dashboard), `sudo rowsafe copies create app --masked --port 55440` makes one on localhost only, on the port you choose: see [Rowsafe on your server](https://rowsafe.sh/docs/guides/no-account-server#safe-copies-for-development).

**AI agents (MCP)**

`create_safe_copy` makes a masked copy (agents can't make an unmasked one). `list_safe_copies` shows when it's ready; `delete_safe_copy` removes it. Pass `allow_from` with the address of the machine the agent runs on.

- **Local MCP server** (`rowsafe mcp`): the password is made on your machine, and the tool returns the connection string once.
- **Remote endpoint:** Rowsafe never makes a password, so the copy starts without one. The agent gives you a dashboard link: click **Set password** there and give the agent the connection string.
- **Apps signed in with Rowsafe** get `create_safe_copy`, `extend_safe_copy` and `delete_safe_copy` only with **Act for you**. An API key and a local `rowsafe mcp` always have them.

## Connect

```sh
psql "postgresql://rowsafe_sc_5k2m9x7q4t1v:PASSWORD@10.0.4.12:55440/app?sslmode=require"
```

Other engines use their own form (`mysql://`, `mongodb://`, `clickhouse://`, `rediss://`), always with TLS.

- **The password is made on your computer** (browser, CLI or local `rowsafe mcp`) and never reaches Rowsafe, which only passes on its verifier or hash (SCRAM-SHA-256, `caching_sha2_password`, `mysql_native_password` or SHA-256, per engine). The API refuses a copy without one. Passwords are random (24 characters), so a hash can't be guessed back. Copies from the remote MCP endpoint start with no password: nobody can log in until one is set.
- **Lost it?** Click **Set password** (or **Reset password**) on the copy, or run `rowsafe copies password app ID`. The old one stops working within seconds.
- **TLS is required.** Each copy has its own self-signed certificate, which the connection strings don't check; save it to check it. To use your own, set `ROWSAFE_COPY_TLS_CERT` and `ROWSAFE_COPY_TLS_KEY` on the server.
- **Only allowed addresses get in.** Others are refused before a password is asked.
- **You can write to it** (migrations, tests, fixtures). The login can change your databases but not the server (PostgreSQL: a role that owns your tables, not a superuser; ClickHouse: a regular user; others: see [Other engines](#other-engines)).

### Reaching the port

Copies listen on ports 55440 to 55539 (`ROWSAFE_COPY_PORTS`): open that range to your addresses in any firewall in front of the server. If you connect through another address or DNS name, set **Host name to connect to** (`--connect-host`).

## Masking

Rowsafe suggests a choice for every column from its name and type, and applies it on the server before anyone connects. Review them in **Guard → Masking** (or `rowsafe masking app`). New columns get a suggestion automatically.

| Choice                           | What the value becomes                                                                                                                                           |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email                            | A fake, unique email: `olivia.3f9a2c1b7e4d5a6b@example.com`                                                                                                      |
| First name, Last name, Full name | Common names                                                                                                                                                     |
| Street address, City             | Made-up addresses and cities                                                                                                                                     |
| Same format                      | Digits stay digits and letters stay letters: phone numbers, postcodes, IDs, card numbers, tokens keep their shape                                                |
| IP address                       | A private address (`10.x.x.x`, or `fd00::` for IPv6)                                                                                                             |
| Password hash                    | bcrypt hashes become the hash of `rowsafe-copy`, so you can sign in to your app as any user with that password; other hashes keep their format but match nothing |
| Lorem ipsum                      | Placeholder text of about the same length                                                                                                                        |
| Numbers ±10%                     | Each number moved by up to 10%                                                                                                                                   |
| Dates ±30 days                   | Each date moved by up to 30 days                                                                                                                                 |
| JSON strings                     | Every text value inside the JSON masked; keys, numbers and structure stay                                                                                        |
| Empty (NULL)                     | No value                                                                                                                                                         |
| Keep                             | The real value                                                                                                                                                   |

The same value always masks the same way (with a key that stays on your server), so joins match and unique columns stay unique. Rowsafe then rebuilds table statistics (and PostgreSQL's materialized views), which would otherwise hold real values.

**No masking** is possible for people allowed to see production data: an admin chooses it and types the database's name, and it's audited. AI agents never get an unmasked copy.

## Limits and costs

- **Plans:** live safe copies at a time, across the organization: Free 1, Pro 5, Business 20. Each is deleted by itself after 24 hours by default (at most 7 days), even if Rowsafe is unreachable.
- **It runs on the database server**, at low priority, and needs free disk: about 1.3 times the cluster's size plus 1 GB. When the agent restarts (an update, a reboot), the copy restarts too, dropping connections for a few seconds.
- **Data is as fresh as your backups:** at most about a minute behind production (ClickHouse: its newest backup).
- **Only masked columns are masked.** Personal data in columns you keep (notes, JSON, logs) stays, and large objects aren't masked. Old versions of masked rows remain in the copy's files, readable only by a superuser, which no copy login is.
- **Docker sidecar agents can't make safe copies** (the copy would be unreachable from outside the container). Previews work there.
- **What reaches Rowsafe:** table and column names and types (for the masking review), counts and sizes. Never the data.

## SQLite

A SQLite safe copy is a **new file on the database's server**: no port, no login, no password.

- **Masked copy:** the file as of the newest point in your bucket (rollback-journal mode: the newest daily backup), masked by your [rules](#masking) with the app's triggers set aside, then `VACUUM`ed so no original value stays in free pages. If a masked value would break a constraint, the column is emptied.
- **Structure only:** tables, indexes, views and triggers, no rows (`rowsafe copies create app --structure`).

The file stays in a private folder (`0700`) under `/var/lib/rowsafe/rewind/sqlite-copies`, readable only by the agent's user and root (`0600`). To get it onto your computer, use the command under **Do it yourself** on the copy's card (`scp`, or `docker compose cp`): Rowsafe can't hand files over end-to-end encrypted yet. It's deleted when it expires or when you click **Delete**.

FTS5 tables are masked or rebuilt (contentless ones emptied). FTS3/4, R\*Tree and your app's own extensions, and the triggers using them, are left out.

## Other engines

**MySQL and MariaDB**

- **The copy:** latest backup plus every binary log since, masked with no network port open, then opened over TLS only.
- **Logins:** production's accounts are locked. The copy's login works only from the allowed addresses (IPv4 ranges or single IPv6 addresses), with every privilege on your databases and none on the server.
- **Masking:** one `UPDATE` per masked column, so tables without a primary key are masked too. Triggers on masked tables run during masking.

**MongoDB**

- **The copy:** latest backup plus the oplog since, masked with no TCP port open, then started with access control and TLS only.
- **Logins:** production's users are removed. The copy's user (`readWriteAnyDatabase`, `dbAdminAnyDatabase`) signs in only from the allowed addresses.
- **Masking:** the review lists fields from each collection's `$jsonSchema` validator, or a small sample of documents read on your server (two levels deep; only names and types reach Rowsafe). Fields inside arrays, and `_id`, aren't masked.

**ClickHouse**

- **The copy:** your newest backup (one every hour), masked with one mutation per table, then opened with plain ports closed: native protocol over TLS on the copy's port, plus HTTPS on a second, random port for the agent.
- **Logins:** production's users aren't in the copy; its only login works from the allowed networks.
- **Not masked:** columns in a table's sorting, primary or partition key, and tables outside the MergeTree family (ClickHouse can't change them in place). The masking report lists them.

**Redis and Valkey**

- **The copy:** the newest point in your bucket, in a temporary server on a private Unix socket only.
- **Masking:** per key pattern and field, by your rules, by names, and wherever a value looks like an email, phone number, token or JSON. Times to live are kept.
- **Structure only:** every key with its type and time to live, every value a placeholder (`rowsafe copies create --structure`, or **More options**).
- **Logins:** Redis can't limit logins by address, so Rowsafe's agent listens on the copy's port, lets in only allowed addresses, speaks TLS, and passes connections on. The default user is off; the copy's login can't run admin commands.
- Keys of module types (RedisJSON, search) are removed.
