Upgrading WarehousePG Enterprise Manager

Upgrade to WEM 1.4 from 1.3, or directly from 1.2. WEM 1.4 replaces Prometheus and Loki with ClickHouse as the metrics and log pipeline, and requires acp-host-agent 1.1.0 or later on every cluster node, see Upgrading the host agent. See the 1.4 release notes for the full list of changes.

Before you upgrade

• Export or archive any historical metrics and logs you need to keep from Prometheus and Loki. Switching to ClickHouse doesn't carry over existing telemetry, so they become unavailable in WEM once you complete the upgrade. See Prometheus's TSDB admin API for taking a snapshot, and Loki's storage documentation for backing up the underlying chunk and index store, Loki itself has no separate export feature.

• If you're upgrading from 1.2, shut down any separately installed Alertmanager configured through the now-removed ALERTMANAGER_URL parameter. Since 1.3, WEM bundles its own instance of Alertmanager, and leaving an existing one running on the same host can block it from starting.

• If you're upgrading from 1.2, note down any custom alert rules from WEM's previous Prometheus rule files, they're lost once those files are removed, and recreate them through the Rules tab after upgrading. See the 1.3 release notes for the full list of changes 1.3 introduced.

• Note down any User alert rules from the Rules tab before upgrading. Upgrading removes Prometheus, where these rules are stored, so they're deleted rather than migrated. Recreate them afterward. System rules and alert history aren't affected. See Creating and managing alert rules.

Installing ClickHouse and the gateway collector

Install ClickHouse and, if your deployment needs one, the gateway collector, before you upgrade WEM. See Installing ClickHouse and Installing the gateway collector for the placement options and when each component is required.

Upgrading WEM

Upgrade WEM from the host where it's installed, either inside your WHPG cluster or on a dedicated host.

1. Configure the EDB repository:

   → WrapCopy

   export EDB_SUBSCRIPTION_TOKEN=<your-token>
   export EDB_REPO=gpsupp
   curl -1sSLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/$EDB_REPO/setup.rpm.sh" | sudo -E bash

2. Upgrade the WEM package:

   → WrapCopy

   sudo dnf upgrade whpg-enterprise-manager

3. The upgrade preserves your existing wem.conf and creates a new wem.conf.rpmnew file matching the 1.4 schema. Make that new file your configuration, keeping the old one for reference:

   → WrapCopy

   cp /etc/wem/wem.conf /etc/wem/wem.conf.old
   cp /etc/wem/wem.conf.rpmnew /etc/wem/wem.conf

   Open the new /etc/wem/wem.conf and replace, as a minimum, the following variables with your values from wem.conf.old:

   • WHPG_HOST, WHPG_PORT, WHPG_DATABASE, WHPG_USER, WHPG_PASSWORD
   • WEM_HOST, WEM_PORT, WEM_DATABASE, WEM_USER, WEM_PASSWORD
   • WEM_COOKIE_SECRET
   • WEM_INSECURE_COOKIES, if you don't serve WEM over HTTPS
   • CLICKHOUSE_URL
   • OTEL_GATEWAY_ENDPOINT, if your deployment needs a dedicated gateway collector.

   See Configuring WEM for the complete list of configuration parameters and what each one does.

   If the app-state database was repointed or restored, WEM also requires WEM_ADMIN_PASSWORD or WEM_ADMIN_PASSWORD_FILE to complete setup non-interactively. See Installing WEM.

4. Restart the WEM service to apply the update:

   → WrapCopy

   sudo systemctl restart wem

5. Verify the installed version:

   → WrapCopy

   rpm -q whpg-enterprise-manager

6. Clear your browser cache or open WEM in a new browser session. After an upgrade, stale session data can cause a CSRF token error on first login.

Upgrading the host agent

