MariaDB Enterprise Manager

MariaDB Enterprise Manager is a comprehensive observability and management solution designed for your entire database fleet. It provides advanced, topology-aware monitoring and a powerful suite of visual tools for query development and schema management, all from a single, centralized interface.

MariaDB Enterprise Operator

MariaDB Enterprise Operator provides a seamless way to run and operate containerized versions of MariaDB Enterprise Server and MaxScale on Kubernetes, allowing you to leverage Kubernetes orchestration and automation capabilities. This document outlines the features and advantages of using Kubernetes and the MariaDB Enterprise Operator to streamline the deployment and management of MariaDB and MaxScale instances.

MariaDB Enterprise MCP Server

MariaDB Enterprise MCP (Model Context Protocol) Server is a secure, enterprise-grade application designed to act as the primary interface between AI assistants and MariaDB data ecosystems. This product solves a key challenge: how to allow powerful AI agents to safely and efficiently leverage an organization's most valuable asset—its data.

MariaDB AI RAG

MariaDB AI RAG is an enterprise-grade Retrieval-Augmented Generation (RAG) solution that integrates with MariaDB to provide AI-powered document processing, semantic search, and natural language generation capabilities.

Hub page for MariaDB Enterprise Manager's pre-packaged Grafana dashboards, which provide deep visibility into server health, database topologies, and system performance.

Specific guidance on migrating database instances into the multi-tenancy Catalog structure within a Kubernetes environment.

The MariaDB Enterprise Operator 26.06 introduces a new feature: Primary Switchover on Graceful Shutdown. This feature is enabled by default and automatically triggers a primary switchover when a primary Pod is gracefully terminated (e.g., during a node drain).

If you are upgrading from a version prior to 26.06 and wish to maintain the previous behavior (i.e., you do not want switchovers to happen automatically on graceful shutdown), you must update your MariaDB Custom Resources (CRs).

Migration Steps

1. Upgrade the CRDs: First, upgrade the MariaDB Enterprise Operator CRDs to version 26.06 or later to make the new configuration fields available. Please refer to the installation guide for detailed instructions on upgrading via Helm.

2. Update MariaDB CRs: After updating the CRDs, edit the spec of all your MariaDB Custom Resources to explicitly disable the feature. This ensures the new behavior is not triggered once the operator controller is upgraded. Add the following configuration under spec.replication.primary:

You can achieve this imperatively using kubectl patch:

1. Update the Operator: Once the CRs have been updated, you can safely upgrade the operator controller to version 26.06.

More Information

For more details, please refer to the Primary Switchover on Graceful Shutdown section in the Replication documentation.

MariaDB Enterprise Manager is a comprehensive observability and management solution designed for your entire database fleet. It provides advanced, topology-aware monitoring and a powerful suite of visual tools for query development and schema management, all from a single, centralized interface.

At its core, Enterprise Manager uses lightweight agents to collect deep telemetry from your standalone databases, replicated topologies, and MaxScale clusters via the OpenTelemetry standard. This foundation powers the integrated Grafana dashboards, which come pre-packaged with production-ready visualizations and alerts. Beyond monitoring, the Workspace provides a shared environment for developers and DBAs with an advanced Query Editor and a visual ERD Designer. The entire system is secured with role-based access control, audit logging, and can integrate with your corporate identity provider (OIDC) for single sign-on.

Key Capabilities at a Glance

Advanced Monitoring

Leverage the power of a built-in Grafana instance, complete with pre-packaged dashboards and production-ready alerts. The platform provides the flexibility to create custom dashboards, define unique alert rules, and route notifications to a wide range of destinations.

Integration with Other Observability Solutions

Built on open standards, Enterprise Manager uses OpenTelemetry for metrics collection. Its integrated Prometheus time-series database exposes a query API, allowing you to seamlessly export metrics and integrate with your existing observability stack.

Centralized Management

Gain a topology-based, centralized view of your entire database fleet. Enterprise Manager discovers and visualizes your replication and clustering setups, providing the ability to drill down into a specific through a seamless single sign-on (SSO) experience.

Workspace

The Workspace provides a powerful suite of tools for developers and DBAs. It features a rich Query Editor for running and debugging SQL and a visual ERD Designer for schema management and modeling across multiple database connections.

Enterprise Security

Secure your management layer with robust security features. Authenticate users with your corporate identity provider (OIDC), enforce granular permissions with role-based access control (RBAC), and maintain compliance with a comprehensive audit log for all administrative actions.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

MariaDB Enterprise Manager is a database management and observability solution that provides advanced topology-aware monitoring coupled with visual schema management, query editing, and ERD design across multiple database connections.

This guide describes steps to install MariaDB Enterprise Manager for evaluation purposes.

MariaDB Enterprise Manager is a client/server application for monitoring and managing MariaDB deployments. It provides topology-aware monitoring, visual schema management, and query editing across multiple database connections.

The architecture consists of two primary components: a central Enterprise Manager Server that aggregates data and hosts the user interface, and an Enterprise Manager Agent that is deployed on each monitored host.

Enterprise Manager Server

The Enterprise Manager Server runs on a dedicated host and acts as the central command center. It is delivered as a suite of container images managed by container engine (Docker or Podman).

The core components are the following:

Enterprise Manager Agent

The Enterprise Manager Agent is installed on each MariaDB Server and MaxScale host that you want to monitor. Its job is to collect data and forward it to the central server.

These components are installed via the mema-agent package (RPM or DEB) and include:

