# Connect to a database

Connect over TLS with the connection strings on the Connection tab, and verify the server with the platform's CA bundle.

Replace _orders_admin_ and _orders_ with your master user and database, and _ewdb-0123456789ab_
with your database's id.

## Prerequisites

- Permission for `rds:DescribeDBInstances` (also what downloading the CA bundle needs).
- The password: see [Manage the master password](manage-the-master-password.md), or
  [Create a login](create-a-login.md) for a person of their own.
- A client that can reach the endpoint: from the database's network, or from anywhere if the
  database is public (see [Instances, clusters and endpoints](instances-and-clusters.md)).

## Get the connection strings

**Console**
1. Open the database, then choose **Connection**.
2. Copy **Application (pooled)**, **Direct**, or, on a cluster, **Read replicas (pooled)**.

**CLI**
```sh
dcloud rds instances get ewdb-0123456789ab
```

The endpoint address and port are in the output.

**API**
```http
GET /rds/api/instances/ewdb-0123456789ab
```

**Terraform:** not available. A connection is not a resource; `dcloud_db_instance` exports `endpoint_address`, `endpoint_port` and `private_endpoint_address`.

Substitute the password:

```text
postgresql://orders_admin:<password>@192.0.2.7:6432/orders?sslmode=require   # applications
postgresql://orders_admin:<password>@192.0.2.7:5432/orders?sslmode=require   # direct
postgresql://orders_admin:<password>@192.0.2.7:6433/orders?sslmode=require   # read replicas, cluster only
```

The console's strings use the host to connect to: the endpoint's DNS name once the database's
certificate carries it, otherwise its address; for a private database, its address or name inside
the network.

`sslmode=require` encrypts the connection. To also verify that you are talking to your database,
use `verify-full`.

## Connect with verify-full

**Console**
1. On the database's **Connection** tab, choose **Download CA bundle**.
2. Copy **Verify the server (verify-full)** and point `sslrootcert` at the downloaded file.

**CLI**
`dcloud rds exec` downloads the CA and runs your command with it:

```sh
dcloud rds exec -- node migrate.js
dcloud rds exec -- psql "postgresql://orders_admin:<password>@<id>.db.apps.<root-domain>:6432/orders?sslmode=verify-full"
```

It caches the CA as `~/.dcloud/rds-ca.pem`, fetches it again after 30 days or with `--refresh`
(a stale copy is used if the download fails), and runs your command with `NODE_EXTRA_CA_CERTS` and
`PGSSLROOTCERT` pointing at it. node-postgres then stops failing with
`SELF_SIGNED_CERT_IN_CHAIN`, and libpq tools can use `verify-full`. The command's exit code is
passed through.

**API**
```http
GET /rds/api/ca-bundle
```

It downloads as `dcloud-rds-ca-bundle.pem`. Then:

```text
postgresql://orders_admin:<password>@192.0.2.7:6432/orders?sslmode=verify-full&sslrootcert=/path/to/dcloud-rds-ca-bundle.pem
```

**Terraform:** not available. A connection is not a resource.

The CA bundle is the same file for every database in the installation. The certificate names the
endpoint address and the endpoint's DNS names (`<id>.db.apps.<root-domain>` for the public
endpoint, `<id>.private.db.apps.<root-domain>` for the private one); `verify-full` succeeds against
any of them. Without `sslrootcert`, `verify-full` and `verify-ca` fail.

**From Node.js, connect by name.** node-postgres cannot verify a certificate for an IP host: it
checks it against `localhost` and fails, and it treats `sslmode=require` as `verify-full`. A bound
app is given the name for this reason. A database created before the names existed is given its
address until its certificate is next renewed.

**From an app deployed on Deutsche Cloud**, no download is needed: every container has the CA at
`/etc/ews/ca/platform-ca.pem`, and Node trusts it already (see
[Bind a managed database](/docs/deploy/guide/bind-a-database) in the _Apps User Guide_). Use that path
as `sslrootcert`.

## TLS reference

|                            |                                                                                                                                        |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Where TLS is served        | every port, direct and pooled                                                                                                          |
| Certificate subject        | the database id                                                                                                                        |
| Certificate names          | the endpoint address, as an IP, and the endpoint DNS names                                                                             |
| Issuer                     | `Deutsche Cloud Managed Databases CA` (an older installation's CA keeps the name it was made with), one per installation, valid ten years |
| Certificate validity       | two years from creation                                                                                                                |
| Renewal                    | automatic, from the machine, once the certificate is inside its last 30 days; connections are not interrupted                          |
| Expiry warning             | written to **Activity** from 30 days out, once a day; as an error inside 7 days                                                        |
| CA bundle                  | `GET /rds/api/ca-bundle` → `dcloud-rds-ca-bundle.pem`                                                                                |
| Shown on the database page | the certificate's expiry and serial                                                                                                    |

`sslmode` values, as libpq treats them against this database:

| `sslmode`         | Encrypted | Verifies the server | Needs `sslrootcert` |
| ----------------- | --------- | ------------------- | ------------------- |
| `disable`         | no        | no                  | no                  |
| `allow`, `prefer` | yes       | no                  | no                  |
| `require`         | yes       | no                  | no                  |
| `verify-ca`       | yes       | issuer only         | yes                 |
| `verify-full`     | yes       | issuer and address  | yes                 |

With **Require TLS** on (the default for new databases), a client that does not ask for TLS is
refused: `no pg_hba.conf entry … no encryption` on 5432, `SSL required` on 6432. With it off, it
gets a plaintext connection. See [Require TLS](require-tls.md).

## Result

`SELECT version();` answers. With `verify-full`, the client has checked that the certificate was
issued by the platform's CA for the address or name you connected to.

## Related

- [Require TLS](require-tls.md)
- [Instances, clusters and endpoints](instances-and-clusters.md)
- `rds.ca-bundle.download` · `dcloud rds ca-bundle download`