From WEM 1.4, the host agent (acp-host-agent) runs on every cluster node in your WarehousePG (WHPG) cluster, and WEM 1.4 requires acp-host-agent 1.1.0 or later, an older host agent can't connect. It depends on edb-otelcol, the OTel Collector, which replaces the Alloy-based WHPG Collector. Segment hosts are always a fresh install, since they never ran the host agent before 1.4 either way. The coordinator (and standby, if you have one) is either an upgrade, if you're coming from 1.3, or a fresh install, if you're coming from 1.2.

1. On the coordinator, download the host agent package and its edb-otelcol dependency from the EDB repository:

   → WrapCopy

   export EDB_SUBSCRIPTION_TOKEN=<your-token>
   export EDB_REPO=gpsupp
   curl -1sSLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/$EDB_REPO/setup.rpm.sh" | sudo -E bash
   sudo dnf download edb-acp-host-agent edb-otelcol

2. From the coordinator, transfer both packages to every host in the cluster:

   • WHPG 7
   • WHPG 6

   → WrapCopy

   gpsync -f all_hosts edb-acp-host-agent-*.rpm edb-otelcol-*.rpm =:/tmp

   → WrapCopy

   gpscp -f all_hosts edb-acp-host-agent-*.rpm edb-otelcol-*.rpm =:/tmp

3. From the coordinator, install both packages on every host. Installing the local .rpm files upgrades the existing installation wherever the host agent is already present (the coordinator and standby coordinator, coming from 1.3) and installs fresh everywhere else:

   → WrapCopy

   gpssh -f all_hosts -u gpadmin -e "sudo dnf install -y /tmp/edb-acp-host-agent-*.rpm /tmp/edb-otelcol-*.rpm"

4. Set WEM_CONNECT_ADDRESS in /etc/edb/acp-host-agent/acp-host-agent.conf to WEM's IPv4 address and listen port plus 1 (default 8081) on every freshly installed host, segment hosts always, and the coordinator and standby coordinator if you're coming from 1.2:

   → WrapCopy

   WEM_HOST=<wem-host-ipv4>
   gpssh -f all_hosts -u gpadmin -e \
     "sudo sed -i 's/^WEM_CONNECT_ADDRESS=.*/WEM_CONNECT_ADDRESS=${WEM_HOST}:8081/' \
       /etc/edb/acp-host-agent/acp-host-agent.conf"

5. Restart the service on every host so it reconnects using the self-registration and mTLS flow:

   → WrapCopy

   gpssh -f all_hosts -u gpadmin -e "sudo systemctl restart acp-host-agent"

6. In WEM, go to Management > Host Agents and approve any agent that appears in a pending state.

7. Verify every host is running 1.1.0 or later:

   → WrapCopy

   gpssh -f all_hosts -u gpadmin -e "rpm -q edb-acp-host-agent"

Migrating the Prometheus metrics endpoint

Migrate your Prometheus configuration if it scrapes the old combined /prom/metrics feed for WHPG, SQL, or system metrics, since Prometheus scraping now splits across two endpoints:

• WEM metrics: Keep scraping WEM's own metrics from /prom/metrics, unaffected by this change.
• WHPG, SQL, and system metrics: Set OTEL_PROMETHEUS_SCRAPE_ENDPOINT=<host:port> in wem.conf, so the OTel Collector exposes these metrics for an external Prometheus instance, then point your Prometheus configuration at that address instead.

See Metrics reference for the full list of available metrics.

After you upgrade

• To list, restore, report on, or delete backups from the Backups panel, upgrade whpg-backup to 1.34 or later on every cluster node. Older versions can still take and schedule backups. See Installing WarehousePG Backup and Restore.

• Stop and disable the old WHPG Collector (the alloy service) on every cluster node, along with any Prometheus or Loki instances you ran solely for WEM:

  → WrapCopy

  gpssh -f all_hosts -u gpadmin -e "sudo systemctl disable --now alloy"

Next steps

Your upgrade is complete. See Getting started with WEM.