# Create a login

Give a person or a tool a read-only or read-write PostgreSQL login of their own instead of sharing the master or app password.

A login is a Postgres role. Its password is filed in Secrets and never in the response. Replace
_ewdb-0123456789ab_ with your database's id and _alice_ with the login's name.

## Prerequisites

- Permission for `rds:CreateDBLogin`. To see the **Logins** tab at all, `rds:DescribeDBLogins`.
- For the console to let the person you name reveal the password: `iam:AttachUserPolicy` on that
  user, and `secrets:GetSecretValue` on the secret yourself (nobody grants what they cannot do).
  Without them the login is still created, the console says the person was not given the
  password, and an administrator grants **Read the value** on its secret later.
- The database is **available**: the login is made on the server with the master credential.
- An enabled encryption key in KMS, to file the password in Secrets.
- In the console, also `rds:DescribeDBInstances` to open the database's page (without it the page is
  not found).

## Create the login

**Console**
1. Open the database, then choose **Logins**.
2. For **Login name**, enter alice.
3. For **Access**, choose **Read-only** or **Read-write**.
4. (Optional) For **For (optional)**, choose the person the login is for.
5. (Optional) For **Expires**, choose **1 day**, **7 days**, **30 days**, **90 days** or
   **1 year** instead of **Never**. An exact date is set through the CLI, the API or
   Terraform.
6. Choose **Create login**.

**CLI**
```sh
dcloud rds logins create ewdb-0123456789ab --name alice --access read \
  --valid-until 2026-12-31T18:00:00Z
```

**API**
```http
POST /rds/api/instances/ewdb-0123456789ab/logins
{ "name": "alice", "access": "read", "forIamUserId": "3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f" }
```

**Terraform**
```hcl
resource "dcloud_db_login" "alice" {
  db_instance_id = dcloud_db_instance.orders.id
  name           = "alice"
  access         = "read"
  valid_until    = "2027-06-30T00:00:00Z"
}
```

## Result

- **Read-only** reads every table in every schema of every database on the server, tables created
  later included, and can write nothing (`pg_read_all_data`).
- **Read-write** can also insert, update and delete (`pg_write_all_data`). It is granted no DDL
  privilege and owns nothing.

Both work on the pooled port, the direct port and through the VPN, with the same connection strings
as the master user (see [Connect to a database](connect.md)). A login reaches every database on the
server; it cannot be scoped to one database or schema.

The password is filed in Secrets as `PG_<IDENTIFIER>_LOGIN_<NAME>_PASSWORD`. When you name a person,
the console grants them **Read the value** on that secret, so they reveal their own password from
the **Logins** tab (**Password**) and nobody else's. Through the API, read it with
`secrets get-value` on the returned `secretId` (`secrets:GetSecretValue`). Revealing it is recorded
in the audit log.

An expiry is any time from five minutes to two years ahead; without one, the login does not
expire. Each change is on **Activity** (phase `logins`).

## If the login is refused

- 400 `A login name is 2–41 characters: lower-case letters, digits and underscores, starting with a letter.`
  Names that are the master user's, `postgres`, `replicator`, `public`, `pgbouncer`, or start with
  `pg_`, `ews_` or `app_` are refused too.
- 400 `The expiry must be at least five minutes from now.` or
  `The expiry can be at most two years from now.`
- 409 `This database already has a login called “alice”.`, or
  `A role called “alice” already exists on this database server.`
- 409 `A secret called PG_…_PASSWORD already exists. Delete it in Secrets, or choose another name.`
- 409 `This database is stopped. Logins can be changed once it is available.` (with the
  database's status).
- 409 `The organization has no enabled encryption key, so the password could not be filed in Secrets. Create a key in KMS first.`
- 404 `That person is not a user of this organization.` for an unknown `forIamUserId`.
- The logins-per-database quota is reached.

## Related

- [Manage a login](manage-a-login.md): expiry, rotation, revocation.
- [Quotas](quotas.md): logins per database.
- `rds.logins.create` · `dcloud rds logins create` · `dcloud_db_login`
