Migrate Mattermost from MySQL to PostgreSQL

Plugin data is the part of a MySQL to PostgreSQL move that most often gets treated as an afterthought, and the Mattermost migration guide covers it directly: it includes plugin data migrations for Boards, Playbooks and Calls. Before anyone takes the copy that feeds the trial run, record the plugin inventory on the source server: the installed version of each plugin, whether each one is enabled, and where each keeps its data. Boards and Playbooks store their content in the database, so their rows travel with the rest of the schema, but you should still confirm which tables and records belong to them. Calls is different because its operating model depends on components outside the database, so its inventory needs a line for those as well. Capture the list in a document that the trial and production runs both reference.

Once the trial run finishes against the copy, check each plugin separately instead of relying on the server starting cleanly. For Boards, open several existing boards, confirm that cards, properties, comments and sharing settings display as they did on MySQL, and confirm that a new card can be created and edited. For Playbooks, open representative playbooks and runs, confirm that run history, owners, checklists and status updates are present, and confirm that a test run can progress through its steps. Compare the plugin enabled state and version on PostgreSQL with the inventory you recorded before the copy. Any plugin that is disabled, missing or on an unexpected version after the trial needs an explanation before you schedule the production cutover.

Calls depends on external components that the database migration does not move, so the trial run cannot prove that Calls works on the new database by itself. Confirm in your own environment which external services the Calls configuration uses, where those services run, and whether their addresses, credentials and network paths remain valid after the server changes. Test a call with real participants on the trial server, including joining, leaving and any recording or transcription features your organization has enabled. Note that the documentation supports the Calls data migration path, but any external dependency your deployment relies on should be verified by your team rather than assumed to work because the database loaded correctly.

Plan for plugin problems as a cutover risk. Decide in advance who signs off on each plugin, what happens if one fails the trial checks, and whether users can be told that a feature is unavailable for a short period. Keep the MySQL source untouched until every plugin check has passed on the copy and the production steps are confirmed. Also confirm the plugin versions you intend to run after the move are supported with the Mattermost server version you are targeting, because plugin behavior can change between server releases. Writing these decisions into the runbook before the trial starts makes the production window shorter and reduces guesswork if something fails.

Size the migration host and the PostgreSQL target before you schedule a trial run, because the documented approach depends on both. Mattermost recommends running migration-assist on a separate server against a copy of the MySQL database. It suggests 2 CPU cores and 16 GB RAM for the tool, and it says the PostgreSQL server should initially match the size of the MySQL server. Treat those as the documented starting points, then confirm them against your own data. Ask your platform team whether the migration host can be provisioned in the same cloud account or data center as production, and whether it can reach both the MySQL copy and the new PostgreSQL instance without opening paths to production.

Running the process on a separate host and against a copy keeps production load and risk out of the exercise. The migration reads and rewrites large tables, so it can compete with live users for CPU, memory, disk I/O and connections if it runs on the production database or on an application node. A copy lets your team stop, repeat and time the process as often as needed without touching the live Mattermost server. It also means a failed attempt cannot corrupt the source data you will need for the real cutover. Keep the copy's source snapshot time recorded, so every trial run can be compared with the same baseline.

Before you accept the sizing, measure the source database and the plugin data it holds. At minimum, record the total database size on disk, the row counts for the largest tables (posts, channels, users, files and file metadata), and the size of the tables used by the Boards, Playbooks and Calls plugins. Also record the size of any file storage that the migration does not move, because it will still need to be reachable from the new server. Compare these figures with the free space and memory on the migration host and with the storage you plan to allocate to PostgreSQL. If the copy will not fit on the migration host with room for the converted database, plan more disk before the trial run rather than during it.

Use the same measurements to check the PostgreSQL target. Matching the MySQL server's size is the documented starting point, so confirm that the CPU, memory, storage throughput and connection limits you plan to give PostgreSQL are at least equal to the MySQL server's current allocation. Note the PostgreSQL major version you intend to run. Supported versions at the time of writing are 14 through 18, and version 14 reaches end of support on November 12, 2026, so confirm the release date and support end date for the version you select against the PostgreSQL versioning policy before you commit. Record the chosen values in a sizing worksheet that the trial run will be measured against.

Decide in advance what result would make the sizing acceptable. Examples include whether the trial run completes on the migration host with headroom, whether the converted database size is within the storage you allocated, and whether row counts match between source and target for each table you check. If any figure falls outside the range your team agreed, change the sizing and repeat the trial rather than adjusting the acceptance criteria after the fact. Ask any implementation partner to deliver this worksheet as part of the written scope, with the measurements taken from your environment rather than from generic assumptions.

A database move like this one cannot be validated by running the old MySQL server and the new PostgreSQL server side by side as two live, writable systems. Once users post messages on one side, the other side diverges, and reconciling two sets of writes is not a task the documented procedure supports. Confidence therefore comes from repeated trial runs against copies of the database, followed by a rehearsed cutover with a defined point at which the team decides whether to roll back.

Each trial run should use a copy of the MySQL database, with migration-assist running on a separate server as Mattermost recommends, so the production source is never touched. After every run, compare the results with checks the team can repeat: row counts for key tables such as posts, channels and users, checksums or spot checks on a sample of records, and a review of how the plugin data for Boards, Playbooks and Calls arrived. Record what changed between runs so that each pass shows the problem was fixed rather than moved. Confirm the exact sequence of trial steps, including how the PostgreSQL server should be sized at first, with Mattermost's MySQL to PostgreSQL guide.

Before the first trial, the team should define four things in writing. First, acceptance tests: which queries, log-ins, file attachments and plugin views must work, and what counts as a pass. Second, sign-off: a named person or group who accepts the results for the business and another for the technical side, so the decision does not default to whoever is available on cutover night. Third, the backup and rollback plan: a verified backup of the MySQL database taken immediately before cutover, and a clear statement of how the team returns users to the MySQL system if acceptance fails. Fourth, the downtime window the organization can accept, measured from the first user-facing stop to the moment the new system is confirmed.

The rollback decision point belongs in the cutover plan, not in the incident room. Set the time after which the team stops trying to fix forward and returns to MySQL, and state who makes that call. Rehearse that path on a copy so the people involved have already seen the commands and the expected output.

Treat the downtime estimate from a trial as a measurement of your environment, not a promise. Trial timing depends on database size, hardware and network path, and the team should size the window from its own results. Confirm the exact downtime steps with Mattermost's documentation, and make the window part of the written scope so that any quote reflects the same assumptions.