From 041050b4f87822025cd4b8d3d28a4a9ad2dfbbf9 Mon Sep 17 00:00:00 2001 From: Ben Schumacher Date: Wed, 15 Apr 2026 14:30:26 +0200 Subject: [PATCH 1/5] Add PostgreSQL upgrade guide Add a dedicated page covering how admins should upgrade their PostgreSQL server, including bare-metal (pg_upgrade and pg_dump/pg_restore) and Docker-based approaches. Move the ANALYZE VERBOSE post-upgrade note from preparations.rst into the new page and replace it with a cross-reference. Register the new page in the upgrade section toctree. Co-Authored-By: Claude Sonnet 4.6 --- .../upgrade-mattermost.rst | 2 + .../upgrade/upgrading-postgres.rst | 153 ++++++++++++++++++ .../deployment-guide/server/preparations.rst | 4 +- 3 files changed, 157 insertions(+), 2 deletions(-) create mode 100644 source/administration-guide/upgrade/upgrading-postgres.rst diff --git a/source/administration-guide/upgrade-mattermost.rst b/source/administration-guide/upgrade-mattermost.rst index 93702c26d3e..01d51bc1a9d 100644 --- a/source/administration-guide/upgrade-mattermost.rst +++ b/source/administration-guide/upgrade-mattermost.rst @@ -14,6 +14,7 @@ Upgrade Mattermost Communicate scheduled maintenance best practices Upgrade Mattermost Server Upgrade Mattermost in Kubernetes and High Availability environments + Upgrade PostgreSQL Upgrade Team Edition to Enterprise Edition Administrator onboarding tasks Enterprise roll-out-checklist @@ -28,6 +29,7 @@ Stay up to date with the latest features and improvements. * :doc:`Communicate scheduled maintenance best practices ` - Learn best practices for communicating scheduled server maintenance in advance of a service maintenance window. * :doc:`Upgrade Mattermost Server ` - Learn the basics of upgrading your Mattermost server to the latest version. * :doc:`Upgrade Mattermost in Kubernetes and High Availability environments ` - Learn how to upgrade Mattermost in Kubernetes and High Availability environments. +* :doc:`Upgrade PostgreSQL ` - Learn how to upgrade your PostgreSQL database server. * :doc:`Upgrade Team Edition to Enterprise Edition ` - Learn how to upgrade your Mattermost Team Edition server to Enterprise Edition. * :doc:`Administrator onboarding tasks ` - Learn about the onboarding tasks for administrators after an upgrade. * :doc:`Enterprise roll-out-checklist ` - Learn about the roll-out checklist for enterprise users. diff --git a/source/administration-guide/upgrade/upgrading-postgres.rst b/source/administration-guide/upgrade/upgrading-postgres.rst new file mode 100644 index 00000000000..944868334c9 --- /dev/null +++ b/source/administration-guide/upgrade/upgrading-postgres.rst @@ -0,0 +1,153 @@ +Upgrade PostgreSQL +================== + +.. include:: ../../_static/badges/all-commercial.rst + :start-after: :nosearch: + +Mattermost follows the `PostgreSQL community versioning policy `_, which provides 5 years of support per major version. When a PostgreSQL version reaches end-of-life, Mattermost drops support for it in a subsequent release. See the :doc:`software and hardware requirements ` documentation for the currently supported PostgreSQL versions. + +When upgrading PostgreSQL, refer to the `official PostgreSQL upgrade documentation `_ for comprehensive guidance. This page covers the steps specific to Mattermost deployments. + +Before you begin +---------------- + +1. **Back up your database.** Always take a full database backup before upgrading. See the :doc:`backup and disaster recovery ` documentation. + +2. **Check supported versions.** Confirm the target PostgreSQL version is supported by your Mattermost release. See :doc:`software and hardware requirements `. + +3. **Stop Mattermost.** Shut down the Mattermost server before starting the database upgrade to prevent data writes during the process. + + .. code-block:: sh + + sudo systemctl stop mattermost + +Upgrade a bare-metal PostgreSQL server +--------------------------------------- + +There are two main approaches for upgrading PostgreSQL on a bare-metal or virtual machine: + +- **pg_upgrade** (in-place): Faster; upgrades the data directory without a full dump/restore cycle. Recommended for large databases. +- **pg_dump / pg_restore** (logical): Simpler and safer for cross-machine migrations or when in-place upgrade is not possible. + +Using pg_upgrade +~~~~~~~~~~~~~~~~ + +``pg_upgrade`` allows you to upgrade between major PostgreSQL versions without a full export. Both the old and new PostgreSQL versions must be installed side-by-side. + +1. Install the new PostgreSQL version alongside the existing one using your package manager. + +2. Stop the existing PostgreSQL service: + + .. code-block:: sh + + sudo systemctl stop postgresql + +3. Run ``pg_upgrade`` as the ``postgres`` user, specifying the binary and data directories for both versions. Replace ```` and ```` with the appropriate version numbers (e.g. ``15`` and ``16``): + + .. code-block:: sh + + sudo -u postgres /usr/lib/postgresql//bin/pg_upgrade \ + --old-datadir /var/lib/postgresql//main \ + --new-datadir /var/lib/postgresql//main \ + --old-bindir /usr/lib/postgresql//bin \ + --new-bindir /usr/lib/postgresql//bin + +4. Update your system to start the new PostgreSQL version by default, then start the service: + + .. code-block:: sh + + sudo systemctl start postgresql + +For full ``pg_upgrade`` reference, see the `official pg_upgrade documentation `_. + +Using pg_dump and pg_restore +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This approach exports the entire database, installs the new PostgreSQL version, and restores the data. It is simpler but requires downtime proportional to database size. + +1. Export the Mattermost database (replace ``mattermost`` with your database name and ``mmuser`` with your database user): + + .. code-block:: sh + + pg_dump -U mmuser -Fc mattermost > mattermost_backup.dump + +2. Install the new PostgreSQL version and create the database user and database: + + .. code-block:: sh + + sudo -u postgres psql -c "CREATE USER mmuser WITH PASSWORD 'your_password';" + sudo -u postgres psql -c "CREATE DATABASE mattermost OWNER mmuser;" + +3. Restore the database into the new PostgreSQL instance: + + .. code-block:: sh + + pg_restore -U mmuser -d mattermost mattermost_backup.dump + +4. Update your ``config.json`` ``SqlSettings.DataSource`` if the PostgreSQL host, port, or version-specific connection string changed. + +Upgrade PostgreSQL in Docker +----------------------------- + +When running PostgreSQL in Docker, ``pg_dump``/``pg_restore`` is the recommended upgrade approach. In-place ``pg_upgrade`` is complex in containers because it requires both old and new binaries in the same container. + +.. important:: + + Ensure your Postgres data is stored in a named Docker volume or bind mount before proceeding. Removing or recreating a container without a persistent volume will result in data loss. + +1. Stop the Mattermost container: + + .. code-block:: sh + + docker stop mattermost + +2. Dump the database from the running PostgreSQL container (replace ``mattermost``, ``mmuser``, and ``db`` with your database name, user, and container name): + + .. code-block:: sh + + docker exec db pg_dump -U mmuser -Fc mattermost > mattermost_backup.dump + +3. Stop the existing PostgreSQL container: + + .. code-block:: sh + + docker stop db + +4. Update the PostgreSQL image tag in your ``docker-compose.yml`` (or ``docker run`` command) to the new version. For example: + + .. code-block:: yaml + + image: postgres:16 + +5. Start the new PostgreSQL container. The existing data volume is mounted but PostgreSQL will not be able to read data directory files from a different major version, so the volume should be empty or new: + + .. code-block:: sh + + docker start db + + .. note:: + + If your volume already contains data from the old major version, PostgreSQL will refuse to start. In that case, create a new named volume for the new container, then restore from the dump in the next step. + +6. Recreate the database user and database in the new container, then restore: + + .. code-block:: sh + + docker exec -i db psql -U postgres -c "CREATE USER mmuser WITH PASSWORD 'your_password';" + docker exec -i db psql -U postgres -c "CREATE DATABASE mattermost OWNER mmuser;" + docker exec -i db pg_restore -U mmuser -d mattermost < mattermost_backup.dump + +After the upgrade +------------------ + +After upgrading PostgreSQL, run ``ANALYZE VERBOSE`` on the Mattermost database. This re-populates the ``pg_statistics`` table used by PostgreSQL to generate optimal query plans. Skipping this step can result in degraded database performance. + +.. code-block:: sh + + sudo -u postgres psql -d mattermost -c "ANALYZE VERBOSE;" + +Once complete, restart Mattermost: + +.. code-block:: sh + + sudo systemctl start mattermost diff --git a/source/deployment-guide/server/preparations.rst b/source/deployment-guide/server/preparations.rst index 50b30ba4c3f..cb2c01f323d 100644 --- a/source/deployment-guide/server/preparations.rst +++ b/source/deployment-guide/server/preparations.rst @@ -119,9 +119,9 @@ PostgreSQL v14+ is required for Mattermost server installations. :doc:`MySQL dat sudo systemctl restart postgresql -.. important:: +.. note:: - If you are upgrading a major version of Postgres, ensure that ``ANALYZE VERBOSE`` is run on the database post upgrade. This is required to re-populate the ``pg_statistics`` table used to generate optimal query plans. Database performance may suffer if this step is skipped. + If you are upgrading a major version of PostgreSQL, see :doc:`Upgrade PostgreSQL ` for the full upgrade procedure and post-upgrade steps. Once you've completed the database preparation, return to the :doc:`Linux deployment ` documentation to continue with your Mattermost server installation. From cb9932e53b818624fcf38d554e111a8e53e425fa Mon Sep 17 00:00:00 2001 From: Ben Schumacher Date: Wed, 15 Apr 2026 15:06:36 +0200 Subject: [PATCH 2/5] manual cleanup --- .../upgrade/upgrading-postgres.rst | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/source/administration-guide/upgrade/upgrading-postgres.rst b/source/administration-guide/upgrade/upgrading-postgres.rst index 944868334c9..87a6368c11f 100644 --- a/source/administration-guide/upgrade/upgrading-postgres.rst +++ b/source/administration-guide/upgrade/upgrading-postgres.rst @@ -17,9 +17,6 @@ Before you begin 3. **Stop Mattermost.** Shut down the Mattermost server before starting the database upgrade to prevent data writes during the process. - .. code-block:: sh - - sudo systemctl stop mattermost Upgrade a bare-metal PostgreSQL server --------------------------------------- @@ -84,17 +81,11 @@ This approach exports the entire database, installs the new PostgreSQL version, pg_restore -U mmuser -d mattermost mattermost_backup.dump -4. Update your ``config.json`` ``SqlSettings.DataSource`` if the PostgreSQL host, port, or version-specific connection string changed. - Upgrade PostgreSQL in Docker ----------------------------- When running PostgreSQL in Docker, ``pg_dump``/``pg_restore`` is the recommended upgrade approach. In-place ``pg_upgrade`` is complex in containers because it requires both old and new binaries in the same container. -.. important:: - - Ensure your Postgres data is stored in a named Docker volume or bind mount before proceeding. Removing or recreating a container without a persistent volume will result in data loss. - 1. Stop the Mattermost container: .. code-block:: sh @@ -105,7 +96,7 @@ When running PostgreSQL in Docker, ``pg_dump``/``pg_restore`` is the recommended .. code-block:: sh - docker exec db pg_dump -U mmuser -Fc mattermost > mattermost_backup.dump + docker exec postgres pg_dump -U mmuser -Fc mattermost > mattermost_backup.dump 3. Stop the existing PostgreSQL container: @@ -133,9 +124,9 @@ When running PostgreSQL in Docker, ``pg_dump``/``pg_restore`` is the recommended .. code-block:: sh - docker exec -i db psql -U postgres -c "CREATE USER mmuser WITH PASSWORD 'your_password';" - docker exec -i db psql -U postgres -c "CREATE DATABASE mattermost OWNER mmuser;" - docker exec -i db pg_restore -U mmuser -d mattermost < mattermost_backup.dump + docker exec -i postgres psql -U postgres -c "CREATE USER mmuser WITH PASSWORD 'your_password';" + docker exec -i postgres psql -U postgres -c "CREATE DATABASE mattermost OWNER mmuser;" + docker exec -i postgres pg_restore -U mmuser -d mattermost < mattermost_backup.dump After the upgrade ------------------ From d470a7778564884f582bd1c720fcc14559d1cd8b Mon Sep 17 00:00:00 2001 From: Ben Schumacher Date: Wed, 15 Apr 2026 15:07:01 +0200 Subject: [PATCH 3/5] Scope Docker postgres upgrade guide to mattermost/docker Add a notice that the Docker upgrade steps target the official Mattermost Docker deployment at https://github.com/mattermost/docker. Co-Authored-By: Claude Sonnet 4.6 --- source/administration-guide/upgrade/upgrading-postgres.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/administration-guide/upgrade/upgrading-postgres.rst b/source/administration-guide/upgrade/upgrading-postgres.rst index 87a6368c11f..f6634590003 100644 --- a/source/administration-guide/upgrade/upgrading-postgres.rst +++ b/source/administration-guide/upgrade/upgrading-postgres.rst @@ -84,6 +84,10 @@ This approach exports the entire database, installs the new PostgreSQL version, Upgrade PostgreSQL in Docker ----------------------------- +.. note:: + + The steps below are written for the official `Mattermost Docker deployment `_. If you are using a custom Docker setup, adapt the container and volume names accordingly. + When running PostgreSQL in Docker, ``pg_dump``/``pg_restore`` is the recommended upgrade approach. In-place ``pg_upgrade`` is complex in containers because it requires both old and new binaries in the same container. 1. Stop the Mattermost container: From 3d56d0136b70311dffaf13f36143e60971a09f63 Mon Sep 17 00:00:00 2001 From: Ben Schumacher Date: Wed, 15 Apr 2026 15:08:24 +0200 Subject: [PATCH 4/5] Reference POSTGRES_IMAGE_TAG in Docker upgrade steps Update the Docker upgrade guide to use the .env variable POSTGRES_IMAGE_TAG rather than editing docker-compose.yml directly. Co-Authored-By: Claude Sonnet 4.6 --- .../upgrade/upgrading-postgres.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/administration-guide/upgrade/upgrading-postgres.rst b/source/administration-guide/upgrade/upgrading-postgres.rst index f6634590003..660b8530118 100644 --- a/source/administration-guide/upgrade/upgrading-postgres.rst +++ b/source/administration-guide/upgrade/upgrading-postgres.rst @@ -106,19 +106,19 @@ When running PostgreSQL in Docker, ``pg_dump``/``pg_restore`` is the recommended .. code-block:: sh - docker stop db + docker stop postgres -4. Update the PostgreSQL image tag in your ``docker-compose.yml`` (or ``docker run`` command) to the new version. For example: +4. Update ``POSTGRES_IMAGE_TAG`` in your ``.env`` file to the new version. For example: - .. code-block:: yaml + .. code-block:: text - image: postgres:16 + POSTGRES_IMAGE_TAG=16-alpine 5. Start the new PostgreSQL container. The existing data volume is mounted but PostgreSQL will not be able to read data directory files from a different major version, so the volume should be empty or new: .. code-block:: sh - docker start db + docker start postgres .. note:: From fe82d1a11c8279a77930637693892ca9e38d52ce Mon Sep 17 00:00:00 2001 From: Ben Schumacher Date: Wed, 15 Apr 2026 15:12:10 +0200 Subject: [PATCH 5/5] Fix Docker restart command and upgrade notice severity - Replace "docker start postgres" with "docker compose up -d --force-recreate postgres" so the container is recreated with the updated image tag from .env - Promote the PostgreSQL upgrade cross-reference in preparations.rst from ".. note::" to ".. important::" to reflect its high-impact nature Co-Authored-By: Claude Sonnet 4.6 --- source/administration-guide/upgrade/upgrading-postgres.rst | 4 ++-- source/deployment-guide/server/preparations.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/administration-guide/upgrade/upgrading-postgres.rst b/source/administration-guide/upgrade/upgrading-postgres.rst index 660b8530118..7701ae9f0e6 100644 --- a/source/administration-guide/upgrade/upgrading-postgres.rst +++ b/source/administration-guide/upgrade/upgrading-postgres.rst @@ -114,11 +114,11 @@ When running PostgreSQL in Docker, ``pg_dump``/``pg_restore`` is the recommended POSTGRES_IMAGE_TAG=16-alpine -5. Start the new PostgreSQL container. The existing data volume is mounted but PostgreSQL will not be able to read data directory files from a different major version, so the volume should be empty or new: +5. Recreate the PostgreSQL container so the new image tag from ``.env`` is applied: .. code-block:: sh - docker start postgres + docker compose up -d --force-recreate postgres .. note:: diff --git a/source/deployment-guide/server/preparations.rst b/source/deployment-guide/server/preparations.rst index cb2c01f323d..9739a634f96 100644 --- a/source/deployment-guide/server/preparations.rst +++ b/source/deployment-guide/server/preparations.rst @@ -119,7 +119,7 @@ PostgreSQL v14+ is required for Mattermost server installations. :doc:`MySQL dat sudo systemctl restart postgresql -.. note:: +.. important:: If you are upgrading a major version of PostgreSQL, see :doc:`Upgrade PostgreSQL ` for the full upgrade procedure and post-upgrade steps.