Upgrading Your Home Assistant Database to MariaDB: The Definitive 2026 Guide

Last updated on January 22, 2026

If you’ve been using Home Assistant for a while, your system has likely grown exponentially. More devices, more automations, and most importantly, more data. The default SQLite database is fantastic for getting started, but as your smart home gets more complex, it can become a serious performance bottleneck. That’s why in this definitive 2026 guide, I’m going to show you how to set up Home Assistant with MariaDB—a crucial upgrade to supercharge your system’s performance and reliability.

Why Ditch SQLite for MariaDB in Home Assistant?

Making the switch isn’t just for kicks; the long-term benefits are a game-changer. Home Assistant uses a core component called the Recorder to save the state history of all your entities. By default, it writes everything to a single SQLite file (home-assistant_v2.db). This is simple and effective at first, but it has its limits.

By migrating from SQLite to the Home Assistant MariaDB setup, you’re graduating from a single-file system to a robust, high-performance relational database engine. In real-world terms, this means a snappier UI, especially when loading history graphs and Lovelace cards, and a massive boost in overall system stability.

To make it crystal clear, here’s a head-to-head comparison:

SQLite vs. MariaDB: A Head-to-Head Comparison for Home Assistant in 2026

Step-by-Step Installation and Setup Guide

The process is surprisingly straightforward, thanks to the Home Assistant Add-on system. We’ll break it down into three simple phases: install the Add-on, configure it securely, and link it to Home Assistant.

1. Installing the MariaDB Add-on

First, log into your Home Assistant instance and navigate to Settings > Add-ons > Add-on Store. In the search bar, type “MariaDB” and select the official add-on.

Hit “Install” and wait for the process to complete. Hold on, though—don’t start it just yet!

2. Securing Your Add-on Configuration

Before firing up the service, it’s absolutely critical to set a strong password. Go to the “Configuration” tab of the MariaDB Add-on.

You’ll see a YAML configuration block. The defaults work, but we need to change the password, which is set to null.

Pro Tip for 2026: Instead of typing your password directly here, we’re going to use the secrets.yaml file. This prevents exposing sensitive info in your backups or if you share your configuration online. If you’re not familiar with it, check out the official Home Assistant documentation on secrets.

Open your secrets.yaml file (using the “File editor” or “Visual Studio Code” Add-on) and add a line like this, replacing “MySuperSecretPassword123” with your own:

mariadb_password: MySuperSecretPassword123

Now, go back to the MariaDB Add-on configuration and update it to look exactly like this:

databases:
  - homeassistant
logins:
  - username: homeassistant
    password: '!secret mariadb_password'
rights:
  - username: homeassistant
    database: homeassistant

Save your changes. Now you can go back to the “Info” tab and start the Add-on. I also recommend toggling on “Watchdog” so it restarts automatically if it ever crashes.

3. Connecting Home Assistant to MariaDB

With the add-on running, the final step is to tell Home Assistant to actually use this new database. This is handled in your main configuration.yaml file.

Add the following code block to your configuration.yaml:

recorder:
  db_url: !secret mariadb_connection_string

Next, hop back over to your secrets.yaml file and add this new line:

mariadb_connection_string: mysql://homeassistant:!secret mariadb_password@core-mariadb/homeassistant?charset=utf8mb4

Notice how we’re reusing the mariadb_password secret we created earlier. This centralizes your password management and makes future maintenance a breeze.

Once you’ve saved both files, go to Developer Tools > YAML and click “Check Configuration.” If everything looks good, restart Home Assistant.

Heads-up: The first restart after this change can take significantly longer than usual. Home Assistant is busy building the new database structure from scratch. Be patient and let it do its thing.

Bonus: Create a Sensor to Track Database Size

Once you’re up and running, it’s super useful to have a sensor to monitor your database growth. We can do this easily with an SQL sensor.

Add the following code to your sensor configuration file (or directly in configuration.yaml under the sensor: key):

- platform: sql
  db_url: !secret mariadb_connection_string
  queries:
    - name: "MariaDB Size"
      query: 'SELECT table_schema "database", Round(Sum(data_length + index_length) / 1048576, 2) "value" FROM information_schema.tables WHERE table_schema="homeassistant" GROUP BY table_schema;'
      column: 'value'
      unit_of_measurement: MB

After a quick restart, you’ll have a new entity, sensor.mariadb_size, showing the current database size in megabytes.

Basic Maintenance to Keep Your Database Lean and Mean

Just because you have a powerful database doesn’t mean you can forget about it. To optimize your Home Assistant MariaDB setup and prevent uncontrolled growth, regular purging is key.

You can do this manually from Developer Tools > Services. The two key services you need to know are:

• recorder.purge: Deletes history data older than a specified number of days. For example, to keep only the last 15 days of data, you would call the service with keep_days: 15.
• recorder.purge_entities: Lets you wipe the entire history for specific entities. This is a lifesaver if a faulty sensor goes haywire and floods your database with junk data.

I highly recommend creating a weekly automation that runs the recorder.purge service to keep your system snappy. For a deeper dive into keeping your system optimized, check out our guide on how to fix a slow Home Assistant instance for good.

Common Troubleshooting & FAQs

Here are answers to the most common questions I get when people make this switch.

Q: I restarted and all my history is gone. Is that normal?
A: Yep, 100% normal and expected. By setting up MariaDB, you’re telling Home Assistant to start writing to a brand new, empty database. Your old history is still safe in the home-assistant_v2.db file, but the system will no longer read from it. Migrating the old data is a much more complex process not covered in this guide.

Q: Home Assistant won’t start, or I’m seeing ‘recorder’ errors in the logs.
A: 99% of the time, this is a password mismatch. Double-check that the password in your secrets.yaml is exactly the same one referenced in your MariaDB Add-on configuration. Also, check the logs of the MariaDB Add-on itself to see if it’s having trouble starting up.

Q: How do I switch back to SQLite if something goes wrong?
A: Easy peasy. Just delete or comment out the entire recorder: block from your configuration.yaml (by adding a # at the beginning of each line) and restart Home Assistant. The system will automatically revert to using the default SQLite file.