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

• 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)

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