• Prometheus Exporters: These are the primary data gatherers.

  • Node Exporter: Collects system-level metrics (CPU, RAM, disk usage).

  • Mysqld Exporter: Collects detailed metrics from the MariaDB database itself.

• OpenTelemetry Collector: This local collector pulls data from the Prometheus exporters and pushes it to the central collector on the Enterprise Manager Server.

• mema-agent CLI: A setup utility used to register the host with the Enterprise Manager Server and configure the local agent services.

Networking Requirements

For the system to function correctly, the following firewall ports must be open on the Enterprise Manager Server host:

• 8090 (HTTP/S): The main entry point for the web UI. Nginx listens on this port and proxies requests to Supermax and Grafana.

• 4318 (HTTP/S): Agents on monitored nodes push telemetry data to this port.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This section provides an overview of the deployment process for MariaDB Enterprise Manager, covering installation and upgrades for both the central server and the monitoring agents.

MariaDB Enterprise Manager is designed for a streamlined deployment experience. You can launch the main server with a single-line command for a quick start, and a UI-integrated helper tool simplifies the process of installing and registering agents on your monitored databases.

Installing the Enterprise Manager Server

The Enterprise Manager Server is a Docker-based application installed on a dedicated host. The installation is handled by the installer script, which pulls the necessary container images and starts the application.

As a first step review the hardware, system, and network requirements:

• Hardware and System Requirements

• Network and Firewall Requirements

After confirming your hardware, system, and network are compliant, proceed with the installation instructions: Installing MariaDB Enterprise Manager

Installing Enterprise Manager Agents

To monitor a MariaDB Server and MaxScale host, install agent on it. Then, use the Enterprise Manager UI to add the database topology and generate the agent setup command. This command includes the correct metric labels for that host.

Quick start

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This guide outlines the system and hardware requirements for deploying the Enterprise Manager Server and the Enterprise Manager Agent.

Enterprise Manager Server 🖥️

The Enterprise Manager Server is the central component that hosts the UI and stores monitoring data.

Hardware Sizing Guide

System Requirements

• CPU Architecture: x86-64 and ARM64

• Linux OS with either of the supported container engines

  • Docker with Docker Compose https://docs.docker.com/engine/install

  • Podman with Podman Compose

    • The podman-docker compatibility package is required to enable the docker CLI for Podman. All commands in this guide documented for Docker work similarly with Podman.

Enterprise Manager Agent🕵

The agent must be installed on each and MaxScale instance you wish to monitor. Below are the supported operating systems.

Supported Platforms for MariaDB Server

Supported Platforms for MariaDB MaxScale

* Monitoring and Single Sign-On(SSO) are only supported for MaxScale versions 25.10 and Above

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

By default, MariaDB Enterprise Manager retains detailed metrics for 30 days. You can configure this data retention period to balance your need for historical data with storage costs.

This guide explains how to change the retention period and how the underlying storage system works.

How to Change the Retention Period

Changing the retention time is done by editing the environment file for Enterprise Manager and then restarting the services.

cd enterprise-manager/
vim .env

PROMETHEUS_RETENTION_TIME=90d

PROMETHEUS_RETENTION_TIME=52w

docker compose up -d

Data Retention Policy

Prometheus, the time-series database used by Enterprise Manager, does not delete expired data instantly.

• Block-Based Storage: Prometheus stores metrics data in blocks, which are typically two-hour chunks of time. In the background, these small blocks are compacted into larger ones.

• Delayed Cleanup: Data is not deleted on a sample-by-sample basis. Instead, Prometheus removes an entire block once all the data within it has passed the retention period. This cleanup process runs in the background and may not be immediate.

Valid Retention Time Units

When setting PROMETHEUS_RETENTION_TIME, you can use the following units:

• y - years

• w - weeks

• d - days

• h - hours

• m - minutes

• s - seconds

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The mema-agent is a small application that must be installed on every server you wish to monitor with MariaDB Enterprise Manager, including MariaDB Server nodes and MaxScale nodes.

This guide covers the recommended installation method using a package manager.

Prerequisite: Create the Local Monitor User

Before installing the agent on a MariaDB Server host, you must create a local user that the agent will use to connect to the database and collect metrics.

Log in to your MariaDB Server and run the following:

CREATE USER 'monitor'@'localhost' IDENTIFIED BY '<password>';
GRANT SELECT, PROCESS, REPLICATION CLIENT, RELOAD, REPLICA MONITOR, REPLICATION MASTER ADMIN ON *.* TO 'monitor'@'localhost';

Replace <password> with a secure password. You will need these credentials later when linking the agent in the Enterprise Manager UI.

Installation via Package Manager (Recommended)

This method uses your OS's native package manager (dnf, apt, zypper) to install the agent from the MariaDB Enterprise repository.

Step 1: Configure the MariaDB Enterprise Repository

If you haven't already configured the MariaDB Enterprise repository on the server, follow these steps.

Step 2: Install the Agent Package

Once the repository is configured, use your system's package manager to install the agent.

sudo dnf install mema-agent

sudo apt-get install mema-agent

The agent is now installed and running as a service.

Next Steps: Linking the Agent 🔗

After the agent is installed, it is running but not yet configured or linked to your MariaDB Enterprise Manager server.

The final step is to link the agent, which is done from the Enterprise Manager UI. Please refer to the "Adding Databases to MariaDB Enterprise Manager" guide for the specific steps to generate the linking command.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

