Safely rename a Debian PostgreSQL cluster with pg_renamecluster

You will rename one PostgreSQL cluster managed by Debian's postgresql-common, verify its new identity and paths, and keep a recovery route if the change does not complete. 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. pg_renamecluster stops a running cluster, changes its managed directories and log names, then starts it again. 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 contains the 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.

Checkpoint: if command -v finds a different program, stop here and read that program's manual. This guide is for the Debian wrapper at /usr/bin/pg_renamecluster.

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

Use the row belonging to the cluster you intend to change. Record its port, status, owner, data directory and log file. If more than one row matches your mental picture, do not guess. A PostgreSQL major version and cluster name together identify the target, so a wrong name can stop the wrong service or simply produce a misleading error.

Keep a database backup and a copy of any local configuration that 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 it is 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 at which to begin verification, not as a substitute for it.

During this step, PostgreSQL is unavailable. Do not interrupt the command while it is renaming directories or waiting for the new cluster to start. If it reports an error, do not immediately run the inverse command. First inspect the state in the next step.

5. Verify the new cluster and its paths

Start with the cluster inventory and confirm that 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. Understand what the command edits

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. It also renames matching files in /var/log/postgresql.

This 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 that 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

Only use that inverse after verification shows that the rename did not already complete. If both names or only part of the expected layout exist, stop and restore from your documented backup or ask the database administrator to reconstruct the state. Never delete a directory to make the names fit.