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:ModifyDBBranchSettingson the database;rds:DescribeDBBranchesto 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:DescribeDBInstancesto 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.
- Open the database, then choose Branches.
- 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 (emailat first), then choose Add rule. Repeat for each column. - Choose Save settings. Rules you add or remove take effect only when you save.
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"}'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" }
]
}Not available in Terraform. 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
- On the Branches tab, under A branch per pull request, choose the repository in the list (Off turns pull-request branches off).
- (Optional) Enter the target branches, separated by commas; empty means the repository's default branch.
- Choose Save settings.
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.
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"] }
}Not available in Terraform. 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):
dcloud deploy database bind app-id --db-instance-id ewdb-0123456789ab --db-branch-id ewbr-0123456789abThe 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
GET /rds/api/instances/{id}/branch-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).