MariaDB Enterprise Manager allows you to monitor multiple logical databases or clusters that are managed by the same set of high-availability MaxScale instances. After adding your first MaxScale instance, you can easily add more monitors to track different services without re-entering the connection details.

Adding an Additional Monitor

Follow these steps to add another logical database that is monitored by the same MaxScale deployment.

1

Add a new monitored logical database

1. Navigate to your main database inventory page.

2. Locate the existing logical database that is associated with your MaxScale deployment.

3. Click the three-dot menu icon (⋮) on the right side of the database entry to open the context menu and select Add Monitor.

2

Configure the new monitor

1. In the dialog box that appears, provide a new Logical Database Name and select the specific MaxScale Monitor you wish to track from the dropdown list.

2. Click the Confirm button to add the new monitored database.

Changing the Monitor for an Existing Database

If you need to change which MaxScale monitor an existing logical database is tracking, follow these steps.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

For topologies managed by MaxScale, you can seamlessly access the MaxScale GUI directly from Enterprise Manager using Single Sign-On.SSO to MaxScale requires MaxScale 25.10.0 or higher.1

1

Accessing the MaxScale GUI

1. Click the three-dot menu (⋮) next to a MaxScale node.

2. Select "Manage MaxScale".

2

Configuring SSO in maxscale.cnf

To enable SSO, add the following parameters to your MaxScale configuration file (maxscale.cnf) on the MaxScale host:

Parameter

Description

admin_oidc_url

Hostname or IP address of your Enterprise Manager server.

admin_host

Must be set to 0.0.0.0 to allow external connections from Enterprise Manager.

admin_oidc_client_id

Default credentials used by Enterprise Manager to request the access token.

admin_oidc_client_secret

Default credentials used by Enterprise Manager to request the access token.

Copy

[maxscale]
# ... other settings ...
admin_host=0.0.0.0
admin_oidc_url=<Enterprise Manager Host Name>
admin_oidc_client_id=admin
admin_oidc_client_secret=mariadb

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

Before installing MariaDB Enterprise Manager, ensure that your firewall and network rules allow traffic on all required ports. Proper connectivity is essential for the system to function correctly.

The following table details the necessary ports and their purposes.

Summary of Required Firewall Rules

For the current version of MariaDB Enterprise Manager, ensure the following rules are in place:

• From user workstations, allow traffic to the Enterprise Manager Server on TCP port 8090.

• From agent hosts, allow traffic to the Enterprise Manager Server on TCP port 4318.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

MariaDB Enterprise Manager can be integrated with external identity providers (like Okta, Keycloak, or Azure AD) using OpenID Connect (OIDC). This allows you to centralize user authentication, enforce your organization's security policies, and enable single sign-on (SSO).

Before configuring OIDC in Enterprise Manager, you must first register Enterprise Manager as a client application within your Identity Provider's administrative console and obtain the necessary credentials.

Note: This is about backing up the data, configuration and collected metrics of the Enterprise Manager (EM), not the databases.

Backing up Enterprise Manager

mkdir backups

docker run --rm --volumes-from enterprise-manager-grafana -v $(pwd)/backups/:/backups:Z alpine:latest tar -czf /backups/grafana-backup.tar.gz /var/lib/grafana/
docker run --rm --volumes-from enterprise-manager-prometheus -v $(pwd)/backups/:/backups:Z alpine:latest tar -czf /backups/prometheus-backup.tar.gz /prometheus/
docker run --rm --volumes-from enterprise-manager-supermax -v $(pwd)/backups/:/backups:Z alpine:latest tar -czf /backups/supermax-backup.tar.gz /var/lib/supermax/

Restoring Enterprise Manager Server

# Clear out any existing data first
docker run --rm --volumes-from enterprise-manager-grafana -v $(pwd)/backups/:/backups:Z alpine:latest find /var/lib/grafana/ -delete -mindepth 1
docker run --rm --volumes-from enterprise-manager-prometheus -v $(pwd)/backups/:/backups:Z alpine:latest find /prometheus/ -delete -mindepth 1
docker run --rm --volumes-from enterprise-manager-supermax -v $(pwd)/backups/:/backups:Z alpine:latest find /var/lib/supermax/ -delete -mindepth 1

# Restore the data from the backups
docker run --rm --volumes-from enterprise-manager-grafana -v $(pwd)/backups/:/backups:Z alpine:latest tar -C / -xzf /backups/grafana-backup.tar.gz
docker run --rm --volumes-from enterprise-manager-prometheus -v $(pwd)/backups/:/backups:Z alpine:latest tar -C / -xzf /backups/prometheus-backup.tar.gz
docker run --rm --volumes-from enterprise-manager-supermax -v $(pwd)/backups/:/backups:Z alpine:latest tar -C / -xzf /backups/supermax-backup.tar.gz

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

To set the hostname or IP address for an existing MariaDB Enterprise Management instance, follow these instructions. Changing the hostname or IP address is useful if your server's IP changed or if you need to switch from an IP address to a public DNS name.

ssh user@your-server-ip

cd enterprise-manager

nano .env

MEMA_HOSTNAME=your.new.hostname.or.ip

docker compose up -d --force-recreate

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

MariaDB Enterprise Manager provides security at multiple levels, including transport-layer encryption for all components, secure authentication, and a detailed audit log.

SSL/TLS Certificate Management

The Enterprise Manager installation generates a self-signed TLS certificate and key for immediate use. For production environments, you should use your own custom certificates.

The audit log records all REST API requests made to MariaDB Enterprise Manager, providing a clear trail of administrative actions for security and compliance.

