NetBird 0.82 ya no admite MySQL: cómo migrar a PostgreSQL antes de actualizar con Docker

Si tu servidor NetBird 0.82 no arranca y el registro dice the MySQL store engine is no longer supported, vuelve a la imagen 0.81.5, migra los datos a PostgreSQL con netbird-mysql-migrate de la 0.81.5 y solo después actualiza fijando la etiqueta 0.82.0. El orden importa porque la 0.82 eliminó MySQL y también dejó de publicar la herramienta que lo migra. Lo reproduje el 2 de noviembre de 2026 en Linux arm64 con Docker 29.5.2, MySQL 8.4.13 y PostgreSQL 17.11, sobre el servidor combinado netbirdio/netbird-server. Tienes la versión en inglés de esta guía.

Puntos clave

• NetBird 0.82.0 (29 de octubre de 2026) eliminó el motor MySQL del servidor de gestión, solo 14 días después de marcarlo como obsoleto en la 0.81.0.
• El 2 de noviembre de 2026 la etiqueta latest de netbirdio/netbird-server y de netbirdio/management ya apunta a la 0.82.0: un docker compose pull te deja sin servidor.
• La 0.82.0 se para antes de tocar la base de datos, así que volver a 0.81.5 arranca sin pérdidas.
• netbird-mysql-migrate solo existe en las versiones 0.81.x; en mi prueba copió 19 filas de 39 tablas, 11 eventos de actividad y 6 filas del proveedor de identidad.
• Tras la migración, la 0.82.0 sobre PostgreSQL devolvió el mismo peer, los 2 usuarios, los 4 grupos, la ruta y la clave de alta.

¿Qué significa el error the MySQL store engine is no longer supported?

Significa que tu servidor de gestión está configurado con engine: "mysql" y la versión que acabas de arrancar ya no tiene ese motor. NetBird es una red privada virtual (VPN) en malla sobre WireGuard, y su servidor de gestión guarda peers, usuarios, grupos y políticas en SQLite, PostgreSQL o, hasta la 0.81, MySQL. Este es el final del registro que obtuve al cambiar la imagen de 0.81.5 a latest:

INFO combined/cmd/root.go:730:   Store engine: mysql
INFO combined/cmd/root.go:341: Signal server created
FATL management/internals/server/boot.go:101: failed to open database
connection: the MySQL store engine is no longer supported. Please refer
to the documentation for migrating to PostgreSQL:
https://docs.netbird.io/selfhosted/migration/mysql-to-postgresql

En tu terminal la línea FATL sale entera; aquí la he partido para que quepa. El contenedor termina con código 1. Si tu servicio tiene restart: unless-stopped, como el compose oficial, Docker lo relanza una y otra vez con el mismo mensaje: en mi prueba sumó 9 reinicios en 30 s. El texto sale tal cual del código fuente de la 0.82.0 (management/server/store/store.go), que comparten la imagen combinada y la antigua netbirdio/management.

¿A quién afecta y qué versiones lo provocan?

Solo afecta a quien configuró MySQL a mano, porque el instalador oficial genera engine: "sqlite" y la otra opción documentada es PostgreSQL. Comprueba tu motor en el registro del contenedor antes de tocar nada:

docker logs netbird-server 2>&1 | grep -i "store engine"

Si ves Store engine: mysql o using MySQL store engine, sigue leyendo. Con la 0.81.5 sobre MySQL el registro no muestra ningún aviso de obsolescencia: el único rastro es esa línea INFO. Estas son las fechas que comprobé en GitHub y en Docker Hub:

La nota de la versión 0.82.0^[1] lo deja claro: "The netbird-mysql-migrate tool is no longer part of the release, so run the migration while still on 0.81.x, with the tool from the v0.81.5 release, then upgrade."

Arreglo inmediato: vuelve a la 0.81.5

La 0.82.0 falla al abrir la conexión, antes de aplicar ninguna migración de esquema, así que tu base de datos MySQL queda intacta. Fija la etiqueta en tu compose y vuelve a levantar el servicio:

  netbird-server:
    image: netbirdio/netbird-server:0.81.5

Después de docker compose up -d netbird-server, mi servidor volvió a registrar management server version 0.81.5 y la API devolvió los mismos datos que antes del intento. Si usas la arquitectura antigua, con gestión, señalización y relé en contenedores separados, la etiqueta que fijas es la de netbirdio/management. Deja la etiqueta fija también después de migrar: latest es justo lo que te ha traído hasta aquí.

Cómo migrar de MySQL a PostgreSQL con netbird-mysql-migrate

