A PostgreSQL Cluster is a managed, horizontally-shardable PostgreSQL deployment built on Citus (distributed PostgreSQL) and Patroni (automated failover), coordinated by a dedicated etcd quorum the platform provisions and manages for you — it never appears in the spec. The cluster is one resource with an array of named shard groups in spec.shardGroups; exactly one of them, marked isCoordinator: true, is the coordinator and holds the cluster's distributed-table metadata.

Key concepts

• Shard groups, not shards — each entry in spec.shardGroups is a full Patroni group (one primary + spec.replicasPerShardGroup replicas), not a single row range; Citus shards individual distributed tables across whichever shard groups exist

• Exactly one shard group is the coordinator, marked explicitly — set isCoordinator: true on exactly one entry, on every create and every modify; it is never inferred from array order. It can never be removed or handed off to a different shard group, but — unlike every other shard group, whose name is its real identity — its own name can be changed freely, since the server resolves that one entry by the flag instead

• Shard groups can't be swapped in one modify — adding a new shard group and removing an old one in the same request is rejected (it's indistinguishable from renaming one you meant to keep); do it as two separate modifies when you genuinely want to replace one

• Scaling is one shard group per modify — the shard-group count may change by at most one in a single request, same discipline as Valkey's own shard scaling

• No root password in the spec — this resource has no user-facing superuser credential. Create a PostgreSqlUser (see below) to get an actual login; the internal bootstrap credential the platform generates for its own automation is never exposed through the API

• Grow the volume, never shrink it — raise spec.volumeSizeGiB on a live cluster and the platform extends the disk and its filesystem in place, online, without a restart or failover. Decreasing it is refused: the block device cannot be made smaller, and nothing in the stack can shrink a filesystem online. A resize still needs free space on the compute node (about twice the growth), so a node that is itself nearly full can refuse it — support can relax that check per cluster

• Point-in-time restore — spec.restoreConfiguration creates a brand-new cluster restored from another cluster's backups as of a specific UTC moment; immutable, create-time only, and the two clusters are otherwise independent. The source cluster's PostgreSqlDatabase and PostgreSqlUser resources are cloned onto the newly-restored target cluster. The target must have the same shard-group count as the source, a volume size greater than or equal to the source's, and the same PostgreSQL major version as the source

• Public access — private by default; set spec.createPublicIpv4 for a public IPv4 per node, and spec.tlsMode to require to force encrypted connections (mandatory once public access is on). Once it is on, every entry in status.primaryEndpoints/status.readEndpoints is paired: that node's public address first, its private one second

Backups and restore

Every cluster is backed up by pgBackRest into its own S3 bucket, which the platform creates and manages together with the cluster — a full backup on a schedule (kept for spec.backupRetentionDays) plus continuous WAL archiving, which is what makes a restore to an arbitrary moment possible.

• The Backups tab lists what is actually in the backup repository — every backup there is, per shard group, read from the backup storage itself rather than from the last recorded status, so backups taken outside the schedule are listed too. Each row shows the backup's label, type, start and finish times (UTC) and its size in the repository; a backup still running is marked as such, and one taken with page-checksum errors is flagged (it is still restorable, but its data is suspect). It also reports backups that already exist, not just the newest one — which is what a point-in-time decision needs

• Restoring always builds a NEW cluster — Restore from backup opens the create form pre-filled from this cluster with spec.restoreConfiguration set to the backup you picked. Nothing is created until that form is submitted, and the cluster you restored from is never modified: Patroni honours a custom bootstrap only while the new cluster's data directory is empty, and the API accepts restoreConfiguration at creation only, rejecting any later change to it

• Restoring to a moment after the newest backup is expected — WAL is archived continuously, so a point in time later than the last full backup is reached by replaying the archive forward; that is usually the moment you actually want. The usable window runs from the oldest retained full backup to now — anything earlier has already been removed by retention. This is the same spec.restoreConfiguration.restoreTime the API takes directly, as a UTC timestamp

A restored cluster starts with an empty backup repository of its own (its first backup is taken by the same scheduled job); the backups it was restored from stay in the source cluster's storage. Each shard group has its own independent backup chain, so a restore recovers all of them to the same moment.

Citus sharding constraints

Citus distributes tables by a chosen distribution column, and that choice shapes what queries stay fast. This is not a drop-in replacement for a single-node database once more than one shard group is in play — plan the schema around it:

• Primary keys must include the distribution column — Citus cannot enforce global uniqueness on any other column

• Foreign keys between distributed tables must reference the same distribution column, or the reference has to go through a reference table (a small table copied to every shard group instead of sharded)

• Joins and transactions that span rows with different distribution-column values cross shard groups — still correct, but noticeably slower than a same-node query, since it involves a real network round trip between shard groups

• Pick the distribution column deliberately — most applications shard on a tenant/customer/organization id, so that a single tenant's data (and its queries) stay within one shard group

None of this applies to a single-shard-group deployment — it behaves like ordinary PostgreSQL with Citus installed but never invoked.

License notice

Citus is licensed under the GNU Affero General Public License v3 (AGPLv3). Kvindo Cloud runs the unmodified upstream extension; its complete corresponding source code is publicly available from the upstream project at github.com/citusdata/citus, satisfying the AGPL's network-use source-availability requirement.

Connecting: ports and pooling

Every node runs the same four listeners in front of its local PostgreSQL. The status endpoint fields below each go through a different one — pick the field for what you're actually trying to do, not just whichever one is closest to hand:

• Port 5432 — raw PostgreSQL, direct to that one node. Bypasses HAProxy and the connection pooler entirely — no write-routing, no read load-balancing, no TLS-terminated pooled connections. This is what shardGroups[].primaryEndpoint/replicaEndpoints return: a specific node, not the cluster

• Port 8432 — HAProxy, write, routed to whichever node is the current leader of that shard group. This is what status.connectionUri, status.coordinatorEndpoint, and every entry in status.primaryEndpoints actually use — connect to any of them and Citus's own metadata routes a write or a distributed query to the correct shard group

• Port 7432 — HAProxy, read, load-balanced across that shard group's replicas (the primary is only used as a fallback). This is what every entry in status.readEndpoints uses

• Port 6432 — Odyssey, a TLS-terminating connection pooler in front of 5432. This is the intended entry point for a public-facing or high-connection-count client, and it's reachable on every node once spec.createPublicIpv4/spec.tlsMode are set — but no status field reports it today. Until that's surfaced, derive it yourself: take the host from any endpoint above and connect to port 6432 on it directly

Examples

A private 2-shard-group cluster (real Citus sharding) with one replica per shard group, on an existing subnet.

Terraform

Python SDK

kc CLI

Related pages

Resource docs

• PostgreSQL User resource docs
• PostgreSQL Database resource docs
• Parameter Set resource docs
• VPC Subnet resource docs

Examples

• CLI PostgreSQL example
• Terraform PostgreSQL example
• Python SDK PostgreSQL example