Cómo migrar a dbt v2 sin romper producción

dbt v2 llegó a estable después de 18 meses de trabajo y con él una reescritura completa en Rust, un compilador de SQL que antes no existía y un cambio que sí te afecta el primer día: los adaptadores ya no se instalan por separado. Esta guía es la ruta para migrar a dbt v2 sin interrumpir lo que ya corre en producción, con los pasos que documenta dbt Labs y los puntos donde conviene parar a comprobar.

Antes de tocar nada: entiende qué cambió de nombre

Lo primero que confunde, porque es un cambio de nombre y no de código. El motor que se llamaba dbt Fusion ahora se llama simplemente dbt, y lo que iba a ser dbt Core v2 se llama dbt OSS. dbt Labs lo dice explícitamente: para quien ya usaba la beta, es puramente un cambio de nombre — no cambia el código disponible ni la licencia.

La diferencia entre las dos distribuciones no es el lenguaje: leen exactamente los mismos archivos de proyecto, así que puedes moverte entre ellas sin tocar tu lógica de negocio. Lo que cambia es qué pueden hacer con esos archivos:

• dbt OSS es 100% Apache 2.0 y trae todo lo necesario para ejecutar un proyecto, más las mejoras de v2: los docs nuevos, la velocidad y el Information Schema.
• dbt añade lo avanzado en local —comprensión de SQL, linting, soporte de LSP— y las funciones de pago por asiento.

La recomendación de dbt Labs: usa dbt OSS solo si necesitas un binario Apache 2.0 o vas a escribir código propio para cambiar cómo funciona dbt. Para todo lo demás, dbt.

El cambio que rompe tu instalación

Aquí está lo que va a fallar en tu primer intento. Los adaptadores ya no se instalan aparte:

# antes
pip install dbt-postgres

# ahora
pip install dbt

El driver adecuado se descarga solo según el destino que tenga tu proyecto. Y si trabajas en un entorno sin salida a internet, la salida es instalar el paquete del adaptador directamente, que arrastra dbt entero y el driver de ADBC:

pip install dbt-snowflake

Hay una red de seguridad temporal: pip install dbt-core sigue funcionando e instala dbt OSS. Pero conviene migrar a un nombre explícito, porque esa compatibilidad es un puente, no el destino.

Cómo migrar a dbt v2, paso a paso

No saltes directo a v2 aunque tu proyecto sea pequeño. La ruta que documenta dbt Labs pasa por una versión intermedia, y tiene motivo: es la que te deja probar el analizador nuevo sin tocar producción.

Primero, sube a dbt Core 1.12. Esa versión trae el flag --use-v2-parser, que analiza tu proyecto con el analizador de la v2 sin cambiar nada más. Es el ensayo: si tu proyecto pasa por ahí, va a pasar por la v2.

dbt build --use-v2-parser

Segundo, arregla lo que salga. Lo que el analizador nuevo rechace, lo va a rechazar la v2. Hacerlo aquí, con la instalación vieja todavía en su sitio, significa que si algo se tuerce vuelves atrás sin consecuencias.

Tercero, usa las herramientas de migración automática. dbt Labs mantiene dbt-autofix y un conjunto de agent skills para migrar proyectos, pensados precisamente para este salto.

Cuarto, sustituye tu instalación por la distribución v2 que hayas elegido. Aquí es donde el cambio de instalación del apartado anterior entra en juego.

Y una advertencia que conviene leer antes de planificar la fecha: algunos adaptadores no están del todo maduros todavía. dbt Labs recomienda comprobar el estado del tuyo en su documentación antes de planear el salto. Si el tuyo está verde, migra; si no, espera — porque el soporte de la 1.x no se acaba mañana.

Qué ganas cuando terminas

El motivo de la reescritura. Los números que publica dbt Labs, medidos en su proyecto de referencia de 10.000 nodos: compilar pasó de 70 segundos a 17. En proyectos grandes, lo que tardaba 20 minutos en analizarse ahora tarda menos de uno. Y en proyectos de tamaño normal, la compilación es al menos el doble de rápida.

Lo interesante no es solo la velocidad, sino lo que la hace posible. dbt v2 añade un compilador de SQL, que antes no tenía: construye un plan lógico de la consulta emulando el comportamiento de tu base de datos, teniendo en cuenta las fuentes, las UDF y las funciones propias de tu motor. Si no consigue producir ese plan, hay algo mal en la consulta.

# el análisis estático viene en modo `baseline` por defecto
# subir a `strict` da más funciones y garantías
dbt build

Y ahí está la parte que tu almacén de datos no puede hacer solo: tu almacén evalúa la consulta que tiene delante en ese momento; dbt sabe que quitar una columna, aunque la consulta siga siendo válida, rompería cuatro modelos aguas abajo.

El resto de lo nuevo:

• dbt State, que decide qué construir, qué saltar y qué clonar, y que se activa con dbt build --manage-state. Los clientes que lo han probado reportan ahorros de entre el 25% y el 59% del coste del almacén.
• El Information Schema, que describe el proyecto entero como archivos Parquet —hasta diez veces más pequeños que un manifest.json y legibles por partes— y se consulta con dbt show --info.
• Los docs nuevos, construidos sobre ese Information Schema y con DuckDB en WASM dentro para consultar el metadata a demanda.

Errores frecuentes al migrar

• pip install dbt-postgres no da lo que esperas. Ya no hace falta el paquete del adaptador, y en entornos sin internet sí hace falta pero por otro motivo. Revisa cuál de los dos casos es el tuyo antes de tocar el pipeline de CI.
• Migrar sin pasar por 1.12. Si vas directo a v2, el analizador nuevo te tira los errores encima de producción y sin red. El paso intermedio existe para eso.
• Dar por hecho que tu adaptador está listo. Compruébalo. Es el riesgo real de la migración, más que cualquier cambio de sintaxis: el lenguaje es el mismo entre distribuciones, pero la madurez del adaptador no.
• Confundir el cambio de nombre con un cambio de producto. Si ya usabas la beta, no hay nada que hacer más allá de renombrar lo que tienes en la cabeza.

Otra novedad de datos de este mes: si además mueves texto dentro de Postgres, mira cómo añadir búsqueda de texto completo con TIN.

Fuentes: el anuncio de dbt v2 en el blog de dbt y la guía que compara dbt con dbt OSS, de donde salen la ruta de migración y el cambio de instalación. Las herramientas de migración están en dbt-autofix.