Upgrading to Enterprise Audit

Uninstall the v1 MariaDB Audit Plugin and migrate its settings, filters, and user lists to MariaDB Enterprise Audit (v2).

MariaDB Enterprise Audit is included with MariaDB Enterprise Server. Special consideration is needed when upgrading from MariaDB releases that include the MariaDB Audit Plugin, including MariaDB Community.

For details on how to upgrade from the MariaDB Audit Plugin to MariaDB Enterprise Audit, see the sections below.

Before upgrading the package: Remove the v1 plugin and every server_audit_* variable setting from your configuration files before running apt upgrade (or your platform's equivalent). The new Enterprise Server does not recognize the v1 variables and will fail to start if they remain. Follow the pre-upgrade cleanup steps below.

Migrating from MariaDB Audit Plugin (v1)

MariaDB Enterprise Audit (server_audit2.so) is a different and incompatible plugin from the older MariaDB Audit Plugin (v1, server_audit.so) found in Community Server or older Enterprise Server versions.

The v1 plugin is configured with server variables (e.g., server_audit_events).

The Enterprise (v2) plugin is configured with system tables (e.g., mysql.server_audit_filters).

You must uninstall the v1 plugin before using the v2 plugin, as running both can cause server instability or deadlocks (MENT-545). The following sections guide you through the full migration process, starting with checking for and removing the old plugin.

Check for and Uninstall the v1 Plugin

Confirm the MariaDB Audit Plugin is Loaded

To confirm that the MariaDB Audit plugin is loaded, query the information_schema.PLUGINS table:

SELECT PLUGIN_STATUS, PLUGIN_LIBRARY, PLUGIN_DESCRIPTION
FROM information_schema.PLUGINS
WHERE PLUGIN_NAME='SERVER_AUDIT'\G

*************************** 1. row ***************************
     PLUGIN_STATUS: ACTIVE
    PLUGIN_LIBRARY: server_audit.so
PLUGIN_DESCRIPTION: Audit the server activity

If you see the output shown above, then the MariaDB Audit plugin is installed, and it must be uninstalled prior to performing the upgrade or migration. Follow the instructions in the section below.

If you do not see any rows in the output, then the MariaDB Audit plugin is not installed.

Determine Uninstallation Method

The MariaDB Audit plugin has multiple uninstallation methods. You must choose the uninstallation method that corresponds to how the plugin was installed on your system.

To determine the uninstallation method, query the mysql.plugin system table:

SELECT *
FROM mysql.plugin
WHERE name = 'SERVER_AUDIT'\G

*************************** 1. row ***************************
name: SERVER_AUDIT
  dl: server_audit.so

If you see the output shown above, then the MariaDB Audit plugin can be uninstalled with UNINSTALL SONAME.

If you do not see any rows in the output, then the MariaDB Audit plugin can be uninstalled by editing the configuration file.

Uninstall with UNINSTALL SONAME

To uninstall the MariaDB Audit Plugin with UNINSTALL SONAME:

1

Check the plugin load option by querying the information_schema.PLUGINS table:

SELECT PLUGIN_STATUS, PLUGIN_LIBRARY, PLUGIN_DESCRIPTION, LOAD_OPTION
FROM information_schema.PLUGINS
WHERE PLUGIN_NAME='SERVER_AUDIT'\G

*************************** 1. row ***************************
     PLUGIN_STATUS: ACTIVE
    PLUGIN_LIBRARY: server_audit.so
PLUGIN_DESCRIPTION: Audit the server activity
       LOAD_OPTION: FORCE_PLUS_PERMANENT

2

Check LOAD_OPTION column for FORCE_PLUS_PERMANENT

If the LOAD_OPTION column does not contain the value FORCE_PLUS_PERMANENT, then you can skip to step 5, which executes the UNINSTALL SONAME statement.

If the LOAD_OPTION column contains the value FORCE_PLUS_PERMANENT, then check your configuration files for the server-audit option:

$ grep --extended-regexp --with-filename \
   'server[-_]audit[[:blank:]]*=' \
   /etc/mysql/my.cnf \
   /etc/mysql/mariadb.conf.d/*

/etc/mysql/mariadb.conf.d/enable-audit.cnf:server_audit=FORCE_PLUS_PERMANENT

3

If the server-audit option was found in a configuration file, then remove or comment the option out:

[mariadb]
# server_audit=FORCE_PLUS_PERMANENT

4

If the configuration file was changed, then restart the server:

$ sudo systemctl restart mariadb

5

Uninstall the plugin by executing the UNINSTALL SONAME statement:

UNINSTALL SONAME 'server_audit';

6

Confirm the plugin is uninstalled by querying the mysql.plugin system table:

SELECT *
FROM mysql.plugin
WHERE name = 'SERVER_AUDIT'\G

If the query returns no results, then the plugin has been uninstalled.

Uninstall with Configuration File

To uninstall the MariaDB Audit plugin with a configuration file:

1

Check your configuration files for the plugin_load_add option:

$ grep --extended-regexp --with-filename \
   'plugin[-_]load[-_]add[[:blank:]]*=[[:blank:]]*server_audit' \
   /etc/mysql/my.cnf \
   /etc/mysql/mariadb.conf.d/*

/etc/mysql/mariadb.conf.d/enable-audit.cnf:plugin_load_add=server_audit

2

Remove or comment out the plugin_load_add option from the configuration file:

[mariadb]
# plugin_load_add=server_audit

Remove v1 Variable Settings

After uninstalling the plugin, also remove every server_audit_* system variable from your configuration files. If any of these settings remain, the new Enterprise Server will fail to start because it does not recognize them.

$ grep --extended-regexp --with-filename \
   'server_audit[_a-z]*[[:blank:]]*=' \
   /etc/mysql/my.cnf \
   /etc/mysql/mariadb.conf.d/*

Comment out or delete every matching line. Common variables include server_audit_events, server_audit_logging, server_audit_incl_users, server_audit_excl_users, server_audit_file_path, server_audit_output_type, server_audit_query_log_limit, and server_audit_file_rotate_size.

Migrate v1 Settings to Enterprise Audit (v2)

Update System Tables

After upgrading to MariaDB Enterprise Server, execute mariadb-upgrade to create the System Tables for Audit Filters.

If mariadb-upgrade reports that the installation is already up to date — for example, when upgrading from Community Server 10.6 to Enterprise Server 10.6 — the audit-filter system tables will not be created. In that case, run mariadb-upgrade --force to force the upgrade scripts to run anyway. See mariadb-upgrade for the full behaviour.

Migrate Audit Filters

The MariaDB Audit Plugin defines Audit Filters using the server_audit_events system system variable, but MariaDB Enterprise Audit defines Audit Filters using the mysql.server_audit_filters system table.

If you are upgrading from the MariaDB Audit Plugin to MariaDB Enterprise Audit, perform the following procedure:

1

Remove or comment out lines involving the server_audit_events system variable from the configuration file:

[mariadb]
...
# server_audit_events=CONNECT,QUERY

2

Insert a replacement Audit Filter into the mysql.server_audit_filters system table:

INSERT INTO mysql.server_audit_filters
   VALUES ('default',
      JSON_COMPACT(
         '{
            "connect_event": "ALL",
            "query_event": "ALL"
         }'
      ));

The example passes the JSON object to the JSON_COMPACT() function, so that the JSON object is compacted prior to being inserted into the system table. This step is recommended, but not required.

Migrate Users

The MariaDB Audit Plugin enables or disable audit logging for specific user accounts using the server_audit_incl_users and server_audit_excl_users system variables, but MariaDB Enterprise Audit uses the mysql.server_audit_users system table.

If you are upgrading from the MariaDB Audit Plugin to MariaDB Enterprise Audit, perform the following procedure:

1

Edit configuration file

Remove or comment out lines involving the server_audit_incl_users and server_audit_excl_users system variables from the configuration file:

[mariadb]
...
# server_audit_incl_users = root,app
# server_audit_excl_users = backup_user,monitor_user

2

For the server_audit_incl_users system variable

For any user account previously mentioned in the server_audit_incl_users system variable, determine if the user account can use the Default Audit Filter or if the user account requires a Named Audit Filter.

Insert the relevant Audit Filters into the mysql.server_audit_filters system table, and insert the user assignments into the mysql.server_audit_users system table:

INSERT INTO mysql.server_audit_filters
   VALUES
   ('default',
      JSON_COMPACT(
         '{
            "connect_event": [
               "CONNECT",
               "DISCONNECT"
            ],
            "query_event": [
               "DML",
               "DDL"
            ]
         }'
   )),
   ('root_filter',
      JSON_COMPACT(
         '{
            "logging": "ON"
         }'
   ));
INSERT INTO mysql.server_audit_users (host, user, filtername)
   VALUES ('%', 'root', 'root_filter');

The example passes the JSON object to the JSON_COMPACT() function, so that the JSON object is compacted prior to being inserted into the system table. This step is recommended, but not required.

3

For the server_audit_excl_users system variable

For any user account previously mentioned in the server_audit_excl_users system variable, create a Named Audit Filter that acts as an exclusion filter.

Insert the relevant Audit Filters into the mysql.server_audit_filters system table, and insert the user assignments into the mysql.server_audit_users system table:

INSERT INTO mysql.server_audit_filters
   VALUES ('exclusion_filter',
      JSON_COMPACT(
         '{
            "logging": "OFF"
         }'
      ));

INSERT INTO mysql.server_audit_users (host, user, filtername)
   VALUES
   ('%', 'backup_user', 'exclusion_filter'),
   ('%', 'monitor_user', 'exclusion_filter');

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