# What runs on your machines

What runs on a database's machines, what the platform does inside your database and as whom, and what each machine holds.

## On every node

Each node is a machine of the instance class you chose, with a data volume of its own:

- PostgreSQL of the database's pinned minor, with the extension builds pinned for that minor (see
  [Versions and maintenance](versions-and-maintenance.md)).
- The connection pooler on `6432` (and `6433` on a cluster), in transaction mode.
- On a cluster, Patroni, which elects the leader and fails over; the endpoint is a load balancer in
  front of the three members.
- pgBackRest, which takes the backups and archives write-ahead log straight to object storage.
- A backup agent that polls the platform once a minute for backup requests; that poll is its
  heartbeat. Each node also reports its disk use every five minutes and the exact PostgreSQL
  version it runs, and renews its own TLS certificate. A maintenance agent applies minor upgrades
  and OS patch reboots in the maintenance window. Machines built before in-place upgrades have no
  maintenance agent, and machines built before log shipping keep their server log on the machine.
- The server log is shipped to the platform and kept seven days (see
  [Read the server log](read-the-server-log.md)).

Every step a machine takes is written to the database's **Activity**, by the machine itself or by
the platform; the phases are listed in [Monitoring](monitoring.md).

## The platform's own role

The platform signs in to your database as `ews_platform`, a superuser role of its own, not as your
master user: applying parameters, health checks, extensions, logins, TLS changes and backups run as
it. Its statements are never counted in `pg_stat_statements` (the role carries
`pg_stat_statements.track = none`), the **Queries** tab leaves it out, and your server log names it,
so an audit tells its work from yours. Its password is derived per database and stored nowhere.

Do not drop or change the role: the health check (every two minutes) makes it again, using the
master credential in the meantime. A database made before the role existed gets it at its next
health check, which also removes from the statistics the entries the platform had left there as
your master user (`ALTER SYSTEM …`, the settings read, `pg_switch_wal()`, `pg_reload_conf()`); your
own history stays, and **Activity** says how many were removed.

The data browser and the credentials handed to bound apps stay your master user's. The platform's
own sessions are not shown under **Running now** and cannot be ended there.

## What reaches a private database

A private database answers machines in its network and the platform's control plane, which
connects on the public endpoint for binding an app, switching extensions, the data browser and
password rotation. Nothing else on the internet reaches it. See
[Instances, clusters and endpoints](instances-and-clusters.md).

## What the machine holds for its backups

The backup is uploaded by the database machine rather than by the console, so that machine has to
hold a storage credential: pgBackRest has no scoped token it could be given instead. The credential
it holds is the backup store's, which on a platform that has separated the two is worth nothing but
database backups. It is never the credential for the store holding the container registry,
packages, git repositories, CI logs and the platform's own backups.

That credential is still shared by every database machine, and object-storage providers issue
credentials per project rather than per bucket, so a machine that goes looking can reach the paths
of other databases. What it finds there is unreadable: each database's repository is encrypted by
pgBackRest on the machine that made it, with a passphrase generated for that database alone and
kept only by the control plane. A restore is given the source database's passphrase, so a restore
works from the console and not from a machine that happened to find the objects.

The passphrase is fixed when the repository is created and is never changed: changing it would make
every backup already in that repository unreadable. Databases created before backup encryption
keep unencrypted repositories, and their backups and restores continue to work; every database
created since is encrypted.

## What the machine holds for its disk

Each data volume is encrypted with LUKS2 and its own random key, held by the control plane. A
machine gets the key only at boot, over its own credential, only while the volume is attached to
that machine and the request comes from that machine's address. The key is never written to the
machine's disk or to its user data. A machine can only open its volume while the control plane
answers: a node that reboots during a control plane outage waits, and its database starts as soon
as the control plane is back; a running node is unaffected. See [Security](security.md).

## Query insights sampling

Once a minute, when `pg_stat_statements` is enabled, the platform reads each node's
`pg_stat_statements` counters (numbers only, one query) and stores what changed since the minute
before, for the 50 statements that took the most time: at most 50 statements per node per minute,
kept 7 days in the platform's store. See
[Find slow queries](find-slow-queries.md).

## The branch pool

The first branch of a database builds one extra machine, the branch pool (`<name>-branches`): a
`performance-4` with a LUKS-encrypted, ZFS-formatted volume 1.5× the database's (at least 40 GiB). It holds
a masked restore of the latest backup and serves each branch from its own PostgreSQL server on
ports 6500–6519. The **Branches** tab shows the pool's machine, disk, ZFS space (free, base, and
each branch's own bytes), base age, masking state and the operation the pool is running, and
**Activity** records every step: pool built, base masked (with the rules skipped), branch
requested, branch available with how long it took (request to serving, and on the pool), deleted,
expired. See [Branches](branches.md).

## Related

- [How Managed PostgreSQL behaves when things fail](failure-behaviour.md)
- [Benchmarks](benchmarks.md)
- [Security](security.md)
