How to Set cluster_name in PostgreSQL

How to Set cluster_name in PostgreSQL

Table of Contents

1. What is cluster_name in PostgreSQL?

The cluster_name parameter is an optional setting in PostgreSQL - the server runs normally whether it is set or left blank. 
It simply assigns a logical label to a PostgreSQL server instance, commonly referred to as a PostgreSQL cluster.
This parameter has no impact on performance, storage, or database functionality. Its sole purpose is identification — making it easier to distinguish one PostgreSQL instance from another in environments where multiple instances are running on the same server.

It is particularly useful in the following areas:

Process list — visible in ps -ef output
Log files — appears in PostgreSQL log entries
Monitoring tools — helps identify the instance being monitored
Replication environments — distinguishes primary and replica instances
Multi-instance servers — separates multiple PostgreSQL clusters running side by side

In short, cluster_name is a lightweight administrative convenience — helpful for identification and monitoring, but never required for PostgreSQL to operate.

2. Set cluster_name Using ALTER SYSTEM (OR) vi command

[postgres@pgdb02 17.4]$ psql
psql (17.4)
Type "help" for help.

postgres=# SHOW cluster_name;
 cluster_name
--------------
                          <---- empty
(1 row)

postgres=# ALTER SYSTEM SET cluster_name = 'PGDB_SIT';
ALTER SYSTEM
postgres=# SELECT pg_reload_conf();
 pg_reload_conf
----------------
 t
(1 row)

postgres=# SHOW cluster_name;
 cluster_name
--------------
                          <---- empty
(1 row)

postgres=#

# Verified postgresql logs 
2026-06-20 16:55:23.602 +08 [3305] LOG:  parameter "cluster_name" cannot be changed without restarting the server
2026-06-20 16:55:23.602 +08 [3305] LOG:  configuration file "/pgData/pgsql17/data/postgresql.auto.conf" contains errors; unaffected changes were applied

3. Restart PostgreSQL

# Restart 
[root@pgdb02 ~]# systemctl restart postgresql-17
[root@pgdb02 ~]#

[postgres@pgdb02 ~]$ psql
psql (17.4)
Type "help" for help.

postgres=# SHOW CLUSTER_NAME;
 cluster_name
--------------
 PGDB_SIT  <------
(1 row)

postgres=#

4. Verify

[postgres@pgdb02 ~]$ ps -ef | grep postgres
root        3641    3561  0 16:57 pts/1    00:00:00 su - postgres
postgres    3642    3641  0 16:57 pts/1    00:00:00 -bash
postgres    3711       1  0 17:03 ?        00:00:00 /usr/pgsql-17/bin/postgres -D /pgData/pgsql17/data/
postgres    3712    3711  0 17:03 ?        00:00:00 postgres: PGDB_SIT: checkpointer
postgres    3713    3711  0 17:03 ?        00:00:00 postgres: PGDB_SIT: background writer
postgres    3715    3711  0 17:03 ?        00:00:00 postgres: PGDB_SIT: walwriter
postgres    3716    3711  0 17:03 ?        00:00:00 postgres: PGDB_SIT: autovacuum launcher
postgres    3717    3711  0 17:03 ?        00:00:00 postgres: PGDB_SIT: logical replication launcher
postgres    3731    3642  0 17:03 pts/1    00:00:00 psql
postgres    3732    3711  0 17:03 ?        00:00:00 postgres: PGDB_SIT: postgres postgres [local] idle
root        3748    3164  0 17:09 pts/0    00:00:00 su - postgres
postgres    3749    3748  0 17:09 pts/0    00:00:00 -bash
postgres    3778    3749 99 17:09 pts/0    00:00:00 ps -ef
postgres    3779    3749  0 17:09 pts/0    00:00:00 grep --color=auto postgres
[postgres@pgdb02 ~]$

Caution: Your use of any information or materials on this website is entirely at your own risk. It is provided for educational purposes only. It has been tested internally, however, we do not guarantee that it will work for you. Ensure that you run it in your test environment before using.

Thank you,
Rajasekhar Amudala
Email: br8dba@gmail.com
Linkedin: https://www.linkedin.com/in/rajasekhar-amudala/