The connection from the mema-agent to the Enterprise Manager server is secured using HTTPS.

• To enable encryption: ensure the URL provided in the agent setup command uses https://.

• To bypass certificate checks: if you are using a self-signed or non-trusted TLS certificate on the Enterprise Manager server, you can add the --otlp-insecure flag to the agent setup command. This is recommended only for testing environments.

You can configure secure TLS connections from Enterprise Manager to your monitored MariaDB Servers and MaxScale instances when you first add them.

In the "Add Database" page:

1. Toggle the SSL/TLS option to ON.

2. To validate the server's certificate against your Certificate Authority (CA), provide the path to your CA file in the Certificate Authority field. The file must be located in the enterprise-manager/certs/ directory and the path must begin with /certs/.

3. Check Verify peer certificate to enable validation.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This dashboard shows MaxScale’s health and load, how backend servers are seen by each MaxScale, and the traffic/query volume flowing through it—plus cache efficiency from the Query Classifier.

Provides a visual representation of the entire system's architecture and connectivity.

The Node Dashboard pane provides detailed visibility into the health and performance of individual nodes that run MariaDB Server and MaxScale. It combines uptime, system capacity, operating system details, and hardware utilization with disk and network activity. This view helps administrators ensure each node has sufficient resources and can support the workloads running on it.

Provides a high-level, at-a-glance summary of a specific server node's status, configuration, and capacity.

The "fleet" dashboard is the central inventory for all your monitored database topologies. It provides a hierarchical, at-a-glance overview of the health, status, and configuration of your entire database environment.

This column displays the logical names of your databases and the individual server nodes within each topology. It also contains important status and quick-access icons.

The dashboard mirrors most sections from the MariaDB Server dashboard extending it with Galera Metrics section and the Galera Nodes table. Use this dashboard when you need Galera-specific cluster health alongside the familiar server views.

Galera Metrics

Insights into Galera Cluster health with critical metrics and node-specific status details.

Per-node status summary with short state logic

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

MariaDB Server Metrics

MariaDB Server metrics are gathered with the Prometheus exporter for MySQL and stored in Enterprise Manager’s Prometheus with the mariadb prefix. The agent runs the exporter with the following collector flags:

MaxScale Metrics

MariaDB Enterprise Manager collects a wide range of time-series metrics from your MariaDB MaxScale instances to provide deep insight into their performance, health, and activity. Monitoring these metrics is crucial for diagnosing performance bottlenecks, ensuring high availability, and understanding how your database proxy is handling application traffic.

Here is the list of available MaxScale metrics collected by Enterprise Manager.

Node Metrics

Node metrics provide crucial information about the health and performance of the underlying hardware and operating system on each monitored host. These metrics are essential for diagnosing infrastructure bottlenecks, understanding resource utilization, and planning for future capacity.

MariaDB Enterprise Manager gathers these metrics using Prometheus Node Exporter, which includes a default set of collectors.

Key metrics collected by default include:

• CPU Usage: Overall and per-core utilization, load average, and context switching.

• Memory: Total, used, free, and cached memory, including swap space.

• Disk I/O: Read/write operations, throughput (bytes per second), and I/O time.

• Filesystem Usage: Total, used, and available space for each mounted filesystem.

• Network Traffic: Data sent and received, packets, and network interface errors.

For a complete and detailed list of all metrics gathered by the default collectors, please refer to the official Prometheus Node Exporter documentation.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

MariaDB Enterprise Manager provides two primary methods for exporting metrics, allowing you to integrate with external observability platforms for aggregation or long-term retention.

MariaDB Enterprise Manager provides a powerful and flexible alerting system, built on the capabilities of the integrated Grafana Alerting engine. It allows you to proactively monitor your entire database fleet, define custom rules for potential issues, and receive notifications through various channels to ensure you can respond quickly.

How It Works: The Alerting Flow

The alerting process in MariaDB Enterprise Manager follows a clear, four-step flow from detection to notification.

Key Alerting Concepts

To configure alerting effectively, it's helpful to understand these core concepts from Grafana:

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This page explains how to configure email alerting for MariaDB Enterprise Manager using Grafana's integrated alerting engine. SMTP is configured through Grafana's standard GF_SMTP_* environment variables, which are passed to the Grafana container via the Enterprise Manager .env file. For the complete list of available options, refer to the Grafana SMTP configuration documentation.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

Workspace enhances MariaDB Enterprise Manager by adding query editing, visual schema management, and ERD design. It provides a collaborative environment for DBAs, developers, and analysts.

Enterprise manager provides a visual interface for creating entity relationship diagrams (ERD) and for observing existing database schemas, so you can quickly understand table relationships, identify dependencies, and visually assess the impact of schema changes before implementation.

This procedure outlines the steps required to access and utilize the ERD Designer within the Workspace section of Enterprise Manager UI.

1. From the main Workspace screen, click the "Run Queries" card.\

The MariaDB Enterprise Manager Workspace includes a powerful set of integrated tools that allow DBAs and developers to perform common administrative tasks graphically, without needing to write raw SQL commands. These features are primarily accessed through the Schemas Sidebar and dedicated tabs in the main worksheet area.

Schema Inspector

The Schema Inspector provides detailed, read-only metadata views for any selected schema object. This allows you to quickly understand the structure, data types, constraints, and dependencies of your tables, views, and other objects without querying the information_schema. To use it, simply click on an object in the Object Browser.

Object Browser

