Offloading Mattermost Search to Elasticsearch or OpenSearch

Search slows down as your Mattermost history grows

By default, Mattermost runs message and file search against the same PostgreSQL or MySQL database that handles posts, channels, and user sessions. For a small team this is simple and works fine. As message volume reaches hundreds of thousands or millions of rows, those SQL pattern matches start competing with normal traffic for CPU and I/O. Search results get slower, and the database can become the bottleneck for everyday chat.

A supported option in many Mattermost releases is to send search indexing and queries to an external Elasticsearch or OpenSearch cluster. Elasticsearch and OpenSearch are distributed search engines that store indexes of content for fast lookup. This offloads full-text search from the transactional database, but it adds a new service to provision, secure, and monitor. Decide whether the trade-off fits your team before changing configuration.

What changes when search moves outside the database

Mattermost sends new messages and files to the search cluster as they are created, and runs a one-time backfill job for existing history. Search queries then hit the search cluster instead of the primary database. The database still stores posts, files, and metadata; the external cluster only holds searchable content and the metadata needed to return results.

Configuration and cutover: a representative example

Exact configuration keys depend on your Mattermost version, so consult the documentation for your release before applying anything. The following is a structural example, not a tested configuration.

On the Mattermost server, edit config.json or set environment variables. A representative JSON block looks like this:

{
  "Elasticsearch": {
    "Enabled": true,
    "ConnectionUrl": "http://elasticsearch-cluster:9200",
    "IndexPrefix": "mattermost-production-",
    "SnippetSize": 200
  }
}

Equivalent environment variables might use names such as MM_ELASTICSEARCH_ENABLED and MM_ELASTICSEARCH_CONNECTIONURL, depending on the release. Make the edit as a user with permission to modify the Mattermost configuration directory, typically the mattermost service account or a root user with sudo.

After saving, restart Mattermost so the new settings load. Example command, run on the Mattermost application server with root or sudo:

sudo systemctl restart mattermost

Expected check: sudo systemctl status mattermost reports active and running. Risk: a brief service interruption, and search is unavailable until the external cluster responds.

Next, trigger the built-in indexing backfill. On a large system this job can run for hours and consume significant CPU and disk I/O, so schedule it during a maintenance window. Once backfill completes, new search traffic should route to the external cluster.

Verify the search cluster independently

From any host that can reach the search endpoint, run a health check. Example:

curl -s http://ELASTICSEARCH_HOST:9200/_cluster/health | python3 -m json.tool

Replace ELASTICSEARCH_HOST with your cluster hostname. Required permission is network read access to the endpoint. Expected output includes a status field set to green or yellow and allocated shards. Risk: do not embed credentials in plain text on shared systems; use authentication if the cluster requires it.

Trade-offs and limitations

• Version compatibility is strict. Pairing Mattermost with an unsupported Elasticsearch or OpenSearch major version can cause silent indexing failures or broken search.
• Initial indexing is expensive. Backfilling millions of messages takes time and I/O. Do not run it during peak chat hours.
• Search is eventually consistent. A message posted a few seconds ago may not appear in external search results immediately.
• Cluster failure affects search. Depending on version and settings, Mattermost may fall back to database search or return partial results when the search cluster is unreachable, which can confuse users.
• Operational burden increases. You must provision, patch, secure, back up, and monitor another cluster.

Confirm the cutover in Mattermost

1. Open the Mattermost System Console and go to the search or Elasticsearch configuration page. Confirm the connection status shows healthy and the index name matches your prefix.
2. Inspect Mattermost server logs for entries from the search indexing job. Look for successful completion messages and no recurring connection errors.
3. Pick a unique phrase from a busy channel, search for it before and after enabling the external index, and compare response times. Do not rely on a single measurement; network and cache effects can skew results.

If you need to roll back, set the external search setting to disabled, restart Mattermost, and search traffic returns to the primary database. The external index can remain in place or be deleted after you confirm database search is acceptable again.

Bottom line

Move Mattermost search to Elasticsearch or OpenSearch when database search latency is affecting users and you have capacity to operate a search cluster. Confirm version compatibility first, run the backfill in a maintenance window, and verify through the System Console, server logs, and cluster health endpoint before telling users the change is complete.