cluster_name

Definition PG 18 manual

Sets a name that identifies this database cluster (instance) for various purposes. The cluster name appears in the process title for all server processes in this cluster. Moreover, it is the default application name for a standby connection (see synchronous_standby_names).

The name can be any string of less than NAMEDATALEN characters (64 characters in a standard build). Only printable ASCII characters may be used in the cluster_name value. Other characters are replaced with C-style hexadecimal escapes. No name is shown if this parameter is set to the empty string '' (which is the default). This parameter can only be set at server start.

How it works

cluster_name sets the name of the cluster, which is included in the process title. It is an operator-facing label included in process titles and can distinguish several clusters running on one host; it is not a database identifier.

cluster_name is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Process titles complement application_name, cluster_name, pg_stat_activity, and log_line_prefix, allowing operating-system observations to be joined with database activity.

Operational considerations

Expecting a reload or SET to activate cluster_name, although it requires a controlled server restart.

Putting secrets or unbounded high-cardinality data into operator-visible process labels.

Using inconsistent cluster, application, and process labels that cannot be joined across monitoring systems.

Changing cluster_name globally without a rollback plan and a client or operational compatibility test.

Workload guidance

OLAP: Preserve cluster_name so long jobs can be attributed from operating-system and PostgreSQL views; use application_name for finer job identity.

OLTP: Keep cluster_name enabled or populated for operator clarity unless profiling proves material overhead. Use stable, non-secret labels that match monitoring inventory.

SMALL: Do not tune cluster_name for capacity. Its observability value normally outweighs negligible overhead, but avoid high-cardinality or sensitive labels.