The Object Browser is the hierarchical tree view located in the Schemas Sidebar on the left side of the Workspace. It is your primary tool for navigating and exploring your database instances. You can expand databases to see their tables, views, stored procedures, and triggers, and use the filter box at the top to quickly locate specific objects.

Object Editor

The Object Editor allows you to create, modify, and delete schema objects using graphical forms and dialogs. You can access these functions by right-clicking on an object (or object type) in the Object Browser. This will open a context menu with actions such as:

• CREATE TABLE, CREATE VIEW

• ALTER TABLE

• DROP TABLE

• Managing constraints and relationships

• Renaming or copying objects

User Management

This dedicated tab provides a grid-based interface for managing database users and their privileges directly, without writing GRANT or CREATE USER statements.

From this interface, you can:

• View a list of all database users and their assigned global privileges.

• Create new database users using a simple form.

• Edit an existing user's password or modify their privileges.

• Delete users who no longer require access.

Process List Viewer

The Processlist tab provides a real-time view of the database server's active sessions and the commands they are executing, equivalent to running SHOW FULL PROCESSLIST. This is an essential tool for diagnosing performance issues.

Using the Processlist Viewer, you can:

• Monitor all active connections, their current status (e.g., Query, Sleep), and how long they have been running.

• Identify long-running or problematic queries that may be impacting server performance.

• Manage live sessions, which may include the ability to terminate (kill) a specific process.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This documentation aims to provide guidance on how to configure access to docker.mariadb.com in your MariaDB Enterprise Kubernetes Operator resources.

MariaDB Corporation requires customers to authenticate when logging in to the . A Customer Download Token must be provided as the password. Customer Download Tokens are available through the MariaDB Customer Portal. To retrieve the customer download token for your account:

• Navigate to the .

This guide aims to provide a quick way to get started with the MariaDB Enterprise Kubernetes Operator for Kubernetes. It will walk you through the process of deploying a MariaDB Enterprise Cluster and MaxScale via the MariaDB and MaxScale CRs () respectively.

Before you begin, ensure you meet the following prerequisites:

• Configure your

This operator allows you to configure standalone MariaDB Enterprise Server instances. To achieve this, you can either omit the replicas field or set it to 1:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb
spec:
  rootPasswordSecretKeyRef:
    name: mariadb
    key: password

  replicas: 1

  port: 3306

  storage:
    size: 1Gi

  myCnf: |
    [mariadb]
    bind-address=*
    default_storage_engine=InnoDB
    binlog_format=row
    innodb_autoinc_lock_mode=2
    innodb_buffer_pool_size=800M
    max_allowed_packet=256M

  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      memory: 1Gi

  metrics:
    enabled: true

Whilst this can be useful for development and testing, it is not recommended for production use because of the following reasons:

• Single point of failure

• Upgrades require downtime

• Only vertical scaling is possible

For achieving high availability, we recommend deploying a highly available topology as described in the high availability guide.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

In order to effectively manage the full lifecycle of both replication and Galera topologies, the operator relies on a set of components that run alonside the MariaDB instances and expose APIs for remote management. These components are collectively referred to as the "data-plane".

Components

The mariadb-enterprise-operator data-plane components are implemented as lightweight containers that run alongside the MariaDB instances within the same Pod. These components are available in the operator image. More preciselly, they are subcommands of the CLI shipped as binary inside the image.

Init container

The init container is responsible for dynamically generating the Pod-specifc configuration files before the MariaDB container starts. It also plays a crucial role in the MariaDB container startup, enabling replica recovery for the replication topolology and guaranteeing ordered deployment of Pods for the Galera topology.

Agent sidecar

The agent sidecar provides an HTTP API that enables the operator to remotely manage MariaDB instances. Through this API, the operator is able to remotely operate the data directory and handle the instance lifecycle, including operations such as replica recovery for replication and cluster recovery for the Galera topology. It supports multiple authentication methods to ensure that only the operator is able to call the agent API.

Since it has access to the data directory, it is also responsible for periodically archiving binary logs to be used for point-in-time recovery.

Agent auth methods

As previously mentioned, the agent exposes an API to remotely manage the replication and Galera clusters. The following authentication methods are supported to ensure that only the operator is able to call the agent:

ServiceAccount based authentication

The operator uses its ServiceAccount token as a mean of authentication for communicating with the agent, which subsequently verifies the token by creating a TokenReview object. This is the default authentication method and will be automatically applied by setting:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-repl
spec:
  # [...]
  replication:
    agent:
      kubernetesAuth:
        enabled: true
  # [...]

This Kubernetes-native authentication mechanism eliminates the need for the operator to manage credentials, as it relies entirely on Kubernetes for this purpose. However, the drawback is that the agent requires cluster-wide permissions to impersonate the system:auth-delegator ClusterRole and to create TokenReviews, which are cluster-scoped objects.

Basic authentication

As an alternative, the agent also supports basic authentication:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-repl
spec:
  # [...]
  replication:
    agent:
      basicAuth:
        enabled: true
  # [...]

Unlike the ServiceAccount based authentication, the operator needs to explicitly generate credentials to authenticate. The advantage of this approach is that it is entirely decoupled from Kubernetes and it does not require cluster-wide permissions on the Kubernetes API.

Updates

Please refer to the updates documentation for more information about how to update the data-plane.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

blob-csi-driver (Azure Blob Storage)

This section outlines a recommended StorageClass configuration for the Azure Blob Storage CSI Driver that resolves common mounting and list operation issues encountered in Kubernetes environments.

