CheckMySQL¶

Check MySQL, MariaDB, Percona and other MySQL-compatible servers: connectivity, health and custom queries.

CheckMySQL checks MySQL, MariaDB, Percona and other MySQL-compatible database servers on both Windows and Linux. It connects with MariaDB Connector/C (speaking the native protocol, so one module covers the whole MySQL family) and is only built/shipped when the connector is available.

Default connection settings live under /settings/mysql (host, port, socket, user, password, TLS, timeouts) and every command accepts the network overrides per request (host=, port=, user=, password=, tls=true, …). The parameters that name a local resource the service loads or reads on its own account — socket, plugin dir and defaults file — are configured only in /settings/mysql, never per request, so a check caller cannot make the agent load a plugin or read a file it chooses. Credentials can be kept out of nsclient.ini entirely via defaults file pointing at a permission-protected my.cnf-style file.

Enable module¶

To enable this module and and allow using the commands you need to ass CheckMySQL = enabled to the [/modules] section in nsclient.ini:

[/modules]
CheckMySQL = enabled

Queries¶

A quick reference for all available queries (check commands) in the CheckMySQL module.

List of commands:

A list of all available queries (check commands)

Command	Description
check_mysql	Check MySQL/MariaDB server connectivity and health (version, flavor, uptime, connections).
check_mysql_query	Run a custom SQL query and apply thresholds to the returned rows.

check_mysql¶

Check MySQL/MariaDB server connectivity and health (version, flavor, uptime, connections).

About `check_mysql`¶

check_mysql verifies that a MySQL-compatible server is reachable and healthy. It connects (TCP by default, or via the socket setting), reads the server version and a couple of global status values, and reports them. Being able to connect is the health signal: a reachable server is OK unless you add thresholds, and any connection failure is reported as UNKNOWN with the driver’s error message (“Access denied …”, “Can’t connect …”).

The check works identically against MySQL, MariaDB and Percona; the flavor keyword tells them apart when you need to (e.g. warning=flavor != 'mariadb' to catch an unplanned migration).

Common connection options that can be passed per request (shared by all CheckMySQL commands, defaults come from /settings/mysql): host=, port=, user=, password=, database=, tls=true, timeout=, query-timeout=.

The socket, defaults file and plugin dir connection parameters are set only in /settings/mysql, not per request. Each names a local resource the service loads or reads as its own account — a plugin directory the connector loads a DLL/.so from, a named pipe that can point off-box, an option file read for credentials — so accepting them from a check request would let any caller who can run a check load code or exfiltrate credentials as the agent. They are deployment properties; configure them once in nsclient.ini.

Notes:

host=localhost connects over TCP like any other host name; set the socket setting when you want the local socket / named pipe (the check does not inherit the mysql client’s silent localhost-means-socket behaviour).
MySQL 8 accounts default to the caching_sha2_password auth plugin, which the connector loads from its plugin directory; if that fails set the plugin dir setting to point at it.
Give the monitoring user as few privileges as possible; USAGE is enough for check_mysql.

Jump to section:

Sample Commands
Command-line Arguments
Filter keywords

Sample Commands¶

Check that a MySQL/MariaDB server is up (connecting is the health signal):

check_mysql host=127.0.0.1 user=monitor password=secret
OK: mariadb 11.8.8-MariaDB-ubu2404, uptime 771002s, connections 3/151 (1%)

Warn when the server restarted recently (uptime keyword supports time units):

check_mysql host=127.0.0.1 user=monitor password=secret "warning=uptime < 15m"
WARNING: mariadb 11.8.8-MariaDB-ubu2404, uptime 2s, connections 1/151 (0%)|'mariadb_uptime'=2s;900;0

Alert when the connection pool is close to max_connections:

check_mysql host=127.0.0.1 user=monitor password=secret "warning=connections_pct > 60" "critical=connections_pct > 80"
OK: mariadb 11.8.8-MariaDB-ubu2404, uptime 771002s, connections 3/151 (1%)|'mariadb_connections_pct'=1%;60;80

