Skip to content
SHC Docs

Underneath the simple Postgres

Read this right after A simple Postgres. Every command here reads; none changes the cluster.

home01
$ shc status -s db
last polled 2026-11-04 18:24:01 UTC
NODE STATE CPU% MEM% DISK% LOAD
home01 healthy 63.4 21.3 7.8 1.74
all 68 queues green
TENANT STACK ENVIRONMENT STATE SERVICES NODE LABELS
prod db prod healthy 1/1 home01 app=postgres environment=prod stack=db tenant=prod
TENANT STACK ENVIRONMENT REPLICA NODE STATE LABELS
prod db prod postgres-1-r0 home01 ready role=primary
Groups
GROUP MEMBER LOCATION READY ALIAS SERVICES
postgres 1 learn/home ready postgres postgres-1
Aliases
TENANT STACK ENVIRONMENT ALIAS SELECTS REPLICAS REASON
prod db prod postgres role=primary:1 postgres-1-r0 -
prod db prod postgres-ro role=replica - no replica matches role=replica
runs on home01; no other node to move to
1 node, 1 deployment

The catalogue Postgres is a group named postgres. A member of the group is one copy of the database, and each member is its own numbered service: member 1 is postgres-1. The app starts with one member. With more, one member takes writes and the others copy from it, ready to take over; Postgres members across locations adds them.

A replica is a service running on a node. postgres-1-r0 is the one replica of postgres-1. Postgres reports whether it takes writes, and SHC keeps that as the replica’s label: role=primary here, role=replica on a member that copies.

An alias is a name other services connect to. It reaches the replicas whose labels match what it selects. postgres selects role=primary:1, the one replica that takes writes; the Groups section names it on member 1. postgres-ro selects role=replica, for reads. With one member no replica copies, so postgres-ro reaches nothing and reads no replica matches role=replica. That is expected here.

The Groups section also gives each member’s location, learn/home: the cloud and location home01 was initialized with. The runs on line names the node the database runs on; on a cluster of several nodes it also names the nodes it could move to.

Before its server starts, postgres-1 checks that the data directory and the image are the same major version of Postgres, and refuses to start if they are not.

home01
$ shc exec -s db -S postgres-1 -- hostname -I
10.64.66.2 10.64.128.73

The member has two addresses, one on each network it is attached to. One is on the deployment’s own network, which only its own services share. The other is on SHC’s fabric, the network that connects replicas, on one node and across nodes.

home01
$ shc integration sockets -s db
STACK SOCKET TYPE
db postgres postgres

db offers a socket named postgres. An app with a plug of that name can ask it for a database and a user. The socket page does that.

Next: A Postgres socket.