The following StorageClass is recommended when working with Azure Blob Storage (ABS).

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: blob-fuse
provisioner: blob.csi.azure.com
parameters:
  protocol: fuse2
reclaimPolicy: Retain
volumeBindingMode: Immediate
allowVolumeExpansion: true
mountOptions:
  # Resolves the issue where non-root containers cannot access the mounted blob container.
  - -o allow_other
  # Ensures list operations (critical for backups/deletion) work immediately upon mount.
  - --cancel-list-on-mount-seconds=0

Next, when defining your PhysicalBackup resource, make sure to use the new StorageClass we created.

apiVersion: enterprise.mariadb.com/v1alpha1
kind: PhysicalBackup
metadata:
  name: physicalbackup
spec:
  # [...]
  storage:
    persistentVolumeClaim:
      # Specify your own class
      storageClassName: blob-fuse
  # [...]

Issue 1: Access for Non-Root Containers (-o allow_other)

The default configuration prevents non-root Kubernetes containers from accessing the mounted blob container, resulting in an "unaccessible" volume. By setting the mountOption -o allow_other, non-root containers are granted access to the volume, resolving this issue.

See this issue for more information.

Issue 2: Immediate List Operations and Backup Deletion (--cancel-list-on-mount-seconds=0)

When using the blob-csi-driver with its default settings, list operations (which are critical for cleaning up old backups) may not work immediately upon mount, leading to issues like old physical backups never being deleted. Setting the mountOption --cancel-list-on-mount-seconds to "0" ensures that list operations work as expected immediately after the volume is mounted.

See this issue for more information.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This operator gives you flexibility to define the storage that will back the /var/lib/mysql data directory mounted by MariaDB.

Configuration

The simplest way to configure storage for your MariaDB is:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-galera
spec:
  storage:
    size: 1Gi

This will make use of the default StorageClass available in your cluster, but you can also provide a different one:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-galera
spec:
  storage:
    size: 1Gi
    storageClassName: gp3

Under the scenes, the operator is configuring the StatefulSet's volumeClaimTemplate property, which you are also able to provide yourself:

It is possible to resize your storage after having provisioned a MariaDB. We need to distinguish between:

• PVCs already in use.

• StatefulSet storage size, which will be used when provisioning new replicas.

It is important to note that, for the first case, your StorageClass must support volume expansion by declaring the allowVolumeExpansion = true. In such case, it will be safe to expand the storage by increasing the size and setting resizeInUseVolumes = true:

Depending on your storage provider, this operation might take a while, and you can decide to wait for this operation before the MariaDB becomes ready by setting waitForVolumeResize = true. Operations such as and will not be performed if the MariaDB resource is not ready.

Provisioning standalone MariaDB instances with ephemeral storage can be done by setting ephemeral = true:

This may be useful for multiple use cases, like provisioning ephemeral MariaDBs for the integration tests of your CI.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The root password for a MariaDB resource can be specified in a Secret, like so:

By default, rootPasswordSecretKeyRef are optional and defaulted by the operator, resulting in random password generation if not provided:

You may choose to explicitly provide a Secret reference via rootPasswordSecretKeyRef and opt-out from random password generation by either not providing the generate field or setting it to false:

This guide illustrates, step by step, how to update to 25.8.0 from previous versions.

• Uninstall you current mariadb-enterprise-operator for preventing conflicts:

helm uninstall mariadb-enterprise-operator

Alternatively, you may only downscale and delete the webhook configurations:

kubectl scale deployment mariadb-enterprise-operator --replicas=0
kubectl scale deployment mariadb-enterprise-operator-webhook --replicas=0
kubectl delete validatingwebhookconfiguration mariadb-enterprise-operator-webhook
kubectl delete mutatingwebhookconfiguration mariadb-enterprise-operator-webhook

• Upgrade mariadb-enterprise-operator-crds to 25.8.0:

helm repo update mariadb-enterprise-operator
helm upgrade --install mariadb-enterprise-operator-crds  mariadb-enterprise-operator/mariadb-enterprise-operator-crds --version 25.8.0

• The Galera data-plane must be updated to the 25.8.0 version.

If you want the operator to automatically update the data-plane (i.e. init and agent containers), you can set updateStrategy.autoUpdateDataPlane=true in your MariaDB resources:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-galera
spec:
  updateStrategy:
+   autoUpdateDataPlane: true

Alternatively, you can also do this manually:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb
spec:
  galera:
    agent:
-      image: docker.mariadb.com/mariadb-enterprise-operator:1.0.0
+      image: docker.mariadb.com/mariadb-enterprise-operator:25.8.0
    initContainer:
-      image: docker.mariadb.com/mariadb-enterprise-operator:1.0.0
+      image: docker.mariadb.com/mariadb-enterprise-operator:25.8.0

• Upgrade mariadb-enterprise-operator to 25.8.0:

helm repo update mariadb-enterprise-operator
helm upgrade --install mariadb-enterprise-operator mariadb-enterprise-operator/mariadb-enterprise-operator --version 25.8.0 

• If you previously decided to downscale the operator, make sure you upscale it back:

kubectl scale deployment mariadb-enterprise-operator --replicas=1
kubectl scale deployment mariadb-enterprise-operator-webhook --replicas=1

• If you previously set updateStratety.autoUpdateDataPlane=true, you may consider reverting the changes once the upgrades have finished:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-galera
spec:
  updateStrategy:
+   autoUpdateDataPlane: false
-   autoUpdateDataPlane: true

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This guide illustrates, step by step, how to update to 25.10.6 from previous versions. This guide only applies if you are updating from a version prior to 25.10.x, otherwise you may upgrade directly (see and docs)