An unreachable or refusing server is clearly reported (UNKNOWN):

check_mysql host=127.0.0.1 port=9999 timeout=2
Failed to connect to MySQL server '127.0.0.1:9999': Can't connect to server on '127.0.0.1' (110)

check_mysql host=127.0.0.1 user=root password=wrong
Failed to connect to MySQL server '127.0.0.1:3306': Access denied for user 'root'@'192.168.127.1' (using password: YES)

Connect through the local socket instead of TCP:

check_mysql socket=/run/mysqld/mysqld.sock user=monitor password=secret
OK: mariadb 11.8.8-MariaDB-ubu2404, uptime 771002s, connections 3/151 (1%)

MySQL 8 with a non-default client-plugin directory (caching_sha2_password):

check_mysql host=db1 user=monitor password=secret plugin-dir=C:\Program Files\MariaDB\MariaDB Connector C 64-bit\lib\plugin
OK: mysql 8.4.11, uptime 1011s, connections 1/151 (0%)

Command-line Arguments¶

Option	Default Value	Description
host	localhost	MySQL/MariaDB server to connect to.
port	3306	TCP port of the server.
socket		Unix socket path (or Windows named pipe) to connect through instead of TCP.
database		Default database (schema) to connect to.
user		User to authenticate with.
password		Password to authenticate with.
defaults-file		my.cnf-style file whose [client] section supplies credentials, so passwords can be kept out of nsclient.ini.
plugin-dir		Directory the connector loads client auth plugins from (needed for MySQL 8’s caching_sha2_password when the connector’s default is wrong).
tls	false	Require TLS on the connection.
timeout	10	Connection timeout in seconds.
query-timeout	30	Query (read/write) timeout in seconds.

host:

MySQL/MariaDB server to connect to.

Default Value: localhost

port:

TCP port of the server.

Default Value: 3306

tls:

Require TLS on the connection.

Default Value: false

timeout:

Connection timeout in seconds.

Default Value: 10

query-timeout:

Query (read/write) timeout in seconds.

Default Value: 30

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning
warn
critical
crit
ok
debug	false
show-all	false
empty-state	unknown
perf-config
escape-html	false
list-separator	,
top-syntax	${status}: ${list}
ok-syntax
empty-syntax	%(status): No server information returned
detail-syntax	${flavor} ${version}, uptime ${uptime}s, connections ${threads_connected}/${max_connections} (${connections_pct}%)
perf-syntax	${flavor}

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords¶

Option	Description
connections_pct	Open connections as a percentage of max_connections
flavor	Server flavor derived from the version: mysql, mariadb or percona
max_connections	Configured connection limit (max_connections)
threads_connected	Currently open connections (Threads_connected)
uptime	Seconds since the server started (supports units, e.g. uptime < 1h)
version	Server version, e.g. 10.11.14-MariaDB-ubu2404 or 8.4.3
version_comment	Server version comment (distribution/build description)

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

check_mysql_query¶

Run a custom SQL query and apply thresholds to the returned rows.

About `check_mysql_query`¶

check_mysql_query runs an arbitrary SQL query and applies thresholds to the returned rows, CheckWMI-style: every column of the result set is registered as a filter keyword, so filter=, warning= and critical= expressions can reference columns by name, and detail-syntax can render them with %(column). The built-in line keyword renders a whole row as column=value pairs.

Notes:

Each row of the result set is matched separately, so a query returning one row per database/queue/job gives per-item results and ${problem_list} works as usual.
Columns are compared numerically when the threshold side is a number (decimal text such as 99.6 is rounded) and as strings otherwise.
Like other generic query checks, performance data is emitted once you choose a perf-syntax (there is no meaningful default alias for arbitrary queries); the thresholded columns then appear as perf values.
Statements that produce no result set (a lone UPDATE, SET, …) are reported as UNKNOWN rather than silently OK — the check is for reading state, not mutating it.
Use a read-only monitoring account: the query runs with whatever privileges the configured user has.

