|
| 1 | +Upgrade PostgreSQL |
| 2 | +================== |
| 3 | + |
| 4 | +.. include:: ../../_static/badges/all-commercial.rst |
| 5 | + :start-after: :nosearch: |
| 6 | + |
| 7 | +Mattermost follows the `PostgreSQL community versioning policy <https://www.postgresql.org/support/versioning/>`_, 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 </deployment-guide/software-hardware-requirements>` documentation for the currently supported PostgreSQL versions. |
| 8 | + |
| 9 | +When upgrading PostgreSQL, refer to the `official PostgreSQL upgrade documentation <https://www.postgresql.org/docs/current/upgrading.html>`_ for comprehensive guidance. This page covers the steps specific to Mattermost deployments. |
| 10 | + |
| 11 | +Before you begin |
| 12 | +---------------- |
| 13 | + |
| 14 | +1. **Back up your database.** Always take a full database backup before upgrading. See the :doc:`backup and disaster recovery </deployment-guide/backup-disaster-recovery>` documentation. |
| 15 | + |
| 16 | +2. **Check supported versions.** Confirm the target PostgreSQL version is supported by your Mattermost release. See :doc:`software and hardware requirements </deployment-guide/software-hardware-requirements>`. |
| 17 | + |
| 18 | +3. **Stop Mattermost.** Shut down the Mattermost server before starting the database upgrade to prevent data writes during the process. |
| 19 | + |
| 20 | + |
| 21 | +Upgrade a bare-metal PostgreSQL server |
| 22 | +--------------------------------------- |
| 23 | + |
| 24 | +There are two main approaches for upgrading PostgreSQL on a bare-metal or virtual machine: |
| 25 | + |
| 26 | +- **pg_upgrade** (in-place): Faster; upgrades the data directory without a full dump/restore cycle. Recommended for large databases. |
| 27 | +- **pg_dump / pg_restore** (logical): Simpler and safer for cross-machine migrations or when in-place upgrade is not possible. |
| 28 | + |
| 29 | +Using pg_upgrade |
| 30 | +~~~~~~~~~~~~~~~~ |
| 31 | + |
| 32 | +``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. |
| 33 | + |
| 34 | +1. Install the new PostgreSQL version alongside the existing one using your package manager. |
| 35 | + |
| 36 | +2. Stop the existing PostgreSQL service: |
| 37 | + |
| 38 | + .. code-block:: sh |
| 39 | +
|
| 40 | + sudo systemctl stop postgresql |
| 41 | +
|
| 42 | +3. Run ``pg_upgrade`` as the ``postgres`` user, specifying the binary and data directories for both versions. Replace ``<old_version>`` and ``<new_version>`` with the appropriate version numbers (e.g. ``15`` and ``16``): |
| 43 | + |
| 44 | + .. code-block:: sh |
| 45 | +
|
| 46 | + sudo -u postgres /usr/lib/postgresql/<new_version>/bin/pg_upgrade \ |
| 47 | + --old-datadir /var/lib/postgresql/<old_version>/main \ |
| 48 | + --new-datadir /var/lib/postgresql/<new_version>/main \ |
| 49 | + --old-bindir /usr/lib/postgresql/<old_version>/bin \ |
| 50 | + --new-bindir /usr/lib/postgresql/<new_version>/bin |
| 51 | +
|
| 52 | +4. Update your system to start the new PostgreSQL version by default, then start the service: |
| 53 | + |
| 54 | + .. code-block:: sh |
| 55 | +
|
| 56 | + sudo systemctl start postgresql |
| 57 | +
|
| 58 | +For full ``pg_upgrade`` reference, see the `official pg_upgrade documentation <https://www.postgresql.org/docs/current/pgupgrade.html>`_. |
| 59 | + |
| 60 | +Using pg_dump and pg_restore |
| 61 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 62 | + |
| 63 | +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. |
| 64 | + |
| 65 | +1. Export the Mattermost database (replace ``mattermost`` with your database name and ``mmuser`` with your database user): |
| 66 | + |
| 67 | + .. code-block:: sh |
| 68 | +
|
| 69 | + pg_dump -U mmuser -Fc mattermost > mattermost_backup.dump |
| 70 | +
|
| 71 | +2. Install the new PostgreSQL version and create the database user and database: |
| 72 | + |
| 73 | + .. code-block:: sh |
| 74 | +
|
| 75 | + sudo -u postgres psql -c "CREATE USER mmuser WITH PASSWORD 'your_password';" |
| 76 | + sudo -u postgres psql -c "CREATE DATABASE mattermost OWNER mmuser;" |
| 77 | +
|
| 78 | +3. Restore the database into the new PostgreSQL instance: |
| 79 | + |
| 80 | + .. code-block:: sh |
| 81 | +
|
| 82 | + pg_restore -U mmuser -d mattermost mattermost_backup.dump |
| 83 | +
|
| 84 | +Upgrade PostgreSQL in Docker |
| 85 | +----------------------------- |
| 86 | + |
| 87 | +.. note:: |
| 88 | + |
| 89 | + The steps below are written for the official `Mattermost Docker deployment <https://github.com/mattermost/docker>`_. If you are using a custom Docker setup, adapt the container and volume names accordingly. |
| 90 | + |
| 91 | +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. |
| 92 | + |
| 93 | +1. Stop the Mattermost container: |
| 94 | + |
| 95 | + .. code-block:: sh |
| 96 | +
|
| 97 | + docker stop mattermost |
| 98 | +
|
| 99 | +2. Dump the database from the running PostgreSQL container (replace ``mattermost``, ``mmuser``, and ``db`` with your database name, user, and container name): |
| 100 | + |
| 101 | + .. code-block:: sh |
| 102 | +
|
| 103 | + docker exec postgres pg_dump -U mmuser -Fc mattermost > mattermost_backup.dump |
| 104 | +
|
| 105 | +3. Stop the existing PostgreSQL container: |
| 106 | + |
| 107 | + .. code-block:: sh |
| 108 | +
|
| 109 | + docker stop postgres |
| 110 | +
|
| 111 | +4. Update ``POSTGRES_IMAGE_TAG`` in your ``.env`` file to the new version. For example: |
| 112 | + |
| 113 | + .. code-block:: text |
| 114 | +
|
| 115 | + POSTGRES_IMAGE_TAG=16-alpine |
| 116 | +
|
| 117 | +5. Recreate the PostgreSQL container so the new image tag from ``.env`` is applied: |
| 118 | + |
| 119 | + .. code-block:: sh |
| 120 | +
|
| 121 | + docker compose up -d --force-recreate postgres |
| 122 | +
|
| 123 | + .. note:: |
| 124 | + |
| 125 | + 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. |
| 126 | + |
| 127 | +6. Recreate the database user and database in the new container, then restore: |
| 128 | + |
| 129 | + .. code-block:: sh |
| 130 | +
|
| 131 | + docker exec -i postgres psql -U postgres -c "CREATE USER mmuser WITH PASSWORD 'your_password';" |
| 132 | + docker exec -i postgres psql -U postgres -c "CREATE DATABASE mattermost OWNER mmuser;" |
| 133 | + docker exec -i postgres pg_restore -U mmuser -d mattermost < mattermost_backup.dump |
| 134 | +
|
| 135 | +After the upgrade |
| 136 | +------------------ |
| 137 | + |
| 138 | +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. |
| 139 | + |
| 140 | +.. code-block:: sh |
| 141 | +
|
| 142 | + sudo -u postgres psql -d mattermost -c "ANALYZE VERBOSE;" |
| 143 | +
|
| 144 | +Once complete, restart Mattermost: |
| 145 | + |
| 146 | +.. code-block:: sh |
| 147 | +
|
| 148 | + sudo systemctl start mattermost |
0 commit comments