---
title: Reference architectures
description: "Supported topologies and placement rules for VMs and bare metal: Standard, Standard HA and Advanced HA, the connection path and the network."
sidebar:
  icon: network
---

## System overview

One console host manages the database servers over a private mesh. Clients
connect to the database servers directly. When the console is down, the
clusters keep running and failover still works. A server that restarts during
the outage joins its cluster again only when the console is back (see
[Console outage](/docs/v2026.11.13-beta/operations/console-outage)).

```mermaid
flowchart LR
  subgraph clients [Your applications]
    APP[App / psql]
  end
  subgraph console [Console host]
    C[Console container<br/>UI + API + metrics + mesh]
  end
  subgraph servers [Your database servers]
    S1[(Server 1)]
    S2[(Server 2)]
    S3[(Server 3)]
  end
  ADMIN[Browser] -->|HTTPS| C
  C -.->|mesh: deploy, monitor, logs| S1 & S2 & S3
  APP -->|PostgreSQL| S1
```

## Placement rules

An HA service survives the failure of one server only when no two servers
share a failure domain.

| Role | Placement |
| --- | --- |
| HA database nodes | One per physical host (a hypervisor anti-affinity rule). Not all on one SAN or datastore. |
| etcd (DCS) members | 3 in total, at most one per failure domain (host, rack, datastore). If one failure removes 2 members, failover stops. |
| Backup server | Outside the failure domain of the database servers: a different host at minimum, a different rack, room or site if you can |
| Console | Its own host, not a database server. Any VM with Docker. |

## Standard HA

Three servers. Each runs PostgreSQL and one etcd member. It survives the loss
of one server. etcd shares the disks with PostgreSQL, so a very write-heavy
workload can slow etcd.

```mermaid
flowchart TB
  subgraph h1 [Physical host / hypervisor 1]
    subgraph s1 [Server 1]
      P1[PostgreSQL primary]
      E1[etcd]
    end
  end
  subgraph h2 [Physical host / hypervisor 2]
    subgraph s2 [Server 2]
      P2[PostgreSQL replica]
      E2[etcd]
    end
  end
  subgraph h3 [Physical host / hypervisor 3]
    subgraph s3 [Server 3]
      P3[PostgreSQL replica]
      E3[etcd]
    end
  end
  subgraph hb [Separate failure domain]
    B[(Dedicated backup server)]
  end
  P1 -->|async replication| P2 & P3
  E1 <--> E2 <--> E3
  P1 -.->|pgBackRest| B
```

## Advanced HA

Two PostgreSQL servers and a separate DCS cluster of 3 small etcd servers.
One DCS cluster can serve more than one service. Put the PostgreSQL servers
on different hosts, and the 3 DCS servers on 3 hosts. See
[External DCS](/docs/v2026.11.13-beta/database-services/external-dcs).

```mermaid
flowchart TB
  subgraph svcA [Service A]
    A1[PostgreSQL primary]
    A2[PostgreSQL replica]
  end
  subgraph svcB [Service B]
    B1[PostgreSQL primary]
    B2[PostgreSQL replica]
  end
  subgraph dcs [Shared DCS cluster: 3 servers, one per host]
    D1[etcd] <--> D2[etcd] <--> D3[etcd]
  end
  A1 -->|async replication| A2
  B1 -->|async replication| B2
  svcA -.->|coordination| dcs
  svcB -.->|coordination| dcs
```

## Connection path

Use port `5000`. After a failover, clients reconnect to the new primary on
the same address.

```mermaid
flowchart LR
  APP[Application] -->|:5000 on the VIP, or on any node with no VIP| H[HAProxy]
  H -->|current primary| PB[PgBouncer :6432]
  PB --> P[(PostgreSQL :5432<br/>primary)]
```

| Port | Service | Routes to |
| --- | --- | --- |
| `5000` | HAProxy (HA only) | PgBouncer on the current primary. Recommended. |
| `6000` | HAProxy direct (HA only) | PostgreSQL on the current primary, without PgBouncer |
| `6432` | PgBouncer (each node) | PostgreSQL on that node |
| `5432` | PostgreSQL (each node) | That node. A replica is read-only. |

With a [VIP](/docs/v2026.11.13-beta/database-services/high-availability), ports `5000` and `6000`
listen on the VIP only. Without a VIP, they listen on each HA node.

## Standard

One PostgreSQL server, with no failover. To recover, [restore from a backup](/docs/v2026.11.13-beta/backups/restore).
Use it for development, tests, and workloads that can wait for a restore.
Use a dedicated backup server: it holds the only copy that survives the loss
of the database server.

## Network

- Browsers and enrolling servers connect to the console at `TSE_PUBLIC_URL`
  (ports per [TLS mode](/docs/v2026.11.13-beta/configuration#tls-modes)).
- Servers connect out to the mesh ports of the console (see
  [Server requirements](/docs/v2026.11.13-beta/servers#server-requirements)). They need no inbound
  access from outside.
- Applications connect to the database servers directly (see
  [Connect](/docs/v2026.11.13-beta/database-services/connect)).
