# Seed data without personal data

> Give previews realistic data: dump your database, take the personal data out on your own machines, put the dump in your storage and name it as a seed, or use Neon's and Xata's own anonymized copies. Why Stagd never gets the real thing.

A seed is the data a preview's database starts with: a dump in your own storage, restored once when the preview is made. This guide makes one that looks like production but holds no one's personal data, and keeps it fresh without anyone thinking about it.

The order matters. **The personal data comes out before the dump leaves your network.** Stagd only ever sees the anonymized file.

```text
production ──► scratch copy ──► anonymize ──► dump ──► your storage ──► Stagd ──► preview
└──────────────── on your machines ────────────────┘
```

## Why it's done this way

A preview is a place for showing and trying things, not for keeping data safe. Anything in its database can end up in front of people who'd never be let near production:

- **Everyone who can open the preview** sees what the app shows. That's your org's members, and anyone with the link if the preview is [public](https://stagd.dev/docs/reference/cli.md#previews).
- **Anyone who can open a pull request** decides what the preview runs. A change to the app, or to `stagd.yaml`, can print every table.
- **What the app makes from it** is kept and shown: captured mail and text messages, logs, traces, screenshots, the preview's thumbnail.
- **Coding agents** read previews through [MCP](https://stagd.dev/docs/reference/mcp.md) and the CLI, and send what they read to their model's provider.
- **The data travels.** A seed is streamed from your storage through Stagd to your compute. Stagd keeps no copy, but a preview that sleeps on compute that can't pause it has its data saved with us until it wakes.

None of that is a problem for made-up people. For real customers it's a breach waiting to happen, and under GDPR you'd need a reason to use their data for testing at all; usually there isn't one.

So Stagd doesn't anonymize for you, on purpose. To do it, the real data would have to reach Stagd first. Doing it on your side means personal data never leaves the place it already lives, under the agreements you already have.

## What to change

Go through your schema table by table. Anything that points to a real person goes:

| Kind | Examples | Make it |
|---|---|---|
| Who someone is | Names, emails, phone numbers, addresses, birth dates, national ids | Fake, but the right shape: `user1234@example.test`, a name from a list |
| How to reach them | Push tokens, webhook URLs, Slack ids | Empty |
| Secrets | Password hashes, API keys, OAuth tokens, sessions, TOTP seeds | Empty, or one known hash for testers |
| What they wrote | Comments, messages, support tickets, notes, uploads' names | Lorem ipsum, or drop the rows |
| Where they were | IP addresses, user agents, locations, audit logs | Empty, or drop the table |
| Money | Card fingerprints, IBANs, payment provider ids | Fake, or empty |

Free text is where personal data hides best: a support ticket holds an address, a note holds a phone number. When in doubt, replace the whole column.

Keep what makes the data useful: ids and the links between tables, counts, dates (move them if they say too much), statuses, and how much of everything there is. Use **`.test`** or **`example.com`** for every email: mail to them goes nowhere, and Stagd's [mail capture](https://stagd.dev/docs/reference/stagd-yaml.md#services) shows it to you.

Then add your [testers](https://stagd.dev/docs/reference/stagd-yaml.md#testers): a few users with known emails, such as `admin@acme.test`, so people and Stagd can sign in.

## On Neon or Xata: anonymize where the database is

If your database is on Neon or Xata, you may not need a dump at all. Both can make an anonymized copy of production inside their own service, and a preview can start from that copy. The rule is the same: the personal data comes out before Stagd is let near it.

### Neon

Neon's [anonymized branches](https://neon.com/docs/workflows/data-anonymization) are a copy of a branch with masking rules applied once, as it's made, using PostgreSQL Anonymizer. Make one from production, in the Console or with the API, and give it a name such as `anonymized`. The Console offers some masking functions; the API and SQL have all of them.

Then fork each preview's branch from it, not from production, with [`database.neon`](https://stagd.dev/docs/reference/stagd-yaml.md#database):

```yaml
database:
  neon:
    project: billowing-sound-61277569
    parent: anonymized
```

And on the Neon integration, turn on **Only some branches may be forked** and list only the anonymized branch, as `<project>/<branch>` ([Connect integrations](https://stagd.dev/docs/guides/connect-integrations.md#neon)). Without it, a pull request can change `parent` to production, and its preview would get the real data.

To bring it up to date, make the anonymized branch again from production; running the masking again on the same branch only masks data that's masked already. Neon's [GitHub Action](https://neon.com/docs/workflows/data-anonymization-github-actions) can do it on a schedule. The rules are per branch, so keep them in the repository and give them to each new one.

### Xata

[Xata](https://xata.io/docs/core-concepts/anonymization) masks while it copies production into a staging replica, with [pgstream](https://github.com/xataio/pgstream) and its transformers, and its branches are made from that replica. A branch never holds the real data.

Stagd doesn't fork Xata branches yet; it's coming. Until then, dump the staging replica, which is anonymized already, and use the dump as a seed: start at [Check it](#check-it).

### Either way

Their masking is only as good as the rules. A new column, or personal data in a JSON column, goes through as it is until someone adds a rule for it. Look at the anonymized branch now and then as you'd [check a dump](#check-it).

## The safe way, for any database

Restore the dump into a scratch database on your own machine or CI, change it there with plain SQL, and dump it again. It needs no new tools, and you can look at the result before it goes anywhere.

```sh
# 1. A scratch copy of production
docker run -d --name scratch -e POSTGRES_PASSWORD=scratch -p 5433:5432 postgres:18
pg_dump --format=custom "$PROD_DATABASE_URL" > prod.dump
pg_restore --no-owner --dbname=postgres://postgres:scratch@localhost:5433/postgres prod.dump

# 2. Take the personal data out
psql postgres://postgres:scratch@localhost:5433/postgres -f anonymize.sql

# 3. Dump what's left, without owners or grants a preview hasn't got
pg_dump --format=custom --no-owner --no-privileges \
  postgres://postgres:scratch@localhost:5433/postgres > app-anonymized.dump

# 4. Delete the real data
rm prod.dump && docker rm -f scratch
```

`anonymize.sql` is yours, kept in the repository and reviewed like code:

```sql
UPDATE users SET
  email      = 'user' || id || '@example.test',
  name       = 'User ' || id,
  phone      = NULL,
  password   = NULL,
  last_ip    = NULL;

UPDATE addresses SET street = id || ' Test Street', postcode = '0000';
UPDATE tickets   SET body = 'Lorem ipsum dolor sit amet.';

TRUNCATE sessions, api_tokens, audit_log;

-- Testers: known users Stagd signs in as
UPDATE users SET email = 'admin@acme.test' WHERE id = 1;
UPDATE users SET email = 'member@acme.test' WHERE id = 2;
```

For MySQL and MariaDB it's the same with `mysqldump` and `mysql`; for MongoDB, `mongorestore`, an update script in `mongosh`, and `mongodump --archive`.

**When the schema changes,** the script has to as well. A new column with an email in it goes out with the next dump unless someone adds it. Make it part of the pull request that adds the column, and check the dump (below).

## With a tool

Tools save you writing the SQL, and some know realistic fakes. All of these run on your side.

### PostgreSQL Anonymizer

[PostgreSQL Anonymizer](https://postgresql-anonymizer.readthedocs.io/) is a Postgres extension: you label each column with how to mask it, and it does the rest. Install it in the scratch database, not in production, and mask it there for good (static masking):

```sql
CREATE EXTENSION anon;
SELECT anon.init();

SECURITY LABEL FOR anon ON COLUMN users.email IS 'MASKED WITH FUNCTION anon.dummy_free_email()';
SECURITY LABEL FOR anon ON COLUMN users.name  IS 'MASKED WITH FUNCTION anon.dummy_last_name()';
SECURITY LABEL FOR anon ON COLUMN users.phone IS 'MASKED WITH VALUE NULL';

SELECT anon.anonymize_database();
```

Then dump as above, with `--no-security-labels --exclude-extension=anon` so the rules and the extension stay out of the seed (`--exclude-extension` needs `pg_dump` 17 or later; before that, drop the extension in the scratch database first). Keep the labels in a file in the repository, next to your migrations, so a new column without one is easy to spot in review.

It can also mask while `pg_dump` runs, for a role that's labelled as masked, without a scratch copy. Its docs warn that such dumps may not be consistent, so the scratch copy is the safer way.

### Greenmask

[Greenmask](https://greenmask.io/) dumps Postgres and changes values on the way, from a YAML file of transformers per table and column, keeping foreign keys in step. It writes `pg_dump`'s directory format; make one file of it with `greenmask restore` into a scratch database and `pg_dump`, as above.

### nxs-data-anonymizer

[nxs-data-anonymizer](https://github.com/nixys/nxs-data-anonymizer) reads a plain SQL dump from Postgres, MySQL or MariaDB on stdin and writes it out changed, so it fits in a pipe:

```sh
pg_dump --no-owner --no-privileges "$PROD_DATABASE_URL" \
  | nxs-data-anonymizer -t pgsql -c anonymize.yaml \
  | zstd > app-anonymized.sql.zst
```

The real data is only ever in memory, never in a file, but nothing checks it on the way, so check the result.

## Check it

Before a dump goes to your storage, look for what shouldn't be there. Restore it somewhere and search for things you know are real: your own email, your company's domain, a customer's name.

```sh
pg_restore app-anonymized.dump | grep -i -E '@acme\.com|@gmail\.com|\+47[0-9]{8}' | head
```

Anything that turns up means a column was missed. Fix the script, not the dump.

## Put it in your storage

[Connect](https://stagd.dev/docs/guides/connect-integrations.md) the storage your seeds are kept in, with a key that only reads, then upload the dump to it. Compressed with gzip, zstd, xz or bzip2, or not:

```sh
zstd app-anonymized.dump
aws s3 cp app-anonymized.dump.zst s3://acme-seeds/app/2026-11-21.dump.zst
# or: az storage blob upload --container-name seeds --name app/2026-11-21.dump.zst --file app-anonymized.dump.zst
```

Name it as a seed, on the Seeds page or with the CLI:

```sh
stagd seeds add app-anonymized --from seeds --path 'app/*.dump.zst'
```

A pattern picks the newest file it matches at each deploy, so tomorrow's dump is used without anyone changing anything. `stagd seeds find 'app/*.dump.zst' --from seeds` shows the file it picks now.

Then use it in `stagd.yaml`:

```yaml
services:
  postgres:
    seed: app-anonymized
```

Keep only anonymized dumps in this storage, and keep it apart from your backups. Stagd can read everything the key can, and a seed's path is easy to change.

## Keep it fresh

Run the whole thing on a schedule where production's data already is: a CI job, a cron job next to your database. For example, nightly in GitHub Actions with a self-hosted runner in your network:

```yaml
on:
  schedule: [{ cron: "0 3 * * *" }]
jobs:
  seed:
    runs-on: [self-hosted, prod-network]
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/make-seed.sh   # restore, anonymize, check, dump, upload
```

Make the job stop when the check finds something, so a missed column means no new seed rather than a leak. Delete old dumps after a while, with your storage's lifecycle rules.

New previews start from the newest dump. Previews that are already live keep their data: [destroy](https://stagd.dev/docs/reference/cli.md#previews) one to start it over.
