Concepts

The pgEdge Control Plane is designed to simplify the management and orchestration of Postgres databases. It provides a declarative API for defining, deploying, and updating databases across multiple hosts.

This section introduces the core concepts and terminology used throughout the Control Plane documentation to help you understand how databases, nodes, instances, and hosts interact within a cluster.

The above diagram illustrates the relationship between nodes, hosts, instances, and databases in a distributed cluster: a database is composed of one or more nodes, each node is made of one or more instances, and each instance runs on a host.

Hosts

Hosts are the underlying compute resources used to run database instances. One Control Plane server should be deployed to each host that will run databases. For this reason, each Control Plane server is identified by a host ID.

Cluster

A Cluster represents a collection of hosts that are joined together to provide a unified API for managing databases. Connecting the Control Plane server on each host into a cluster enables coordination and orchestration of resources, allowing databases to be deployed, replicated, and managed across hosts.

Databases

A database in the Control Plane API is a Postgres database that is optionally replicated between multiple Postgres instances. A database is composed of one or more nodes.

You create and update databases by submitting a "database spec" to the Control Plane API. See Creating a Database and Updating a Database for more information.

Nodes

The Control Plane uses an extension, called Spock, to replicate data between Postgres instances using logical replication. In the Control Plane API, nodes refer to Spock nodes.

Spock monitors changes made in the database on the primary instance of each node and uses logical replication to distribute those changes to other nodes.

Instances

Each node is composed of one or more Postgres instances, where one instance is a primary and the others are read replicas. Writes can be made to the primary instance of any node in the database.

When a node which has multiple instances is created, the primary instance for the node will be placed on the first host specified for the node in the database spec. After a database is created, the primary instance may change due to a failover or switchover operation.

Orchestrators

The Control Plane is architected to support multiple orchestrators, giving you flexibility in how database instances are deployed and managed.

systemd The Control Plane and Postgres instances run as native Linux services managed by systemd units. This is a good fit for organizations that prefer system package managers over containers. See Installing via System Packages for setup instructions.

Docker Swarm Orchestrator in which each host corresponds to a Docker Swarm node, with the Control Plane running as a Docker container. Each database instance runs as a separate Docker container within the Swarm environment. See Installing the Control Plane with Swarm for setup instructions.

Both orchestrators share the same core API and capabilities: declarative database management, Patroni-based high availability, and pgBackRest backup/restore integration.