La migración copia el almacén de gestión de MySQL y los dos ficheros SQLite del volumen (events.db con la actividad e idp.db con el proveedor de identidad integrado) a una base PostgreSQL vacía. La herramienta solo lee MySQL, así que tu instalación anterior sigue siendo la vuelta atrás. Repetí estos pasos con los comandos exactos de la guía en una segunda instalación limpia, y solo cambié los nombres del contenedor y de la red. Estos son los pasos en orden:

1. Añade PostgreSQL a tu compose y arráncalo vacío
2. Para el servidor y haz copia del volumen y de MySQL
3. Descarga netbird-mysql-migrate 0.81.5 y ejecútalo
4. Cambia config.yaml a PostgreSQL y arranca la 0.82.0

Paso 1: añade un servicio PostgreSQL

Añade este servicio junto a los que ya tienes, con su propio volumen para que los datos sobrevivan a un down. Yo usé PostgreSQL 17; si aún no lo has montado nunca, la guía para instalar PostgreSQL con Docker explica las variables:

  postgres:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: netbird
      POSTGRES_PASSWORD: tu_password_postgres
      POSTGRES_DB: netbird
    volumes:
      - netbird_pg:/var/lib/postgresql/data

Declara también netbird_pg: en la sección volumes: del final y ejecuta docker compose up -d postgres. La base tiene que estar vacía: la herramienta se niega a escribir sobre datos de NetBird.

Paso 2: para el servidor y haz copia de seguridad

Para el servidor de gestión antes de copiar, para que nadie escriba en MySQL mientras migras. Después copia el volumen y vuelca MySQL:

docker compose stop netbird-server
mkdir -m 700 backup
docker cp netbird-server:/var/lib/netbird backup/netbird-data
docker compose exec -T mysql mysqldump --no-tablespaces \
  -unetbird -p'tu_password_mysql' netbird > backup/netbird-mysql.sql

docker cp funciona con el contenedor parado. Mi volcado ocupó 54 923 bytes para una instalación de prueba con 1 peer. La opción --no-tablespaces evita el error de privilegio PROCESS que la guía oficial describe para el usuario de NetBird. La copia contiene hashes de contraseñas, así que guárdala con permisos 700.

Paso 3: ejecuta netbird-mysql-migrate 0.81.5

La herramienta es un binario para Linux (amd64, arm64 y arm), no una imagen, y está en los recursos de la versión 0.81.5 en GitHub. Descárgala con la arquitectura de tu servidor:

V=0.81.5; A=linux_arm64   # o linux_amd64
F=netbird-mysql-migrate_${V}_$A.tar.gz
U=https://github.com/netbirdio/netbird/releases/download
mkdir tool && cd tool
curl -LO "$U/v$V/$F" && tar xzf "$F" && cd ..

Mi MySQL no publica su puerto fuera de Docker, así que ejecuté el binario dentro de un contenedor de postgres:17 conectado a la red del compose. Cambia netbird_default por la red de tu proyecto (docker network ls):

MY='netbird:tu_password_mysql@tcp(mysql:3306)/netbird?parseTime=True'
PG='host=postgres dbname=netbird user=netbird sslmode=disable'
PG="$PG password=tu_password_postgres"
docker run --rm --network netbird_default \
  -v "$PWD/tool:/tool:ro" -v "$PWD/backup/netbird-data:/data:ro" \
  postgres:17 /tool/netbird-mysql-migrate \
  --mysql-dsn "$MY" --postgres-dsn "$PG" \
  --events-db /data/events.db --auth-db /data/idp.db

La salida fue de cuatro líneas:

management: 19 rows from 39 tables
activity: 11 rows from 2 tables
auth: 6 rows from 12 tables
Done. Point the store, activity and auth store settings at Postgres
before starting the server.

Si tu servidor no corría en UTC, añade --mysql-timezone Europe/Madrid o la zona que usara. sslmode=disable es aceptable aquí porque PostgreSQL está en la misma red de Docker.

Paso 4: apunta config.yaml a PostgreSQL y arranca la 0.82.0

Cambia los tres almacenes, no solo el principal, y conserva intacta la encryptionKey: sin ella el servidor no puede descifrar los datos copiados. Esta es la sección store de mi config.yaml después del cambio:

  store:
    engine: "postgres"
    dsn: &pg >-
      host=postgres port=5432 dbname=netbird user=netbird
      password=tu_password_postgres sslmode=disable
    encryptionKey: "la_clave_que_ya_tenias"
  activityStore:
    engine: "postgres"
    dsn: *pg
  authStore:
    engine: "postgres"
    dsn: *pg

