Configurar MariaDB Home Assistant: Guía Paso a Paso 2026

Actualizado el 22 de enero de 2026

Si llevas un tiempo usando Home Assistant, es muy probable que tu sistema haya crecido exponencialmente. Más dispositivos, más automatizaciones y, sobre todo, más datos. La base de datos por defecto, SQLite, es fantástica para empezar, pero a medida que tu hogar inteligente se vuelve más complejo, puede convertirse en un cuello de botella. Por eso, en esta guía definitiva de 2026, te enseñaré a configurar MariaDB en Home Assistant, una actualización crucial para optimizar el rendimiento y la fiabilidad de tu sistema.

¿Por qué migrar de SQLite a MariaDB en Home Assistant?

La decisión de cambiar la base de datos no es trivial, pero los beneficios a medio y largo plazo son innegables. Home Assistant utiliza un componente llamado Recorder para guardar el historial de estados de todas tus entidades. Por defecto, lo hace en un único archivo SQLite (home-assistant_v2.db). Esto es simple y efectivo, pero tiene sus límites.

Al migrar de SQLite a MariaDB en Home Assistant, estás pasando de un sistema de «archivo único» a un gestor de bases de datos relacional robusto y diseñado para un alto rendimiento. Esto se traduce en una interfaz más fluida, especialmente al cargar gráficos en el historial de Home Assistant o en las tarjetas de Lovelace, y una mayor estabilidad general del sistema.

Para que quede más claro, he preparado una tabla comparativa:

SQLite vs. MariaDB: Comparativa para Home Assistant en 2026

Característica	SQLite (Por defecto)	MariaDB (Recomendado)
Rendimiento	Bueno para sistemas pequeños. Puede ralentizarse con bases de datos grandes.	Excelente. Optimizado para consultas complejas y acceso concurrente.
Escalabilidad	Limitada. El rendimiento se degrada a medida que el archivo crece.	Alta. Capaz de gestionar terabytes de datos sin problemas.
Fiabilidad	Susceptible a corrupción si hay un apagón o reinicio inesperado.	Muy alta. Incluye mecanismos de recuperación ante fallos.
Acceso Externo	Complicado. Requiere acceso directo al archivo.	Sencillo. Permite conectar herramientas de análisis como Grafana.

Guía de Instalación y Configuración Paso a Paso

El proceso es bastante sencillo gracias al sistema de Add-ons de Home Assistant. Vamos a dividirlo en tres fases: instalar el Add-on, configurarlo de forma segura y enlazarlo con Home Assistant.

1. Instalación del Add-on de MariaDB

Primero, accede a tu instancia de Home Assistant y navega a Ajustes > Complementos > Tienda de complementos. En la barra de búsqueda, escribe «MariaDB» y selecciona el complemento oficial.

Pulsa en «Instalar» y espera a que el proceso finalice. ¡No lo inicies todavía!

2. Configuración Segura del Add-on

Antes de arrancar el servicio, es crucial establecer una contraseña segura. Ve a la pestaña «Configuración» del Add-on de MariaDB.

Verás una estructura de código YAML. La configuración por defecto es funcional, pero debemos cambiar la contraseña. Por defecto, el valor es null.

Práctica recomendada en 2026: En lugar de escribir tu contraseña directamente en este campo, usaremos el archivo secrets.yaml. Esto evita exponer información sensible en tus copias de seguridad o si compartes tu configuración. Si no sabes cómo funciona, te recomiendo leer mi guía sobre el uso y configuración del archivo secrets.yaml.

Abre tu archivo secrets.yaml (usando el Add-on «File editor» o «Visual Studio Code») y añade una línea como esta, reemplazando «MiContraseñaSuperSegura123» por la tuya:

mariadb_password: MiContraseñaSuperSegura123

Ahora, vuelve a la configuración del Add-on de MariaDB y modifícala para que quede así:

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

Guarda los cambios. Ahora sí, vuelve a la pestaña «Información» e inicia el Add-on. Puedes activar «Vigilante» para que se reinicie automáticamente si falla.

3. Conectar Home Assistant con MariaDB

Con el Add-on funcionando, el último paso es decirle a Home Assistant que use esta nueva base de datos. En las versiones actuales de Home Assistant, esto se gestiona principalmente desde el archivo configuration.yaml.

Añade el siguiente bloque de código a tu configuration.yaml:

recorder:
  db_url: !secret mariadb_connection_string

A continuación, vuelve a tu archivo secrets.yaml y añade esta nueva línea:

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

Fíjate cómo reutilizamos el secreto mariadb_password que creamos antes. Esto centraliza la gestión de contraseñas y hace el mantenimiento mucho más sencillo.

Una vez guardados ambos archivos, ve a Herramientas para desarrolladores > YAML y haz clic en «Comprobar configuración». Si todo está correcto, reinicia Home Assistant.

Nota importante: El primer reinicio puede tardar bastante más de lo habitual. Home Assistant está creando la nueva estructura de la base de datos desde cero. Ten paciencia.

Crear un Sensor para Medir el Tamaño de la Base de Datos

Una vez que todo funcione, es útil tener un sensor de tamaño de base de datos para monitorizar su crecimiento. Para ello, añadiremos un sensor de tipo SQL.

Añade el siguiente código en tu archivo de sensores (o en configuration.yaml bajo la clave sensor:):

- 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

Tras un reinicio, tendrás una nueva entidad sensor.mariadb_size que te mostrará el tamaño actual en MB.

Mantenimiento Básico para Optimizar tu Base de Datos

Tener una base de datos potente no significa que debamos descuidarla. Para optimizar la base de datos de Home Assistant y evitar que crezca sin control, es fundamental realizar purgas periódicas.

Puedes hacerlo manualmente desde Herramientas para desarrolladores > Servicios. Los dos servicios clave son:

recorder.purge: Borra datos del historial más antiguos que un número de días determinado. Por ejemplo, para mantener solo los últimos 15 días de datos, llamarías al servicio con keep_days: 15.
recorder.purge_entities: Permite borrar todo el historial de entidades específicas, muy útil si un sensor se ha vuelto loco y ha llenado la base de datos de datos inútiles.

Recomiendo crear una automatización que ejecute el servicio recorder.purge una vez a la semana para mantener el sistema ágil. Para un enfoque más detallado, puedes consultar mi guía sobre mantenimiento y limpieza en Home Assistant.

Solución de Problemas Comunes (FAQ)

Aquí resuelvo algunas de las dudas más frecuentes al realizar este cambio.

P: He reiniciado y he perdido todo mi historial. ¿Es normal?
R: Sí, es completamente normal. Al configurar MariaDB, Home Assistant empieza a escribir en una base de datos nueva y vacía. Tu historial antiguo sigue a salvo en el archivo home-assistant_v2.db, pero ya no será leído por el sistema. La migración de datos es un proceso complejo que no cubrimos en esta guía.

P: Home Assistant no arranca o veo errores del «recorder» en los registros.
R: La causa más común es un error en la contraseña. Asegúrate de que la contraseña en tu secrets.yaml es exactamente la misma que usaste en la configuración del Add-on de MariaDB. Revisa también los registros del propio Add-on para detectar posibles problemas al iniciarse.

P: ¿Cómo puedo volver a SQLite si algo sale mal?
R: Es muy sencillo. Simplemente elimina o comenta (añadiendo un # al principio de cada línea) el bloque recorder: de tu configuration.yaml y reinicia Home Assistant. El sistema volverá a usar y crear un archivo SQLite por defecto.