# Require TLS

Refuse clients that do not use TLS, on the pooled and the direct port of every node, after checking which clients would break.

A new database requires TLS unless you cleared **Require TLS** when you created it (the API and
Terraform default to `true` too). A database without the setting accepts plaintext clients until
you turn it on. Replace _ewdb-0123456789ab_ with your database's id.

## Prerequisites

- Permission for `rds:ModifyDBInstance` (and `rds:DescribeDBInstances` to check clients). Without
  it the switch is disabled: "Your policies do not grant rds:ModifyDBInstance."
- The database is **available**. Otherwise the change is refused with `409` "This database is …. The
  TLS setting can be changed once it is available.", and connected clients cannot be listed.
- A database with a certificate. One provisioned before managed PostgreSQL had certificates is
  refused with `409` "This database was provisioned before managed Postgres had certificates, so
  it cannot offer TLS. Restore it into a new database to get one."

## Check which clients would break

Before turning it on, list every session open without TLS right now, on either port of every node.
Those clients break at their next connect; an open session is not cut. What breaks is
`sslmode=disable`, and a driver with no TLS option whose default is plaintext, such as node-postgres
without `ssl`. libpq's default `prefer` keeps working, and so does every app bound from the
console.

**Console**
1. Open the database, then choose the **Connection** tab.
2. Under **TLS**, next to **Clients that would break**, choose **Check connected clients**.

The list shows the clients connected without TLS; **Check again** refreshes it. A client that
connects only now and then (a nightly job) cannot be seen here.

**CLI**
```sh
dcloud rds tls get ewdb-0123456789ab --clients true
```

**API**
```http
GET /rds/api/instances/ewdb-0123456789ab/tls?clients=true
```

**Terraform:** not available. Connected clients are live state, not configuration.

## Turn on Require TLS

**Console**
1. On the **Connection** tab, under **TLS**, turn on **Require TLS**. The console lists the
   connected plaintext clients.
2. In **Require TLS on this database?**, choose **Require TLS**.

**CLI**
```sh
dcloud rds tls set ewdb-0123456789ab --required
```

To stop requiring it: `--no-required`.

**API**
```http
PATCH /rds/api/instances/ewdb-0123456789ab/tls
{ "required": true }
```

**Terraform**
```hcl
resource "dcloud_db_instance" "orders" {
  identifier     = "orders"
  instance_class = "performance-2"
  require_tls    = true
}
```

## Result

The change is applied to every node at once and then checked from outside: a plaintext connection
to each node's two ports must be refused. The response says `verified: true` when it was, and the
console shows "Checked from outside: plaintext is now refused on both ports of _n_ node(s)." A node
that was unreachable keeps its old setting until the maintenance sweep, which keeps applying it
every 15 minutes; the console says "Saved, but not yet in effect everywhere", and **Activity**
records it (phase `settings`).

Turning it off asks **Stop requiring TLS?** and is confirmed with **Stop requiring**.

## Related

- [Connect to a database](connect.md)
- `rds.tls.set` · `dcloud rds tls set` · `dcloud_db_instance`
