MariaDB

HealOps uses MariaDB diagnostics to investigate database-related alerts — checking server health, finding slow queries, monitoring replication, and analyzing active threads and InnoDB engine state.

Prerequisites

MariaDB 10.5+ (10.11 LTS or 11.x recommended)
Network access from the HealOps environment to your MariaDB instance
A database user with at least SELECT + PROCESS privileges (and SELECT on performance_schema for slow-query insights)

Setup

Option 1: Interactive CLI

healops integrations setup mariadb

You will be prompted for host, port, database, username, password, and whether to enable SSL.

Option 2: Environment variables

Add to your .env:

MARIADB_HOST=db.example.com
MARIADB_PORT=3306
MARIADB_DATABASE=production
MARIADB_USERNAME=healops_ro
MARIADB_PASSWORD=...
MARIADB_SSL=true

Variable	Default	Description
`MARIADB_HOST`	—	Required. MariaDB server hostname or IP
`MARIADB_PORT`	`3306`	MariaDB server port
`MARIADB_DATABASE`	—	Required. Target database for slow-query analysis
`MARIADB_USERNAME`	—	Required. Database user
`MARIADB_PASSWORD`	(empty)	Database password; required unless the user is configured for passwordless authentication
`MARIADB_SSL`	`true`	Use TLS with certificate verification

Option 3: Persistent store

Credentials are automatically persisted to ~/.config/healops/integrations.json with 0o600 permissions:

{
  "version": 1,
  "integrations": [
    {
      "id": "mariadb-prod",
      "service": "mariadb",
      "status": "active",
      "credentials": {
        "host": "db.example.com",
        "port": 3306,
        "database": "production",
        "username": "healops_ro",
        "password": "...",
        "ssl": true
      }
    }
  ]
}

Recommended user setup

Create a dedicated read-only user for HealOps so it cannot modify data:

CREATE USER 'healops_ro'@'%' IDENTIFIED BY 'strong-password';
GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO 'healops_ro'@'%';
GRANT SELECT ON performance_schema.* TO 'healops_ro'@'%';
FLUSH PRIVILEGES;

The PROCESS privilege lets HealOps read information_schema.PROCESSLIST. REPLICATION CLIENT enables SHOW ALL SLAVES STATUS / SHOW SLAVE STATUS. SELECT on performance_schema is only needed if you want slow-query insights.

TLS configuration

SSL is enabled by default and uses the system CA bundle to verify the server certificate. Set MARIADB_SSL=false only in trusted local networks (development).

Investigation tools

When HealOps investigates a MariaDB-related alert, five diagnostic tools are available:

Process list

Retrieves active threads from information_schema.PROCESSLIST, excluding sleeping connections. Results are sorted by duration so long-running queries appear first.

Global status

Returns a curated set of key metrics from SHOW GLOBAL STATUS — thread counts, connection totals, slow query count, InnoDB buffer pool statistics, row lock waits, and uptime.

InnoDB status

Runs SHOW ENGINE INNODB STATUS and returns the engine status text, truncated to 4000 characters with a truncation marker appended when shortening occurs. Useful for investigating deadlocks, buffer pool pressure, and I/O patterns.

Slow queries

Reads performance_schema.events_statements_summary_by_digest to list statements by average execution time. Requires performance_schema to be enabled.

If performance_schema is disabled, the tool returns an informative note instead of failing. Enable it in my.cnf with performance_schema=ON.

Replication status

Runs SHOW ALL REPLICAS STATUS (MariaDB multi-source replication; alias: SHOW ALL SLAVES STATUS on older builds) with a fallback to SHOW REPLICA STATUS. Returns all configured replication channels, each with I/O thread state, SQL thread state, seconds behind primary, last error, and log positions.

Verify

healops integrations verify mariadb

Expected output:

SERVICE   SOURCE       STATUS    DETAIL
mariadb   local env    passed    Connected to MariaDB 11.8.6-MariaDB; target database: production.

Troubleshooting

Symptom	Fix
Connection refused	Verify host/port, check firewall rules, and confirm MariaDB is listening on the network interface (`bind-address` in `my.cnf`).
Access denied for user	Confirm the username/password and that the user is granted access from the HealOps host (`'healops_ro'@'%'` or a specific IP).
SSL: CERTIFICATE_VERIFY_FAILED	The server certificate is not trusted by the system CA bundle. Install the correct CA or set `MARIADB_SSL=false` in trusted networks.
performance_schema is disabled	Slow-query tool returns an empty list with a note. Enable in `my.cnf`: `performance_schema=ON`.
SELECT command denied on performance_schema	Grant `SELECT` on `performance_schema.*` to the user.
This server is not configured as a replica	Expected on standalone instances — replication tool returns an empty channel list, other tools still work.

Security best practices

Use a dedicated read-only user — never root or an admin account.
Always enable TLS in production (MARIADB_SSL=true, which is the default).
Keep passwords out of source control — use .env or the persistent store.
Rotate credentials periodically and scope them to specific hosts where possible.

Overview

LLM providers

Observability and incidents

Cloud, code, and collaboration

Messaging

Data and workflow systems

Prerequisites

Setup

Option 1: Interactive CLI

Option 2: Environment variables

Option 3: Persistent store

Recommended user setup

TLS configuration

Investigation tools

Process list

Global status

InnoDB status

Slow queries

Replication status

Verify

Troubleshooting

Security best practices

​Prerequisites

​Setup

​Option 1: Interactive CLI

​Option 2: Environment variables

​Option 3: Persistent store

​Recommended user setup

​TLS configuration

​Investigation tools

​Process list

​Global status

​InnoDB status

​Slow queries

​Replication status

​Verify

​Troubleshooting

​Security best practices

Prerequisites

Setup

Option 1: Interactive CLI

Option 2: Environment variables

Option 3: Persistent store

Recommended user setup

TLS configuration

Investigation tools

Process list

Global status

InnoDB status

Slow queries

Replication status

Verify

Troubleshooting

Security best practices