PGSQL Architecture

The PGSQL module organizes PostgreSQL in production as clusters—logical entities composed of a group of database instances associated by primary-replica relationships.

Each cluster is an autonomous business unit consisting of at least one primary instance, exposing capabilities through services.

There are four core entities in Pigsty’s PGSQL module:

• Cluster: An autonomous PostgreSQL business unit serving as the top-level namespace for other entities.
• Service: A named abstraction that exposes capabilities, routes traffic, and exposes services using node ports.
• Instance: A single PostgreSQL server consisting of running processes and database files on a single node.
• Node: A hardware resource abstraction running Linux + Systemd environment—can be bare metal, VM, container, or Pod.

Along with two business entities—“Database” and “Role”—these form the complete logical view as shown below:

Naming Conventions (following Pigsty’s early constraints)

• Cluster names should be valid DNS domain names without any dots, regex: [a-zA-Z0-9-]+
• Service names should be prefixed with the cluster name and suffixed with specific words: primary, replica, offline, delayed, connected by -.
• Instance names are prefixed with the cluster name and suffixed with a positive integer instance number, connected by -, e.g., ${cluster}-${seq}.
• Nodes are identified by their primary internal IP address; since databases and hosts are deployed 1:1 in the PGSQL module, hostnames typically match instance names.