Skip to content
You're viewing documentation for v2026.11.6-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview
On this page

Reference architectures

Supported topologies and placement rules for VMs and bare metal: single node, Standard HA and Advanced HA, the connection path and the 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).

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.

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.

Connection path

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

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, ports 5000 and 6000 listen on the VIP only. Without a VIP, they listen on each HA node.

Single node

One server, with no failover. To recover, restore from a backup. 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).
  • Servers connect out to the mesh ports of the console (see Server requirements). They need no inbound access from outside.
  • Applications connect to the database servers directly (see Connect).