Install and configure MariaDB with ejabberd

By default, ejabberd uses the Mnesia internal database. It is great for home and small office environments, but in larger companies, as the amount of chat logs and users grows, we need more scalability. Today, I will show you how to install MariaDB, a MySQL-compatible database, migrate your data and configure ejabberd to use MariaDB instead of Mnesia.

» Don’t want to migrate data yourself?
ProcessOne experts will make your communication scalable. Contact us »

MariaDB with ejabberd

Installing MariaDB

We assume the usual Debian configuration as in my previous tutorials. I have updated my ejabberd to version 21.01 (the update process is the same as the initial ejabberd installation, so check my first tutorial).

To install MariaDB simply use:

apt-get install mariadb-server

Then run the installation wizard and follow the instructions:


Preparing MariaDB for ejabberd

To get MariaDB ready for ejabberd, we need to create a new database, its user, and then populate the database with the ejabberd SQL schema.

First, let’s create the database using your MariaDB root user:

echo "CREATE DATABASE ejabberd;" | mysql -h localhost -u root -p

Next, let’s create a dedicated ejabberd user authenticated with a password, and assign it to this database. The Enter password prompt is again asking about the root MariaDB user:

echo "GRANT ALL ON ejabberd.* TO 'ejabberd'@'localhost' IDENTIFIED BY 'password';" | mysql -h localhost -u root -p

Finally, let’s download the latest ejabberd SQL schema and load it into our database. This time, we are switching to using the ejabberd MariaDB user, and the Enter password prompt is asking for the password we just specified in the GRANT command above:

mysql -h localhost -D ejabberd -u ejabberd -p < mysql.sql

To verify that everything is correct, run a command to display all the database tables, again using the ejabberd MariaDB user, and the output should look something like that:

echo "SHOW TABLES;" | mysql -h localhost -D ejabberd -u ejabberd -p --table
Enter password: 
| Tables_in_ejabberd      |
| archive                 |
| archive_prefs           |
| bosh                    |
| caps_features           |
| last                    |
| mix_channel             |
| mix_pam                 |
| mix_participant         |
| mix_subscription        |
| motd                    |
| mqtt_pub                |

Configuring ejabberd for MariaDB

Now that our MariaDB tables are ready, we need to configure ejabberd to use this MySQL-compatible database. Edit your ejabberd.yml config and add the following settings, where password refers to the ejabberd MariaDB user:

sql_type: mysql
sql_server: "localhost"
sql_database: "ejabberd"
sql_username: "ejabberd"
sql_password: "password"

Migrating Mnesia data to MariaDB database

At this point, if you restart your ejabberd, it won’t be using MariaDB just yet. Let’s first migrate Mnesia data into our new SQL database using ejabberdctl – we first export the data into a mnesia.sql file, and then we import it into the MariaDB database:

cd /opt/ejabberd-21.01/bin/
./ejabberdctl export2sql /tmp/mnesia.sql
mysql -h localhost -D ejabberd -u ejabberd -p < /tmp/mnesia.sql
rm /tmp/mnesia.sql

It’s a good practice to remove the /tmp/mnesia.sql after we are done with it. Now, add default_db: sql and auth_method: sql to your ejabberd.yml configuration file:

default_db: sql
auth_method: sql

sql_type: mysql
sql_server: "localhost"
sql_database: "ejabberd"
sql_username: "ejabberd"
sql_password: "password"

Then, restart your ejabberd instance – it will now use the MariaDB database! Please note that the Mnesia database will still be started up and used for non-persistent data and clustering.

In this ejabberd tutorial series:

Photo by Amy Asher on Unsplash

Let us know what you think 💬

9 thoughts on “Install and configure MariaDB with ejabberd

  1. Very well done!
    This article let me switch from Mnesia DB to MariaDB without any hassles.
    This former article ( gives different information and I was
    not able to succeed with the instructions given there.

    Chapeau, Martin!

    One short question: after migrating the data is there any way to delete the (duplicate) data from Mnesia DB, something like restoring to a virgin (clean) state?

    • To delete content from the Mnesia tables, there is a command called delete_mnesia. but it doesn’t work for me right now

      Alternative: the page in ejabberd WebAdmin -> Nodes -> your node -> Database shows the Mnesia tables and their size, and lets you perform actions with them, like deleting content and even delete some mnesia tables, as the modules you configured no longer need them.

      Of course, it’s highly recommended first of all to backup the mnesia database, just in case you make some mistake, or there is any other problem in ejabberd.

      • Thank you!
        Well, deleting tables is for sure not necessary (dangerous?), but I deleted the content of the “archive_msg” table which made the database size shrink by 98 %! I am pretty satisfied ;)

    • I double checked and indeed it is needed. On a fresh install the default value of “auth_method” is “mnesia”, and it is no explicitly defined in the config. To now fully use auth through the sql, you need to define “auth_method: sql” as you stated. I will update the tutorial, thanks.

  2. Question:

    ./ejabberdctl export2sql /tmp/mnesia.sql
    Failed RPC connection to the node ejabberd@localhost: timeout

    What ist that?

    • Looks like your node is down. You should have it running in the background prior running ejabberdctl.

  3. Hi
    i tried your settings. Users are saved in database but persistent rooms are not saved in database. my settings

    db_type: sql
    – allow
    – allow: admin
    access_create: muc_create
    access_persistent: muc_create
    – allow
    allow_subscription: true # enable MucSub
    mam: true
    members_only: true
    persistent: true
    I can see rooms in web panel.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.