PostgreSQL separate from the platform

era/scripts/install_pg.sh performs database operations without touching the platform. It is needed when the database lives on a separate server, when a replica is brought up, or when master and replica roles are swapped.

bash era/scripts/install_pg.sh
bash install_pg_ssh.sh --host=192.168.0.20 --user=user

Six operations

--operation What it does

install_in_docker

Brings up the server in the postgres<postfix> container and creates the platform role.

install_host_master

Installs the package, creates the cluster on the host, configures postgresql.conf and pg_hba.conf, creates roles, and registers the systemd unit.

install_host_slave

Installs the package and fetches the database from the master via pg_basebackup. The existing cluster is not deleted but moved to the backup directory.

switch_to_master

Promotes the replica to master.

switch_to_slave

Demotes the master to replica: moves the data to backup and re-fills the database from the new master.

uninstall

Stops the server, removes the container or unit and the cluster directory, and then the instance directory if it remained empty.

The operation need not be specified explicitly: it is derived from --pgmode and --pghostmode, as described in the version 3 help. --pgmode=d gives install_in_docker, --pgmode=h --pghostmode=m — install_host_master, --pgmode=h --pghostmode=r — install_host_slave. An explicit --operation always wins over the derived one.

Container or host

In a container On the host

Installation

docker run, data in the instance directory

Distribution or PGDG package

Version update

Change the image

Update the package

Cluster directory

/opt/era<postfix>/postgresql

OS family path — see era_installer/reference-os-matrix.adoc#era-installer-os-matrix

Management

docker

systemctl via the postgresql_<version>_era<postfix>.service unit. The cluster is started by it immediately at installation, so systemctl stop stops the server and systemctl start starts it — without a restart.

Replication

Not provided by the installer

Fully supported

A container is simpler and faster; a host cluster is needed where replication is required or where the database must survive platform reinstallation.

Replication

The master is brought up with --usereplic=y: then a replication user is created and permissive lines are added to pg_hba.conf.

# on the database master server
bash era/scripts/install_pg.sh --non-interactive -y \
     --operation=install_host_master --postfix=_11 \
     --pgport=5441 --usereplic=y \
     --pgreplicauser=era_replica

# on the replica server
bash era/scripts/install_pg.sh --non-interactive -y \
     --operation=install_host_slave --postfix=_11 \
     --pghost=192.168.0.20 --pgport=5441 \
     --pgreplicauser=era_replica

The replica fetches the entire database via pg_basebackup -R: the standby.signal file and the master connection string are created automatically. Without this the cluster would come up as an ordinary master and diverge from the real one.

After installation the installer executes SELECT pg_is_in_recovery() — the master answers f, the replica t. This is visible in the log and confirms that the role was assigned correctly.

Role switching

The operations below are an additional path: the platform can switch to another database itself, according to its configuration. They are used when the cluster role must be assigned manually.

Promote the replica:

bash era/scripts/install_pg.sh --non-interactive -y \
     --operation=switch_to_master --postfix=_11

Demote the former master:

bash era/scripts/install_pg.sh --non-interactive -y \
     --operation=switch_to_slave --postfix=_11 \
     --pghost=<new master address> --pgreplicauser=era_replica
Demotion moves the current cluster directory to --pgbackupfolder and re-fills the database from the new master. Data that reached the old master after divergence will not appear in the new database — it remains only in the backup.

What is shown at the end of the operation

After each operation the "what changed on the server" form is printed — the same as for platform installation, but with database rows:

== What changed on the server ==

  [ ok ] Packages                            postgresql-17, postgresql-client-17
  [ ok ] PostgreSQL                          postgresql_17_era_11.service service, port 5441
  [ ok ] Database roles                      platformpgadmin
  [ ok ] PostgreSQL replication              prepared, user era_replica

The status is taken from system state rather than command return code: the service is active (or the container is started), the cluster responds to a query, the role exists in pg_roles. A failure in any row gives return code 5 even if all commands ran.

The operations have their own rows:

Operation What is in the form

install_in_docker, install_host_master, install_host_slave

Packages, the database itself, roles, replication. For a replica the replication row is confirmed by the cluster itself: pg_is_in_recovery() must return t, otherwise the cluster came up as a separate master and will diverge from the real one.

switch_to_master, switch_to_slave

Only the replication row: that is the whole result of the operation — which side the cluster became. There are no rows about database installation and roles; those actions are not provided in the operation.

uninstall

The form answers the reverse question — "what remains": the container or service with the unit, and the cluster directory.

With --dry-run there is no form: the server was not changed, and there is nothing to report.

Passwords and roles

Key What it is

--pgpostgresuser

The role under which the platform accesses the database. By default platformpgadmin.

--pgerapwd

Its password.

--pgpostgrespwd

Password of the built-in postgres role.

--pgreplicauser, --pgreplicapwd

Replication role and its password.

--pgospwd

Password of the system postgres user. Needed only for operator login.

In the wizard the password question names the account for which it is entered: "DB user platformpgadmin password", "DB user era_replica password". The label follows the actual name — if you set your own via --pgpostgresuser or --pgreplicauser, it will ask about that one. The same name stands next to the password on the confirmation screen: pgerapwd [platformpgadmin]. The passwords are collected there in a row, as one block — so they can be compared before starting installation.

All passwords are hidden in the log and in printed commands. When installing a cluster on the host, the system user password, if not set with a key, is asked interactively — the terminal is handed to the passwd command at that moment.

Removing the database

bash era/scripts/install_pg.sh --non-interactive --operation=uninstall \
     --postfix=_11 --pgmode=h

The systemd unit (or container) and the cluster directory are removed. Packages remain unless --douninstallsyspkgs=y is set.

The cluster directory is removed under the common protection: the path must be absolute and at least eight characters long. An empty value does not remove anything — it produces a warning.

The instance directory (/opt/era<postfix>) is removed afterwards if nothing remains in it after cluster removal. This is the directory created by the operation itself when the database is installed without the platform. It will not touch someone else’s: the directory name must match era<postfix>, the directory must not be a mount point, and the command is rmdir, which will not touch a non-empty directory. Therefore /var/lib/postgresql/<version> with a host database remains in place: it belongs to the package.