Jump to section:

Sample Commands
Command-line Arguments
Filter keywords

Sample Commands¶

List rows returned by a custom query (each column becomes a keyword):

check_mysql_query host=127.0.0.1 user=monitor password=secret "query=SELECT table_schema AS db, COUNT(*) AS tables_count FROM information_schema.tables GROUP BY table_schema" "detail-syntax=%(db)=%(tables_count)" "top-syntax=${list}"
information_schema=85, mysql=31, performance_schema=81, sys=102

Threshold on a column value (e.g. long-running queries):

check_mysql_query host=127.0.0.1 user=monitor password=secret "query=SELECT COUNT(*) AS slow_queries FROM information_schema.processlist WHERE time > 60 AND command != 'Sleep'" "critical=slow_queries > 0" "top-syntax=${status}: ${list}" "detail-syntax=%(slow_queries) slow queries"
OK: 0 slow queries

Emit the thresholded column as performance data (set a perf-syntax):

check_mysql_query host=127.0.0.1 user=monitor password=secret "query=SELECT COUNT(*) AS tables_count FROM information_schema.tables" "critical=tables_count > 5000" "perf-syntax=tables" "top-syntax=${status}: ${list}" "detail-syntax=%(tables_count) tables"
OK: 299 tables|'tables_counttables'=299;0;5000

A statement that returns no result set is reported instead of a silent OK:

check_mysql_query host=127.0.0.1 user=monitor password=secret "query=SET @x = 1"
Query returned no result set (the statement produced no columns)

A missing query is rejected with a clear message:

check_mysql_query host=127.0.0.1 user=monitor password=secret
No query specified (use query=<SQL>)

Command-line Arguments¶

Option	Default Value	Description
query		The SQL query to execute.
host	localhost	MySQL/MariaDB server to connect to.
port	3306	TCP port of the server.
socket		Unix socket path (or Windows named pipe) to connect through instead of TCP.
database		Default database (schema) to connect to.
user		User to authenticate with.
password		Password to authenticate with.
defaults-file		my.cnf-style file whose [client] section supplies credentials, so passwords can be kept out of nsclient.ini.
plugin-dir		Directory the connector loads client auth plugins from (needed for MySQL 8’s caching_sha2_password when the connector’s default is wrong).
tls	false	Require TLS on the connection.
timeout	10	Connection timeout in seconds.
query-timeout	30	Query (read/write) timeout in seconds.

host:

MySQL/MariaDB server to connect to.

Default Value: localhost

port:

TCP port of the server.

Default Value: 3306

tls:

Require TLS on the connection.

Default Value: false

timeout:

Connection timeout in seconds.

Default Value: 10

query-timeout:

Query (read/write) timeout in seconds.

Default Value: 30

Common options:

These options are shared by all filter based commands and are described on the common options page; the default values below are specific to this command.

Option	Default Value
filter
warning
warn
critical
crit
ok
debug	false
show-all	false
empty-state	ignored
perf-config
escape-html	false
list-separator	,
top-syntax	${list}
ok-syntax
empty-syntax
detail-syntax	%(line)
perf-syntax

This command also accepts the standard help options: help, help-pb, show-default, help-short.

Filter keywords¶

This command also supports the common filter keywords: count, total, ok_count, warn_count, crit_count, problem_count, list, ok_list, warn_list, crit_list, problem_list, detail_list, sep, status.

Configuration¶

Path / Section	Description
/settings/mysql

/settings/mysql ¶

Key	Default Value	Description
database		DATABASE
defaults file		DEFAULTS FILE
hostname	localhost	MYSQL SERVER
password		MYSQL PASSWORD
plugin dir		PLUGIN DIRECTORY
port	3306	MYSQL PORT
query timeout	30	QUERY TIMEOUT
socket		MYSQL SOCKET
timeout	10	CONNECTION TIMEOUT
tls	false	TLS
user		MYSQL USER

