# Manage the master password

Read the generated master password from Secrets, and rotate it.

The master password is generated at creation and filed in **Secrets**; you never type it
anywhere. Replace _ewdb-0123456789ab_ with your database's id.

## Prerequisites

- To read it: `secrets:GetSecretValue` on the database's master secret (and
  `rds:DescribeDBInstances`). Without it the console shows **Reveal** disabled with "The password
  is not shown to you."
- To rotate it: `rds:ModifyDBInstance`. The database must be **available**; in any other status the
  rotation is refused with `409` "A database in status "…" cannot be changed".

## Read the master password

**Console**
1. Open the database, then choose the **Connection** tab.
2. Under **Master password**, choose **Reveal**. The password appears with a copy button, and the
   connection strings above it carry it when copied. Choose **Hide** to hide it again.

If the section says "Not filed in Secrets", the secret has been deleted (or the database predates
it): rotate the password to file a new one.

**CLI**
```sh
dcloud rds instances get ewdb-0123456789ab
dcloud secrets secrets get-value master-secret-id
```

`masterSecretId` in the first command's output is the secret to read.

**API**
Read `masterSecretId` from the database, then the secret's value:

```http
GET /secrets/api/secrets/{masterSecretId}/value
```

**Terraform**
`dcloud_db_instance` exports `master_secret_id`, the secret holding the password.

Reading a secret value is recorded in the audit log.

## Rotate the master password

**Console**
1. On the **Connection** tab, under **Master password**, choose **Rotate master password**.
2. In **Rotate the master password?**, choose **Rotate**. The tab shows "Rotated. Version _n_ is
   current in Secrets."

**CLI**
```sh
dcloud rds instances rotate-master-password ewdb-0123456789ab
```

**API**
```http
POST /rds/api/instances/ewdb-0123456789ab/master-password/rotate
```

**Terraform:** not available. Rotation is an action, not configuration.

## Result

A new password is generated, filed in Secrets as the next version, and set on the database role;
the response carries `secretId` and `version`. Clients using the old password are refused from
that moment; the pooler keeps working. Apps bound to the database with the master credential are
redeployed with the new password, and the Activity tab records "Redeploying _n_ app(s) bound with
the master credential".

If the database refuses the new password, the rotation fails with `502` "The database refused the
new password: …", the previous version stays current in Secrets, and nothing changes for clients.
With no enabled encryption key to file it under, it is refused with `409` "No enabled encryption
key to file the new password under".

A password changed by hand with `ALTER ROLE` is not visible to the platform: the copy in Secrets
stays the old one until the next rotation through the API.

## Related

- [Create a login](create-a-login.md) instead of sharing the master password.
- `rds.instances.rotate-master-password` · `dcloud rds instances rotate-master-password`
