Database configuration settings

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 table. Changes to configuration settings in this section require a server restart before taking effect.

Tip

Each configuration value below includes a JSON path to access the value programmatically in the config.json file using a JSON-aware tool. For example, the SiteURL value is under ServiceSettings.

If using a tool such as jq, you’d enter: cat config/config.json | jq '.ServiceSettings.SiteURL'
When working with the config.json file manually, look for the key ServiceSettings, then within that object, find the key SiteURL.

Driver name

Available in legacy Enterprise Edition E10/E20

Identify the type of database. Can be one of:

mysql: (Default) Enables driver to MySQL database.
postgres: Enables driver to PostgreSQL database.

System Config path: N/A
config.json setting: ".SqlSettings.DriverName",
Environment variable: MM_SQLSETTINGS_DRIVERNAME

Data source

Available in legacy Enterprise Edition E10/E20

The connection string to the master database.

String input

System Config path: N/A
config.json setting: ".SqlSettings.DataSource",
Environment variable: MM_SQLSETTINGS_DATASOURCE

To enable SSL:

Add &tls=true to your database connection string if your SQL driver supports it.
Add &tls=skip-verify if you use self-signed certificates.

MySQL databases

When Driver Name is set to mysql, using collation is recommended over using charset.

To specify collation:

"SqlSettings": {
    "DataSource":
"<user:pass>@<servername>/mattermost?charset=utf8mb4,utf8&collation=utf8mb4_general_ci",
    [...]
 }

If collation is omitted, the default collation, utf8mb4_general_ci is used:

"SqlSettings": {
    "DataSource": "<user:pass>@<servername>/mattermost?charset=utf8mb4,utf8",
    [...]
 }

Note: If you’re using MySQL 8.0 or later, the default collation has changed to utf8mb4_0900_ai_ci. See our Database Software Requirements documentation for details on MySQL 8.0 support.

PostgreSQL databases

When Driver Name is set to postgres, use a connection string in the form of: postgres://mmuser:password@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10.

Maximum idle connections

Available in legacy Enterprise Edition E10/E20

Maximum number of idle connections held open to the database.

Numerical input. Default is 10.

System Config path: Environment > Database
config.json setting: ".SqlSettings.MaxIdleConns": 10,
Environment variable: MM_SQLSETTINGS_MAXIDLECONNS

Maximum open connections

Available in legacy Enterprise Edition E10/E20

Maximum number of idle connections held open to the database.

Numerical input. Default is 300.

System Config path: Environment > Database
config.json setting: ".SqlSettings.MaxOpenConns": 300,
Environment variable: MM_SQLSETTINGS_MAXOPENCONNS

Query timeout

Available in legacy Enterprise Edition E10/E20

The amount of time to wait for a response from the database, in seconds, after opening a connection and sending the query.

Numerical input in seconds. Default is 30 seconds.

System Config path: Environment > Database
config.json setting: ".SqlSettings.QueryTimeout: 30",
Environment variable: MM_SQLSETTINGS_QUERYTIMEOUT

Maximum connection lifetime

Available in legacy Enterprise Edition E10/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 3,600,000 milliseconds (1 hour).

System Config path: Environment > Database
config.json setting: ".SqlSettings.ConnMaxLifetimeMilliseconds: 3600000",
Environment variable: MM_SQLSETTINGS_CONNMAXLIFETIMEMILLISECONDS

Maximum connection idle timeout

Available in legacy Enterprise Edition E10/E20

Maximum time a database connection can remain idle, in milliseconds.

Numerical input in milliseconds. Default is 300000 (5 minutes).

System Config path: Environment > Database
config.json setting: ".SqlSettings.ConnMaxIdleTimeMilliseconds: 300000",
Environment variable: MM_SQLSETTINGS_CONNMAXIDLETIMEMILLISECONDS

Minimum hashtag length

Minimum number of characters in a hashtag. This value must be greater than or equal to 2.	System Config path: Environment > Database `config.json` setting: `".SqlSettings.MinimumHashtagLength: 3",` Environment variable: `MM_SQLSETTINGS_MINIMUMHASHTAGLENGTH`
Note: MySQL databases must be configured to support searching strings shorter than three characters. See the MySQL documentation for details.

SQL statement logging

Executed SQL statements can be written to the log for development.

true: Executing SQL statements are written to the log.
false: (Default) SQL statements aren’t written to the log.

System Config path: Environment > Database
config.json setting: ".SqlSettings.Trace: false",
Environment variable: MM_SQLSETTINGS_TRACE

Recycle database connections

Available in legacy Enterprise Edition E20

Select the Recycle Database Connections button to reconnects to the configured database. All old connections are closed after 20 seconds.

To fail over without downing the server, change the database line in the config.json file, select Reload Configuration from Disk via Environment > Web Server, then select Recycle Database Connections.

System Config path: Environment > Database
config.json setting: N/A
Environment variable: N/A

Disable database search

Available in legacy Enterprise Edition E10/E20

When other search engines are configured, such as Elasticsearch, the database can be disabled to perform searches.

true: Disables the use of the database to perform searches. If another search engine isn’t configured, setting this value to true will result in empty search results.
false: (Default) Database search is not disabled.

System Config path: Environment > Database
config.json setting: ".SqlSettings.DisableDatabaseSearch: false",
Environment variable: MM_SQLSETTINGS_DISABLEDATABASESEARCH

Applied schema migrations

Available in legacy Enterprise Edition E10/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.