# 
[/settings/mysql]
hostname=localhost
port=3306
query timeout=30
timeout=10
tls=false

DATABASE ¶

Default database (schema) to connect to.

Key	Description
Path:	/settings/mysql
Key:	database
Default value:	N/A

Sample:

[/settings/mysql]
# DATABASE
database=

DEFAULTS FILE ¶

my.cnf-style file whose [client] section supplies credentials, so passwords can be kept out of nsclient.ini.

Key	Description
Path:	/settings/mysql
Key:	defaults file
Advanced:	Yes (means it is not commonly used)
Default value:	N/A

Sample:

[/settings/mysql]
# DEFAULTS FILE
defaults file=

MYSQL SERVER ¶

Default MySQL/MariaDB server to connect to.

Key	Description
Path:	/settings/mysql
Key:	hostname
Default value:	`localhost`

Sample:

[/settings/mysql]
# MYSQL SERVER
hostname=localhost

MYSQL PASSWORD ¶

Password used to authenticate.

Key	Description
Path:	/settings/mysql
Key:	password
Default value:	N/A

Sample:

[/settings/mysql]
# MYSQL PASSWORD
password=

PLUGIN DIRECTORY ¶

Directory the connector loads client auth plugins from (needed for MySQL 8’s caching_sha2_password when the connector’s default is wrong).

Key	Description
Path:	/settings/mysql
Key:	plugin dir
Advanced:	Yes (means it is not commonly used)
Default value:	N/A

Sample:

[/settings/mysql]
# PLUGIN DIRECTORY
plugin dir=

MYSQL PORT ¶

Default TCP port of the server.

Key	Description
Path:	/settings/mysql
Key:	port
Default value:	`3306`

Sample:

[/settings/mysql]
# MYSQL PORT
port=3306

QUERY TIMEOUT ¶

Query (read/write) timeout in seconds.

Key	Description
Path:	/settings/mysql
Key:	query timeout
Advanced:	Yes (means it is not commonly used)
Default value:	`30`

Sample:

[/settings/mysql]
# QUERY TIMEOUT
query timeout=30

MYSQL SOCKET ¶

Unix socket path (or Windows named pipe) to connect through instead of TCP.

Key	Description
Path:	/settings/mysql
Key:	socket
Default value:	N/A

Sample:

[/settings/mysql]
# MYSQL SOCKET
socket=

CONNECTION TIMEOUT ¶

Connection timeout in seconds.

Key	Description
Path:	/settings/mysql
Key:	timeout
Advanced:	Yes (means it is not commonly used)
Default value:	`10`

Sample:

[/settings/mysql]
# CONNECTION TIMEOUT
timeout=10

TLS ¶

Require TLS on the connection.

Key	Description
Path:	/settings/mysql
Key:	tls
Advanced:	Yes (means it is not commonly used)
Default value:	`false`

Sample:

[/settings/mysql]
# TLS
tls=false

MYSQL USER ¶

User used to authenticate.

Key	Description
Path:	/settings/mysql
Key:	user
Default value:	N/A

Sample:

[/settings/mysql]
# MYSQL USER
user=

CheckMySQL¶

Enable module¶

Queries¶

check_mysql¶

About check_mysql¶

Sample Commands¶

Command-line Arguments¶

host:

port:

tls:

timeout:

query-timeout:

Filter keywords¶

check_mysql_query¶

About check_mysql_query¶

Sample Commands¶

Command-line Arguments¶

host:

port:

tls:

timeout:

query-timeout:

Filter keywords¶

Configuration¶

/settings/mysql ¶

DATABASE ¶

DEFAULTS FILE ¶

MYSQL SERVER ¶

MYSQL PASSWORD ¶

PLUGIN DIRECTORY ¶

MYSQL PORT ¶

QUERY TIMEOUT ¶

MYSQL SOCKET ¶

CONNECTION TIMEOUT ¶

TLS ¶

MYSQL USER ¶

About `check_mysql`¶

About `check_mysql_query`¶