# Instances, clusters and endpoints

A database is a single node or a three-node cluster, reached at one endpoint on direct and pooled ports, from its network or from the internet.

## Single node and cluster

A **single node** is one machine. Its endpoint address is reserved before the machine exists and
stays with the database if the machine is replaced.

A **cluster** is three machines with a load balancer in front. Reads and writes go to the leader;
the two others are hot standbys that serve reads on the read ports. A failover moves the leader
without changing the address. A cluster needs an instance class with at least 8 GiB of memory.
You can add up to five **readers** to a cluster for read capacity: see
[Add or remove a reader](add-or-remove-a-reader.md).

The topology is chosen when you create the database. The instance classes on offer, with their
stock, come from `rds.server-types.list`.

## Endpoints and ports

The **endpoint** is the IP address you connect to. Where the installation has its own domain, its
TLS certificate also names DNS names for it: `<id>.db.apps.<root-domain>` for the public endpoint
and, when the database has an address in its network, `<id>.private.db.apps.<root-domain>` for
that one.

| Port   | What                       | Private database                                              | Public database |
| ------ | -------------------------- | ------------------------------------------------------------- | --------------- |
| `5432` | PostgreSQL, direct         | your network, the platform's private range, the control plane | anywhere        |
| `5433` | direct, replicas (cluster) | same                                                          | anywhere        |
| `6432` | pooled, read/write         | same                                                          | anywhere        |
| `6433` | pooled, replicas (cluster) | same                                                          | anywhere        |

The pooler on `6432` and `6433` runs in transaction mode; use it from applications. A cluster's
read ports (`6433` pooled, `5433` direct) are served by its replicas and readers together.

## Public and private databases

`publiclyAccessible` at creation decides which addresses may reach the ports. Private is the
default. In the console it is **Reachable from the internet**.

A private database is reachable from:

- machines in its network, over the private network. A database created without `vpcId` joins
  your organization's default network, the one deployed apps run in, which is created if you have
  none yet.
- the platform's own control plane, whose addresses the firewall admits on the client ports.
  Binding an app, switching extensions, the data browser and password rotation connect from there.

Nothing else on the internet reaches it. A private database has a **private endpoint**, an address
in its network that is named in its TLS certificate, and that is the address to connect to:

- A private single node keeps a public address too, but its firewall admits only the control plane
  there.
- A private cluster's load balancer has no public interface at all. It sits in your network at the
  private address, and the public DNS name resolves to that address.

An app bound to a private database from the same network connects to its private endpoint (see
[Bind a managed database](/docs/deploy/guide/bind-a-database) in the _Apps User Guide_).

## Where a cluster's endpoint runs

On installations that have switched to it, a new cluster's endpoint is a `dedicated` load balancer
on Deutsche Cloud's own proxy fleet instead of a provider load balancer (see
[Load balancer types](/docs/lb/guide/load-balancer-types)). A public cluster gets an
IPv4 of its own; a private one gets an address in its VPC on your organization's own pair of proxy
machines, with no public address. It answers on the same four ports, routes on Patroni's own
answer every second (two misses take a node out), and closes the connections of a primary that
Patroni has demoted, so clients reconnect to the new primary instead of writing into a read-only
replica. You see it in **Load balancing** as a load balancer owned by the database (health, live
numbers, logs); it changes with the database and is deleted with it. A cluster keeps the kind of
endpoint it was created with.

## Zones

Region `de1` has two zones: `de1a` (Falkenstein) and `de1b` (Nuremberg).

- A **cluster** is spread over both by default (`zonePlacement: "spread"`, **Spread over zones**
  in the console): members 1 and 3 in `de1a`, member 2 in `de1b`, readers alternating from `de1b`.
  The data then has a copy outside Falkenstein, and the cluster keeps serving if `de1b` is lost, or
  any one machine. (A `sync` commit waits for one of the two standbys, which may be the one in
  `de1a`, so the newest commits are not guaranteed to have reached `de1b`.) Losing `de1a` takes two of the three members, so the cluster cannot
  elect a leader until `de1a` is back; the data in `de1b` is intact. Choose `"single"` to keep all
  members in one zone (`availabilityZoneId`, default `de1a`).
- A **single node** is in `availabilityZoneId` (default `de1a`).

Placement is fixed when the database is created, because each node's disk lives in one zone.
`rds.instances.get` returns `placement`: the zones, which zone's loss the cluster survives
(`survivesLossOf`), the leader's zone and each node's zone. **Nodes** shows the same.

The load balancer and the preferred leader are in `de1a`. Patroni promotes a `de1a` standby when
one is healthy, and planned operations (reboot, resize, upgrades, logical replication) hand over to
a `de1a` member. When the leader does end up in `de1b`, every commit and every query through the
endpoint crosses zones (about 1.5 ms more per round trip). **Nodes** says so; switch over when
convenient. A cluster created before zones existed has every member in `de1a` and stays there.

`fi1` (Helsinki, an opt-in region outside Germany) has one zone, so a cluster there survives
losing a machine, not the site.

## Statuses

| Status                                         | Meaning                                                                    |
| ---------------------------------------------- | -------------------------------------------------------------------------- |
| `creating`                                     | machines are being built; the endpoint does not answer yet                 |
| `waiting-for-capacity`                         | the machine type is sold out; nothing is built or billed while it waits    |
| `available`                                    | accepting connections on every port                                        |
| `modifying`                                    | a change (storage, settings, machine type) is being applied                |
| `backing-up`                                   | a backup was requested                                                     |
| `stopping`, `stopped`, `starting`, `rebooting` | power state changes requested through the API                              |
| `maintenance`                                  | a platform operation (such as an upgrade) is running on the machines       |
| `failed`                                       | provisioning did not complete; its cause is the last line of **Activity**  |
| `deleting`                                     | teardown in progress                                                       |
| `retained`                                     | deleted with a final backup; the backups are kept and can be restored from |

`engineVersion` on a database is the pinned minor its nodes install. Each node also reports the
exact version it runs within a few minutes; that is on the **Nodes** page.

## Related

- [Create a database](create-a-database.md)
- [Connect to a database](connect.md)
- [How Managed PostgreSQL behaves when things fail](failure-behaviour.md)