El ancla YAML &pg reutiliza la misma cadena de conexión (DSN) en los tres almacenes, y >- la une en una sola línea. Borra cualquier variable NB_STORE_ENGINE_MYSQL_DSN o NETBIRD_STORE_ENGINE_MYSQL_DSN del compose, cambia la imagen a netbirdio/netbird-server:0.82.0 y ejecuta docker compose up -d netbird-server. En la arquitectura antigua con management.json, la guía oficial cambia StoreConfig.Engine a postgres y usa las variables NETBIRD_STORE_ENGINE_POSTGRES_DSN, NB_ACTIVITY_EVENT_STORE_ENGINE y NB_ACTIVITY_EVENT_POSTGRES_DSN; esa variante no la probé.

Cómo comprobar que la migración salió bien

El registro de arranque tiene que nombrar PostgreSQL en los almacenes y terminar con la versión nueva. En el mío aparecieron using Postgres store engine, using postgres as activity event store engine y management server version 0.82.0.

Después compara la API con lo que tenías en MySQL. Usé un token de acceso personal (PAT) creado antes de migrar, y siguió valiendo después, lo que ya prueba que el almacén cifrado se leyó bien. Estos son los recuentos antes y después:

GET /api/instance devolvió {"setup_required":false}, así que el proveedor de identidad integrado encontró a su administrador en PostgreSQL. En la tabla password estaban los dos correos de los usuarios locales. Con la 0.82.0 en marcha, la base tenía 54 tablas y ocupaba 10 MB.

Dificultades con las que me he topado

Tres comportamientos que no esperaba, todos reproducidos en el laboratorio:

• Repetir la migración falla: con datos ya copiados, el segundo intento termina con migration failed: management: table accounts: target already holds data. Para repetir, vacía antes la base de PostgreSQL
• Volver a MySQL pierde lo nuevo: la guía oficial avisa de que los cambios hechos sobre PostgreSQL no se copian de vuelta a MySQL, así que tu volcado es un punto de retorno, no una réplica
• Un up sin etiqueta te devuelve a la versión anterior: si la etiqueta sale de una variable con valor por defecto, un docker compose up -d olvidadizo arranca la otra versión. A mí me levantó la 0.81.5 sobre PostgreSQL ya migrado; arrancó, pero no es un estado que quieras dejar

Otros cambios de la 0.82 que conviene revisar

La 0.82.0 trae dos avisos más para quien autoaloja NetBird. Rosenpass, la capa poscuántica opcional, pasa a obsoleto: sigue funcionando, pero --enable-rosenpass y --rosenpass-permissive desaparecen de la ayuda y avisan al usarse. La opción --admin-url del cliente se ignora porque no funcionaba.

Si estás eligiendo entre redes en malla, montar Headscale con Docker es la alternativa autoalojada a Tailscale. Si lo que necesitas es una VPN de punto de acceso, WireGuard con wg-easy en Docker no necesita base de datos.

Preguntas frecuentes

¿Puedo quedarme en NetBird 0.81 con MySQL?

Sí, el servidor 0.81.5 funciona sobre MySQL, pero no recibirá las correcciones de la 0.82 en adelante. Fija la etiqueta 0.81.5 y planifica la migración: la herramienta de migración solo está en las versiones 0.81.x.

¿Me afecta si uso SQLite?

No. SQLite es el motor por defecto del instalador y la 0.82.0 lo sigue admitiendo, igual que PostgreSQL. Comprueba la línea Store engine del registro para salir de dudas.

¿Tengo que migrar también los clientes?

No. La migración solo toca el servidor de gestión, y los peers no guardan nada de MySQL. En mi prueba, el peer registrado con la 0.81.5 conservó en PostgreSQL su nombre, su IP y su versión de cliente.

Conclusión

La 0.82.0 convierte un MySQL obsoleto en un servidor que no arranca, y la herramienta de migración ya no viene en esa versión. Vuelve a la 0.81.5, migra con su netbird-mysql-migrate, cambia los tres almacenes en config.yaml y arranca la 0.82.0 con la etiqueta fija. Compara después los recuentos de la API con los de antes y guarda el volcado de MySQL hasta que estés seguro.

Fuentes: [1] NetBird, notas de la versión 0.82.0^[1], [2] NetBird, notas de la versión 0.81.0^[2], [3] NetBird, versión 0.81.5 con netbird-mysql-migrate^[3], [4] NetBird, guía de migración de MySQL a PostgreSQL^[4], [5] Docker Hub, etiquetas de netbirdio/netbird-server^[5], [6] NetBird, código del almacén en la 0.82.0^[6].

Fuentes

1. nota de la versión 0.82.0
2. NetBird, notas de la versión 0.81.0
3. NetBird, versión 0.81.5 con netbird-mysql-migrate
4. NetBird, guía de migración de MySQL a PostgreSQL
5. Docker Hub, etiquetas de netbirdio/netbird-server
6. NetBird, código del almacén en la 0.82.0