Configure the database environment in which Mattermost is deployed by going to System Console > Environment > Database, or by editing the config.json
file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.
Driver name#
Also available in legacy Mattermost Enterprise Edition E10 or E20
The type of database. Can be either:
|
|
Data source#
Also available in legacy Mattermost Enterprise Edition E10 or E20
The connection string to the master database. String input. |
|
||||||||||||||||
PostgreSQL databases When Driver Name is set to To use TLS with PostgreSQL databases The parameter to encrypt connection against a PostgreSQL server is Your database admin must configure the functionality according to the supported values described below:
|
|||||||||||||||||
MySQL databases When Driver Name is set to To specify collation: "SqlSettings": {
"DataSource":
"<mmuser:password>@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8&collation=utf8mb4_general_ci",
[...]
}
If collation is omitted, the default collation, "SqlSettings": {
"DataSource": "<mmuser:password>@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8",
[...]
}
Note: If you’re using MySQL 8.0 or later, the default collation has changed to To use TLS with MySQL databases The parameter to encrypt connection against a MySQL server is Your database admin must configure the functionality according to supported values described below:
|
|||||||||||||||||
AWS High Availablity RDS cluster deployments For an AWS High Availability RDS cluster deployment, point this configuration setting to the write/read endpoint at the cluster level to benefit from the AWS failover handling. AWS takes care of promoting different database nodes to be the writer node. Mattermost doesn’t need to manage this. See the high availablility database configuration documentation for details. |
Maximum open connections#
Also available in legacy Mattermost Enterprise Edition E10 or E20
The maximum number of open connections to the database. Numerical input. Default is 300 for self-hosted deployments, and 100 for Cloud deployments. |
|
Query timeout#
Also available in legacy Mattermost Enterprise Edition E10 or E20
The amount of time to wait, in seconds, for a response from the database after opening a connection and sending the query. Numerical input in seconds. Default is 30 seconds. |
|
Maximum connection lifetime#
Also available in legacy Mattermost Enterprise Edition E10 or E20
Maximum lifetime for a connection to the database, in milliseconds. Use this setting to configure the maximum amount of time a connection to the database may be reused Numerical input in milliseconds. Default is 3600000 milliseconds (1 hour). |
|
Maximum connection idle timeout#
Also available in legacy Mattermost Enterprise Edition E10 or E20
Maximum time a database connection can remain idle, in milliseconds. Numerical input in milliseconds. Default is 300000 (5 minutes). |
|
Minimum hashtag length#
Also available in legacy Mattermost Enterprise Edition E10 or E20
Minimum number of characters in a hashtag. This value must be greater than or equal to 2. |
|
Note: MySQL databases must be configured to support searching strings shorter than three characters. See the MySQL documentation for details. |
SQL statement logging#
Also available in legacy Mattermost Enterprise Edition E10 or E20
Executed SQL statements can be written to the log for development.
|
|
Recycle database connections#
Note
Available only on Enterprise plans
Also available in legacy Mattermost Enterprise Edition E20
Select the Recycle Database Connections button to manually recycle the connection pool by closing the current set of open connections to the database within 20 seconds, and then creating a new set of connections. To fail over without stopping the server, change the
database line in the |
|
Disable database search#
Also available in legacy Mattermost Enterprise Edition E10 or E20
When other search engines are configured, such as Elasticsearch, the database can be disabled to perform searches.
|
|
Search behavior in Mattermost depends on which search engines are enabled.
|
Applied schema migrations#
Also available in legacy Mattermost Enterprise Edition E10 or E20
A list of all migrations that have been applied to the data store based on the version information available in the db_migrations
table. Select About Mattermost from the product menu to review the current database schema version applied to your deployment.
Active Search Backend#
Read-only display of the currently active backend used for search. Values can include none
, database
, elasticsearch
, or bleve
.
Read replicas#
Note
Available only on Enterprise and Professional plans
Also available in legacy Mattermost Enterprise Edition E10 or E20
Specifies the connection strings for the read replica databases. |
|
Note: Each database connection string in the array must be in the same form used for the Data source setting. |
|
AWS High Availablity RDS cluster deployments For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the write traffic). Mattermost has its own method of balancing the read-only connections, and can also balance those queries to the data source/write+read connection should those nodes fail. See the high availablility database configuration documentation for details. |
Search replicas#
Note
Available only on Enterprise and Professional plans
Also available in legacy Mattermost Enterprise Edition E10 or E20
Specifies the connection strings for the search replica databases. A search replica is similar to a read replica, but is used only for handling search queries. |
|
Note: Each database connection string in the array must be in the same form used for the Data source setting. |
|
AWS High Availablity RDS cluster deployments For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the write traffic). Mattermost has its own method of balancing the read-only connections, and can also balance those queries to the data source/write+read connection should those nodes fail. See the high availablility database configuration documentation for details. |
Replica lag settings#
Note
Available only on Enterprise plans
Also available in legacy Mattermost Enterprise Edition E20
String array input specifies a connection string and user-defined SQL queries on the database to measure replica lag for a single replica instance. These settings monitor absolute lag based on binlog distance/transaction queue length, and the time taken for the replica to catch up. String array input consists of:
|
|
Notes:
|
Configure the replica lag metric based on your database type. See the following tabs for details on configuring this for each database type.
Add the configuration highlighted below to your
SqlSettings.ReplicaLagSettings
array. You only need to add this once because replication statistics for AWS Aurora nodes are visible across all server instances that are members of the cluster. Be sure to change theDataSource
to point to a single node in the group.For more information on Aurora replication stats, see the AWS Aurora documentaion.
Example:
{ "SqlSettings": { "ReplicaLagSettings": [ { "DataSource": "replica-1", "QueryAbsoluteLag": "select server_id, highest_lsn_rcvd-durable_lsn as bindiff from aurora_global_db_instance_status() where server_id=<>", "QueryTimeLag": "select server_id, visibility_lag_in_msec from aurora_global_db_instance_status() where server_id=<>" } ] } }Add the configuration highlighted below to your
SqlSettings.ReplicaLagSettings
array. You only need to add this once because replication statistics for all nodes are shared across all server instances that are members of the MySQL replication group. Be sure to change theDataSource
to point to a single node in the group.For more information on group replication stats, see the MySQL documentation.
Example:
{ "SqlSettings": { "ReplicaLagSettings": [ { "DataSource": "replica-1", "QueryAbsoluteLag": "select member_id, count_transactions_remote_in_applier_queue FROM performance_schema.replication_group_member_stats where member_id=<>", "QueryTimeLag": "" } ] } }
Add the configuration highlighted below to your
SqlSettings.ReplicaLagSettings
array. This query should run against the primary node in your cluster, to do this change theDataSource
to match the SqlSettings.DataSource setting you have configured.For more information on pg_stat_replication, see the PostgreSQL documentation.
Example:
{ "SqlSettings": { "ReplicaLagSettings": [ { "DataSource": "postgres://mmuser:password@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10.", "QueryAbsoluteLag": "select usename, pg_wal_lsn_diff(pg_current_wal_lsn(),replay_lsn) as metric from pg_stat_replication;", "QueryTimeLag": "" } ] } }
Grant permissions to the database user for
pg_monitor
. This user should be the same user configured above in theDataSource
string.For more information on roles, see the PostgreSQL documentation.
sudo -u postgres psql postgres=# GRANT pg_monitor TO mmuser;
Save the config and restart all Mattermost nodes.
Navigate to your Grafana instance monitoring Mattermost and open the Mattermost Performance Monitoring v2 dashboard.
The
QueryTimeLag
chart is already setup for you utilizing the existingReplica Lag
chart. If usingQueryAbsoluteLag
metric clone theReplica Lag
chart and edit the query to use the below absolute lag metrics and modify the title to beReplica Lag Absolute
.
mattermost_db_replica_lag_abs{instance=~"$server"}
Replica monitor interval (seconds)#
Available on all plans
self-hosted deployments
Specifies how frequently unhealthy replicas will be monitored for liveness check. Mattermost will dynamically choose a replica if it’s alive. Numerical input. Default is 5 seconds. |
|