Rename a Debian PostgreSQL Cluster with pg_renamecluster

Debian's pg_renamecluster stops the cluster, moves its directories, then starts it back up, so a wrong name mid-operation ruins your afternoon. Allow about fifteen minutes for a quiet development cluster, or longer for a production change with a maintenance window. The installed command here comes from postgresql-common version 257build1.1.

This is a service-disrupting operation. Take a backup and arrange an outage before using it on data that matters. The examples use 16, main and app; replace them with values from your host.

1. Check the installed command

Read-only checks do not need elevated privileges. Confirm the binary, package version and exact command shape:

$ command -v pg_renamecluster
/usr/bin/pg_renamecluster
$ dpkg-query -W -f='${Package} ${Version}\n' postgresql-common
postgresql-common 257build1.1
$ pg_renamecluster --help
Usage: /usr/bin/pg_renamecluster [OPTIONS] <version> <old cluster name> <new cluster name>

The help text shows a generic [OPTIONS] marker, but the installed manual says there are no options. The command takes exactly three positional arguments: the PostgreSQL major version, the current cluster name and the replacement name. Do not append a flag such as --stop; stopping and starting are built into the operation.

2. Record the current cluster state

Use pg_lsclusters to identify the exact version and name. It is an ordinary, read-only command:

$ pg_lsclusters
Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

• Record the port, status, owner, data directory and log file for the row belonging to the cluster you intend to change.
• Do not guess if more than one row matches. A PostgreSQL major version and cluster name together identify the target, so a wrong name can stop the wrong service or produce a misleading error.
• Keep a database backup and a copy of any local configuration you would need to restore. Renaming is not a backup operation.

It changes filesystem names and configuration values, so a partial failure needs investigation rather than a blind retry.

3. Check the new name before changing anything

The old and new names must differ, the old cluster must exist, and the target name must not already be in use. Cluster names are restricted by the installed script to letters, numbers, underscores, dots and hyphens. Prefer a simple name such as app.

$ pg_lsclusters
$ test ! -e /etc/postgresql/16/app && echo 'target config name is free'
target config name is free

Do not use a hyphen casually. The installed script accepts one, but when run from a terminal it warns that systemd operations can have problems with cluster names containing dashes. Pick an underscore or a short word if the name must work cleanly with service management.

Before the next step, stop applications that connect to the cluster, or arrange for them to be stopped by the maintenance procedure. A running cluster is stopped by the command, and client connections can make that stop fail.

4. Run the rename with elevated privileges

The command writes under /etc/postgresql, may rename data under /var/lib/postgresql, may rename logs under /var/log/postgresql, and may control the PostgreSQL process. Run it with sudo from an administrative shell:

$ sudo pg_renamecluster 16 main app
Stopping cluster 16 main ...
Starting cluster 16 app ...

The stop and start lines appear when the cluster was running before the rename. A cluster that was already stopped is not started merely because it was renamed. The command has no progress mode or dry run, so treat a zero exit status as the point to begin verification, not as a substitute for it.

5. Verify the new cluster and its paths

Start with the cluster inventory and confirm the old row is gone and the new row is present:

$ pg_lsclusters
Ver Cluster Port Status Owner    Data directory             Log file
16  app     5432 online postgres /var/lib/postgresql/16/app /var/log/postgresql/postgresql-16-app.log

The port can differ on your host. The important changes are the version/name row, the managed configuration directory /etc/postgresql/16/app, the data directory when its path contained the old name, and the PostgreSQL log filename. Existing log files matching the old cluster name are renamed as part of the operation.

Check the configuration directory and query the server itself. The second command needs database access as the PostgreSQL operating-system account on a typical Debian installation:

$ sudo test -f /etc/postgresql/16/app/postgresql.conf && echo 'new configuration exists'
new configuration exists
$ sudo -u postgres psql -p 5432 -tAc 'show data_directory; show cluster_name;'
/var/lib/postgresql/16/app
16/app

cluster_name is shown when the setting is supported and configured; do not require that exact output on every PostgreSQL release. The useful checks are that the server answers on the expected port and that data_directory points to the intended location.

6. Know what the command does not touch

The installed manual lists six postgresql.conf settings that can be updated to follow the renamed paths: data_directory, hba_file, ident_file, external_pid_file, stats_temp_directory and cluster_name. The command changes the managed configuration directory and the data directory when the data path includes the old cluster name, and renames matching files in /var/log/postgresql.

It does not rename databases, roles, tables or application connection strings. If an application refers to a service name, socket path, log path or a hard-coded cluster directory, update that application separately. Check monitoring and backup jobs too. The PostgreSQL data is still the same cluster; only Debian's cluster identity and related paths have changed.

7. Recover from an incomplete operation

If the command exits with an error, preserve the error text and inspect before making another change:

$ pg_lsclusters
$ sudo ls -ld /etc/postgresql/16/main /etc/postgresql/16/app 2>/dev/null
$ sudo ls -ld /var/lib/postgresql/16/main /var/lib/postgresql/16/app 2>/dev/null
$ sudo journalctl -u postgresql@16-app --since '15 minutes ago' --no-pager

The exact systemd unit name can vary with the version and host, so an empty journal result is not proof the data is missing. Confirm which configuration and data directories exist, then inspect the PostgreSQL log named by pg_lsclusters. If the old name still exists and the new name does not, the inverse command may be appropriate after fixing the reported cause:

$ sudo pg_renamecluster 16 app main