Add PostgreSQL upgrade guide

[hanzei]

Summary

We had frequent questions from customer on how to update their Postgres cluster. This document aims to cover that gap. It cover both https://github.com/mattermost/docker and a standalone postgres server. Cluster upgrade are not covered as they are too complex for ours docs. These setups get managed by specialized DBAs.

AI Summary

• Adds a new page upgrading-postgres.rst under the upgrade section covering how admins should upgrade their PostgreSQL server
• Covers bare-metal upgrades via pg_upgrade and pg_dump/pg_restore, and Docker-based upgrades
• Moves the ANALYZE VERBOSE post-upgrade note from preparations.rst into the new page and replaces it with a cross-reference
• Registers the new page in the upgrade section toctree and index

Test plan

• Verify the new page renders correctly under "Upgrade Mattermost" in the sidebar
• Verify the cross-reference in preparations.rst resolves to the new page
• Check that the ANALYZE VERBOSE callout no longer appears on the preparations page
• Run make linkcheck to confirm no broken links

🤖 Generated with Claude Code

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 041050b

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA d470a77

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9d18a097-0185-4427-ab77-10f13c2547a7

📥 Commits

Reviewing files that changed from the base of the PR and between fe82d1a and 2bbb2e8.

📒 Files selected for processing (1)

• source/deployment-guide/server/preparations.rst

✅ Files skipped from review due to trivial changes (1)

• source/deployment-guide/server/preparations.rst

---

📝 Walkthrough

Walkthrough

Adds a new "Upgrading PostgreSQL" administration guide page and links to it from the Upgrade Mattermost guide; updates deployment preparations to replace an important admonition with a note that references the new PostgreSQL upgrade documentation. No code changes.

Changes

Cohort / File(s)	Summary
Upgrade guide entry source/administration-guide/upgrade-mattermost.rst	Inserted new hidden toctree entry and added a visible bullet linking to the new PostgreSQL upgrade page.
PostgreSQL upgrade doc source/administration-guide/upgrade/upgrading-postgres.rst	Added a new page describing pre-upgrade requirements and three upgrade workflows (pg_upgrade in-place, pg_dump/pg_restore logical, Docker-specific), plus post-upgrade steps.
Deployment preparations note source/deployment-guide/server/preparations.rst	Replaced an .. important:: admonition about running ANALYZE VERBOSE after a major Postgres upgrade with a .. note:: pointing to the new PostgreSQL upgrade documentation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

Contributor

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add PostgreSQL upgrade guide' directly and clearly summarizes the main change: adding new documentation for PostgreSQL upgrades.
Description check	✅ Passed	The description comprehensively relates to the changeset, explaining the rationale for the new PostgreSQL upgrade guide, the coverage of different upgrade methods, and the documentation reorganization.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-lexical-churning-giraffe

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

source/administration-guide/upgrade/upgrading-postgres.rst (1)

14-19: Add quick success checks after key operations

For Novice Nate, the procedure is clear but lacks explicit verification points after stop/restore/start actions. Add short “Expected result” checks (service status, DB version, restore completion) to reduce uncertainty.

As per coding guidelines, "Include expected output or success checks after key steps to help readers verify progress."

Also applies to: 34-83, 93-133

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@source/administration-guide/upgrade/upgrading-postgres.rst` around lines 14 -
19, Add explicit "Expected result" verification lines after each key step
(specifically after "Back up your database", "Check supported versions", and
"Stop Mattermost" and similar steps in ranges 34-83 and 93-133) that state what
to check (e.g., backup completed message or file exists, PostgreSQL target
version reported by psql --version or SELECT version(), Mattermost service is
inactive via systemctl status or ps output, and restore completion
confirmation), and place them immediately below the corresponding step text so
Novice Nate can verify success before proceeding.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@source/administration-guide/upgrade/upgrading-postgres.rst`:
- Around line 111-122: Replace the incorrect container restart instruction
"docker start db" with a command that recreates the container from the updated
compose file so the new image tag is applied; update the step that currently
references docker start (text mentioning "Start the new PostgreSQL container"
and the command "docker start db") to instruct using docker compose up -d
--force-recreate db (or equivalent compose up command) so the container is
recreated with the new PostgreSQL image and the updated docker-compose.yml is
applied.

In `@source/deployment-guide/server/preparations.rst`:
- Around line 122-124: The advisory uses a low-severity admonition (".. note::")
for a major PostgreSQL upgrade redirect; change the directive to a
higher-severity admonition by replacing the ".. note::" token with "..
important::" in the same block so the guidance about upgrading a major version
of PostgreSQL is surfaced as high-impact information.

---

Nitpick comments:
In `@source/administration-guide/upgrade/upgrading-postgres.rst`:
- Around line 14-19: Add explicit "Expected result" verification lines after
each key step (specifically after "Back up your database", "Check supported
versions", and "Stop Mattermost" and similar steps in ranges 34-83 and 93-133)
that state what to check (e.g., backup completed message or file exists,
PostgreSQL target version reported by psql --version or SELECT version(),
Mattermost service is inactive via systemctl status or ps output, and restore
completion confirmation), and place them immediately below the corresponding
step text so Novice Nate can verify success before proceeding.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f54fc339-da90-4bae-b80c-efd37ca78e33

📥 Commits

Reviewing files that changed from the base of the PR and between 80e869f and d470a77.

📒 Files selected for processing (3)

• source/administration-guide/upgrade-mattermost.rst
• source/administration-guide/upgrade/upgrading-postgres.rst
• source/deployment-guide/server/preparations.rst

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 3d56d01

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA fe82d1a

[agarciamontoro]

Looks good! Succinct and to the point, thank you!

[esethna]

Thanks @hanzei! @Combs7th do you want to give this a pass first?

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 2bbb2e8

[Combs7th]

LGTM

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 0dfba3c