The PostgreSQL Cluster

In PostgreSQL, the word "cluster" does not mean a group of networked machines the way it does almost everywhere else in database vocabulary.

It means the single running server instance, and everything that instance owns: its data directory, its shared memory, its roles, and every database created inside it.

Summary

• Core Idea: A PostgreSQL cluster is the one server instance created by initdb, holding all the databases, roles, and shared memory that instance manages together.
• Why It Matters: Config, restarts, upgrades, and connection limits apply at the cluster level, not the database level, so understanding cluster scope prevents wrong assumptions about isolation.
• Key Concepts: cluster, PGDATA, postmaster, template database, tablespace, role.
• When to Use: Deciding whether a new app gets its own database inside an existing cluster or a cluster of its own, reasoning about max_connections as a shared budget, or planning multi-tenant isolation.
• Limitations / Trade-offs: Sharing a cluster means sharing failure blast radius, version upgrades, and connection capacity across every database inside it.
• Related Topics: roles and privileges, connection pooling, multi-tenant patterns, backup and restore scope.

Foundations

Every PostgreSQL server starts life with a single command: initdb.

That command creates a directory on disk, conventionally called PGDATA, and everything the server instance will ever manage lives inside it.

This PGDATA directory, plus the running postmaster process that serves it, is what the word "cluster" refers to in PostgreSQL.

A useful analogy is an office building: the cluster is the building itself, databases are the floors, schemas are the rooms on each floor, and tables are the filing cabinets inside each room.

One building has one lobby, one set of elevators, and one security desk, no matter how many floors it has.

In the same way, one cluster has one postmaster process, one shared memory region, and one set of roles, no matter how many databases live inside it.

CREATE DATABASE does not start a new server process or allocate a separate chunk of shared memory.

It copies a template database (template1 by default) into a new database entry inside the same running instance.

That single, shared instance is also why the term is confusing at first: it has nothing to do with high-availability clustering, replica sets, or Patroni-managed failover groups, which are a completely different, higher-level concept built on top of individual clusters.

Mechanics & Interactions

A single postgresql.conf file governs the entire cluster, so settings like shared_buffers and max_connections are cluster-wide budgets, not per-database allowances.

ALTER DATABASE ... SET and ALTER ROLE ... SET let you override specific settings for one database or role, but they layer on top of the cluster-wide defaults rather than replacing the shared instance underneath them.

Roles are the sharpest example of this shared scope, because a role created in one database is visible and usable from every database in the cluster, even though its object-level privileges are typically granted per database.

A backend process connects to exactly one database at a time, and there is no built-in cross-database JOIN; reaching into another database in the same cluster requires dblink or a foreign data wrapper, treating it almost like a remote server.

-- Cluster-wide facts vs per-database facts
SHOW data_directory;                 -- one path, whole cluster
SELECT datname FROM pg_database;     -- every database this cluster owns
SELECT rolname FROM pg_roles;        -- roles are visible cluster-wide

Tablespaces let you place individual databases, tables, or indexes on different physical disks while staying inside the same logical cluster, which is a storage-layout decision rather than an isolation decision.

WAL (write-ahead log) is generated as a single, cluster-wide stream, which is exactly why replication and point-in-time recovery are configured once per cluster rather than once per database.

Because the WAL stream and the shared buffer pool are both cluster-wide, a spike of write activity in one database directly competes for the same I/O and memory budget as every other database on that instance.

Advanced Considerations & Applications

Major-version upgrades operate on the whole cluster at once, since pg_upgrade migrates every database in PGDATA together and there is no way to run PostgreSQL 17 for one database and PostgreSQL 18 for another inside the same instance.

That single-version constraint is a real planning input for multi-tenant systems, because it means every tenant sharing a cluster is forced onto the same upgrade schedule whether or not they are ready for it.

max_connections is the sharpest shared-resource constraint in practice, since it is set once for the whole cluster and every database, every role, and every application competes for the same pool of backend slots, which is exactly why connection pooling matters even on a lightly loaded cluster.

Backup granularity follows the same split as everything else: pg_basebackup captures the entire cluster as a physical unit, while pg_dump can target a single database for a logical, more selective backup.

Security boundaries need the same correction, because a role's login credentials work across every database in the cluster even though GRANT statements scope its actual privileges per object, so "different database" is not the same guarantee as "different login."

Common Misconceptions

• "A cluster means multiple servers working together." The term predates and has nothing to do with high-availability clustering; it is simply the name for one initdb-created instance, however confusing that overlap with modern HA vocabulary feels.
• "Roles belong to a single database." Roles are created and visible cluster-wide; only the privileges granted to a role are scoped per database or per object.
• "Different databases in a cluster can run different PostgreSQL versions." One binary and one running postmaster serve every database in PGDATA, so the whole cluster upgrades together via pg_upgrade.
• "Restarting the server only affects the database I'm working in." A restart stops and starts the entire postmaster process, which takes down every database in the cluster at once.
• "More databases always means more isolation, so it's always the safer choice." Extra databases still share max_connections, shared buffers, and WAL throughput, so isolation gains come with real, shared-resource trade-offs.

FAQs

Related

• Installation Basics - installing the binaries that create your first cluster
• initdb & Data Directory - what initdb actually creates on disk
• postgresql.conf Essentials - the cluster-wide config file this page assumes
• Roles Basics - why roles are cluster-wide, not per-database
• Database, Schema & Search Path - the object hierarchy inside one database

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance line 17).