# Configure masking and pull-request branches

Replace sensitive columns on every branch with masking rules, and give every pull request a branch of its own.

Masking rules and pull-request branches are settings of the database, and one request replaces
both. Replace _ewdb-0123456789ab_ with your database's id and _appdb_ with the database inside it.

## Prerequisites

- Permission for `rds:ModifyDBBranchSettings` on the database; `rds:DescribeDBBranches` to see
  the **Branches** tab and read the settings.
- For pull-request branches, a Deutsche Cloud Git repository in the same organization.
- In the console, also `rds:DescribeDBInstances` to open the database's page (without it the page is
  not found).

## Set masking rules

Masking rules belong to the database and apply to every branch: there is no way to ask for an
unmasked branch while rules exist. For real data, restore the database into a new database instead;
that is audited as `rds:RestoreDBInstance`.

**Console**
1. Open the database, then choose **Branches**.
2. Under **Masking rules and pull requests**, check the database and schema in the first two
   fields (they start as the database's own database and `public`), enter the table and the column,
   choose the method (`email` at first), then choose **Add rule**. Repeat for each column.
3. Choose **Save settings**. Rules you add or remove take effect only when you save.

**CLI**
```sh
dcloud rds branches set-settings ewdb-0123456789ab \
  --masking '{"database": "appdb", "table": "customers", "column": "email", "method": "email"}' \
  --masking '{"database": "appdb", "table": "customers", "column": "phone", "method": "phone"}' \
  --masking '{"database": "appdb", "table": "customers", "column": "full_name", "method": "name"}' \
  --masking '{"database": "appdb", "table": "orders", "column": "note", "method": "redact"}'
```

**API**
```http
PUT /rds/api/instances/ewdb-0123456789ab/branch-settings
{
  "masking": [
    { "database": "appdb", "table": "customers", "column": "email", "method": "email" },
    { "database": "appdb", "table": "customers", "column": "phone", "method": "phone" },
    { "database": "appdb", "table": "customers", "column": "full_name", "method": "name" },
    { "database": "appdb", "table": "orders", "column": "note", "method": "redact" }
  ]
}
```

**Terraform:** not available. Branch settings are not a Terraform resource.

`schema` defaults to `public`. A database has at most 200 rules, and one column has at most one
rule: a second is refused (400) with `<schema>.<table>.<column> in <database> has two rules`.

| Method   | Writes                                                                   |
| -------- | ------------------------------------------------------------------------ |
| `null`   | NULL (the column must be nullable)                                       |
| `redact` | `REDACTED`                                                               |
| `hash`   | md5 of the value: deterministic, so equal values stay equal, joins match |
| `email`  | `user-<12 hex>@example.invalid`, derived from the value                  |
| `phone`  | `+00` and ten digits derived from the value                              |
| `name`   | `Person <6 hex>`, derived from the value                                 |

NULL stays NULL. Rules are applied with triggers and foreign-key checks off, one `UPDATE` per
table in one transaction per database, then `VACUUM (ANALYZE)`. A rule for a database, table or
column that does not exist is skipped and named in **Activity**. The pool records the rule set it
masked the base with; after a change the **Branches** tab shows **Masked** … `with older rules: the
next branch refreshes the base`, and the next branch refreshes it. Branches that already exist keep
the data they were masked with.

## Give every pull request a branch

**Console**
1. On the **Branches** tab, under **A branch per pull request**, choose the repository in the
   list (**Off** turns pull-request branches off).
2. (Optional) Enter the target branches, separated by commas; empty means the repository's default
   branch.
3. Choose **Save settings**.

**CLI**
```sh
dcloud rds branches set-settings ewdb-0123456789ab \
  --masking '{"database": "appdb", "table": "customers", "column": "email", "method": "email"}' \
  --pull-requests '{"gitRepositoryId": "3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f", "targetBranches": ["main"]}'
```

Pass the masking rules again: the request replaces both settings.

**API**
```http
PUT /rds/api/instances/ewdb-0123456789ab/branch-settings
{
  "masking": [{ "database": "appdb", "table": "customers", "column": "email", "method": "email" }],
  "pullRequests": { "gitRepositoryId": "3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f", "targetBranches": ["main"] }
}
```

**Terraform:** not available. Branch settings are not a Terraform resource.

A pull request into one of the target branches gets a branch `pr-<number>` when it opens or
reopens, and loses it when it closes or merges. Pushing to the pull request keeps the branch and its
data. A pull-request branch has no lifetime of its own and cannot be given one. When the branch
serves, a comment on the pull request gives the connection string and the Secrets entry (never a
password). When the branch cannot be cut (the branch quota is reached, or the database has no
completed backup yet), the pull request gets none; the pull request itself is not affected.

**Bind a preview app** to the branch (needs `deploy:ManageDatabaseBinding` on the app and
`rds:GetDBBranchCredentials` on the database; the branch must be available, otherwise the bind is
refused with `The branch <name> is <status>`, 409):

```sh
dcloud deploy database bind app-id --db-instance-id ewdb-0123456789ab --db-branch-id ewbr-0123456789ab
```

The app gets `DATABASE_URL` and the `PG*` variables for the branch's master user and port, without
a pooler, at its next rollout (pass `--redeploy` to roll it out now).

**In a workflow of the pull request**, `${{ secrets.DCLOUD_BRANCH_DATABASE_URL }}` is the branch's
`DATABASE_URL` with its master password. It is not a stored secret: it is resolved when the job is
planned, for the user the run executes as, who needs `rds:GetDBBranchCredentials` on the database.
A branch still being cut is waited for, up to 90 seconds. It is empty when the run is not a pull
request's, the user lacks that permission, or the branch is not serving yet (the first branch of a
database builds its pool, which takes minutes: re-run the job).

## Result

`rds.branches.get-settings` returns the rules and the pull-request settings, and **Activity**
records the change with the number of rules. Changed rules make the next branch refresh the pool
base first, so no branch is served unmasked. Branch settings are set on the database itself: on its
`<name>-branches` pool machine they are refused with `Set branch settings on the parent database.`
(400).

## Related

- [Branches](branches.md)
- [Create a branch](create-a-branch.md)
- `rds.branches.set-settings` · `dcloud rds branches set-settings`