• The Galera data-plane must be updated to the 25.10.6 version. You must set updateStrategy.autoUpdateDataPlane=true in your MariaDB resources before updating the operator. Then, once updated, the operator will also be updating the data-plane based on its version:

This guide illustrates, step by step, how to update to 26.3.2 from previous versions. This guide only applies if you are updating from a version prior to 26.3.x, otherwise you may upgrade directly (see Helm and OpenShift docs)

• The data-plane must be updated to the 26.3.2 version. You must set updateStrategy.autoUpdateDataPlane=true in your MariaDB resources before updating the operator. Then, once updated, the operator will also be updating the data-plane based on its version:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-galera
spec:
  updateStrategy:
+   autoUpdateDataPlane: true

• MaxScale embedded definition inside the MariaDB has been deprecated, please refer to the to perform the migration.

• At this point, you may proceed to update the operator. If you are using Helm:

Upgrade the mariadb-enterprise-operator-crds helm chart to 26.3.2:

Upgrade the mariadb-enterprise-operator helm chart to 26.3.2:

• If you are on OpenShift:

If you are on the stable channel using installPlanApproval=Automatic in your Subscription object, then the operator will be automatically updated. If you use installPlanApproval=Manual, you should have a new InstallPlan which needs to be approved to update the operator:

• Consider reverting updateStrategy.autoUpdateDataPlane back to false in your MariaDB object to avoid unexpected updates:

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

This guide illustrates, step by step, how to update to 26.6.0 from previous versions. This guide only applies if you are updating from a version prior to 26.6.x, otherwise you may upgrade directly (see docs).

• The must be updated to the 26.6.0 version. You must set updateStrategy.autoUpdateDataPlane=true in your MariaDB resources before updating the operator. Then, once updated, the operator will also update the data-plane based on its version:

Suspended state

When a resource is suspended, all operations performed by the operator are disabled, including but not limited to:

• Provisioning

• Upgrades

• Volume resize

• Galera cluster recovery

More specifically, the reconciliation loop of the operator is omitted, anything part of it will not happen while the resource is suspended. This could be useful in maintenance scenarios, where manual operations need to be performed, as it helps prevent conflicts with the operator.

Suspend a resource

Currently, only MariaDB and MaxScale resources support suspension. You can enable it by setting suspend=true:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-galera
spec:
  # [...]
  suspend: true
  # [...]

This results in the reconciliation loop being disabled and the status being marked as Suspended:

kubectl get mariadbs
NAME             READY   STATUS      PRIMARY           UPDATES                   AGE
mariadb-galera   True    Suspended   mariadb-galera-0  ReplicasFirstPrimaryLast  12m

To re-enable it, simply remove the suspend setting or set it to suspend=false.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The following is a list of images that have plugins installed and available to use.

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb
spec:
  # ....
  myCnf: |
    [mariadb]
    plugin_load_add = auth_pam # Load auth plugin
  # ....

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The examples catalog contains a number of sample manifests that aim to show the operator functionality in a practical way. Follow these instructions for getting started:

• Download the examples catalog:

curl -sLO https://operator.mariadb.com/examples/manifests.tar.gz
mkdir -p examples
tar -xzf manifests.tar.gz -C examples

• Install the configuration shared by all the examples:

kubectl apply -f examples/config

• Start deploying examples:

kubectl apply -f examples/mariadb.yaml

Some examples rely on external dependencies for specific tasks, make sure to install them when it applies:

• prometheus-operator for metrics

• cert-manager for TLS certificates

• minio for S3 object storage

It is recommended to complement the examples with the API reference documentation to understand the full range of configuration options available.

If you are looking for production-grade examples, you can check the following manifests:

• mariadb_replication_production.yaml and maxscale_replication_production.yaml for asynchronous replication

• mariadb_galera_production.yaml and maxscale_galera_production.yaml for Galera

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

In this guide, we will be migrating from the to the without downtime. This guide assumes:

• version of the MariaDB Community Operator is installed in the cluster.

• MariaDB community resources will be migrated to its counterpart MariaDB enterprise resource. In this case, we will be using 11.4.4

In this guide, we will be migrating an external MariaDB into a new MariaDB instance running in Kubernetes and managed by MariaDB Enterprise Kubernetes Operator. We will be using logical backups for achieving this migration.

1. Take a logical backup of your external MariaDB using one of the commands below:

mariadb-dump --user=${MARIADB_USER} --password=${MARIADB_PASSWORD} --host=${MARIADB_HOST} --single-transaction --events --routines --all-databases > backup.2024-08-26T12:24:34Z.sql

If you are currently using or migrating to a Galera instance, use the following command instead:

mariadb-dump --user=${MARIADB_USER} --password=${MARIADB_PASSWORD} --host=${MARIADB_HOST} --single-transaction --events --routines --all-databases --skip-add-locks --ignore-table=mysql.global_priv > backup.2024-08-26T12:24:34Z.sql

2. Ensure that your backup file matches the following format: backup.2024-08-26T12:24:34Z.sql. If the file name does not follow this format, it will be ignored by the operator.

3. Upload the backup file to one of the supported storage types. We recommend using S3.

4. Create your MariaDB resource declaring that you want to and providing a that matches the backup:

5. If you are using Galera in your new instance, migrate your previous users and grants to use the User and Grant CRs. Refer to the for further detail.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

In this guide, we will be migrating a MaxScale embedded in a MariaDB resource to it's own resource.

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb
spec:
+  maxScaleRef:
+     name: mariadb-maxscale
-  # Provision a MaxScale instance and set 'spec.maxScaleRef' automatically.
-  maxScale:
-    enabled: true
-    connection:
-      secretName: mxs-repl-conn
-      port: 3306
-    metrics:
-      enabled: true

1. Get the migration script and grant execute permissions:

curl -sLO https://operator.mariadb.com/scripts/migrate_maxscale_to_resource.sh
chmod +x migrate_maxscale_to_resource.sh

2. Migrate all of your existing MariaDB resources where MaxScale is embedded.

./migrate_maxscale_to_resource.sh <mariadb_manifest.yaml>

This will have created new <migrated.mariadb_manifest.yaml> manifests.

3. Inspect the newly created manifests and overwrite the source manifests if satisfied with the changes.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

The MariaDB Enterprise MCP (Model Context Protocol) Server is a secure, enterprise-grade application designed to act as the primary interface between AI assistants and MariaDB data ecosystems. This product solves a key challenge: how to allow powerful AI agents to safely and efficiently leverage an organization's most valuable asset—its data.

It achieves this by providing a single, hardened endpoint that offers not only standard database operations but also advanced AI workflow orchestration and integration with industry-standard authentication systems.

What is a Model Context Protocol (MCP) Server?

MCP provides a standardized, model-agnostic way for language models and other AI systems to interact with external tools and data sources. The MCP Server implements this protocol, ensuring a consistent and reliable method for AI applications to request information and perform operations. This streamlined communication layer accelerates the development and deployment of AI-integrated systems.

The Value of an MCP Server for Databases

Connecting AI directly to a production database is both risky and inefficient. An MCP server provides a critical abstraction layer that delivers three key benefits:

1. Security and Governance: It acts as a single, hardened chokepoint for all AI-driven data interactions. Instead of embedding credentials across numerous applications, the MCP Server manages access centrally, enabling robust auditing, permission enforcement, and integration with enterprise secret managers.

2. Abstraction and Simplicity: Developers building AI applications do not need to be database experts. They can interact with a simple, well-defined set of tools (e.g., list_tables, execute_sql) without writing complex connection logic or security checks, dramatically accelerating development cycles.

3. Standardization and Interoperability: By adhering to the MCP standard, your data infrastructure can seamlessly connect with a growing ecosystem of AI assistants and development frameworks—such as Cursor, Windsurf, and VSCode plugins—without requiring bespoke integrations for each one.

The primary goal of the MariaDB Enterprise MCP Server is to enable the secure and scalable deployment of AI agents within enterprise environments.

Key objectives include:

• Enhance Security and Compliance: Integrate with centralized secret management platforms like HashiCorp Vault and 1Password to eliminate static credentials and meet stringent enterprise security policies.

• Streamline Complex AI Workflows: Provide a unified endpoint for orchestrating multi-step RAG (Retrieval-Augmented Generation) pipelines, from data ingestion to final response generation.

• Improve Manageability: Offer a robust, configurable, and observable server that can be reliably deployed and managed by platform engineering and DBA teams.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

Token management is a critical part of the system's security, handled primarily by the RAG API.

Token Generation

The process involves two main steps:

Step 1: User Registration

Step 2: User Login & Token Generation

Token Usage

Once a client has a JWT, it includes it in the Authorization header of every request to the MCP Server. The server then validates the token before processing the request.

Key Security Measures

• Signature Verification: Prevents token tampering.

• Expiration Check: Tokens have a limited lifetime (e.g., 30 minutes).

• Database Validation: Ensures the user associated with the token still exists and is active.

• Issuer/Audience Validation: Prevents a token from one system from being used on another.

• Not-Before Check: Prevents a token from being used before it is valid

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

Standard SQL Query

{ "tool": "execute_sql", "parameters": { "database_name": "test_db", "sql_query": "SELECT * FROM users WHERE id = %s", "parameters": [123] } }

Create Vector Store

{ "tool": "create_vector_store", "parameters": { "database_name": "test_db", "vector_store_name": "my_vectors", "model_name": "text-embedding-3-small", "distance_function": "cosine" } }

Insert Documents into Vector Store

{ "tool": "insert_docs_vector_store", "parameters": { "database_name": "test_db", "vector_store_name": "my_vectors", "documents": ["Sample text 1", "Sample text 2"], "metadata": [{"source": "doc1"}, {"source": "doc2"}] } }

Semantic Search

{ "tool": "search_vector_store", "parameters": { "database_name": "test_db", "vector_store_name": "my_vectors", "user_query": "What is the capital of France?", "k": 5 } }

RAG Generation

{ "tool": "rag_generation", "parameters": { "database_name": "test_db", "vector_store_name": "my_vectors", "user_query": "What is the capital of France?", "k": 5, "temperature": 0.9 } }

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

MariaDB AI RAG is an all-in-one, enterprise-ready solution that handles the entire Retrieval-Augmented Generation (RAG) pipeline, including document parsing with layout extraction, chunking, embedding generation, and easy-to-use retrieval APIs backed by hybrid search (vector + full-text search), with optional reranking before sending the relevant context to a foundation model for answer generation.

Key Features

• Document ingestion and processing

• Semantic chunking and embedding

• Vector-based similarity search

• AI-powered response generation

• Database integration

• Fine-grained access control

• Comprehensive REST API

For detailed information on each component, please refer to the specific documentation sections.

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}