--- title: "Cómo instalar dbt con PostgreSQL en Ubuntu 24.04" description: "Instala dbt Core con el adaptador de PostgreSQL en Ubuntu 24.04, crea un proyecto con seeds, modelos y tests de calidad, y genera su documentación." category: "Ingeniería de Datos" language: es source: https://cubepath.com/es/docs/ingeniería-de-datos/instalacion-de-dbt-transformacion-de-datos updated: 2026-09-25 --- # Cómo instalar dbt con PostgreSQL en Ubuntu 24.04 dbt (data build tool) transforma los datos que ya están en tu base de datos o data warehouse mediante consultas SQL versionadas, con dependencias entre modelos, tests de calidad y documentación generada automáticamente. En este tutorial instalarás dbt Core con el adaptador de PostgreSQL en Ubuntu 24.04, crearás un proyecto con datos de ejemplo, construirás una capa de staging y una tabla agregada, añadirás tests y generarás la documentación del linaje. ## Requisitos previos Para seguir esta guía necesitas: - Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 1 GB de RAM. - Un usuario no root con privilegios `sudo`. - Conocimientos básicos de SQL. En esta guía instalarás PostgreSQL en el mismo servidor para tener un entorno completo. Si ya dispones de un PostgreSQL remoto, sáltate el paso 1 y usa sus datos de conexión en el paso 4. ## Paso 1: Instalar PostgreSQL y crear la base de datos dbt no almacena datos: ejecuta SQL contra una base de datos existente. Instala PostgreSQL desde los repositorios de Ubuntu: ```bash sudo apt update sudo apt install -y postgresql ``` Crea un rol para dbt y una base de datos de la que sea propietario. Sustituye `your_strong_password` por una contraseña segura: ```bash sudo -u postgres psql -c "CREATE ROLE dbt_user WITH LOGIN PASSWORD 'your_strong_password';" sudo -u postgres createdb -O dbt_user analitica ``` Comprueba que puedes conectarte por TCP con ese usuario, igual que hará dbt. `psql` te pedirá la contraseña: ```bash psql -h localhost -U dbt_user -d analitica -c 'SELECT current_user, current_database();' ``` ```output current_user | current_database --------------+------------------ dbt_user | analitica (1 row) ``` ## Paso 2: Instalar dbt en un entorno virtual Instalar dbt con `pip` dentro de un entorno virtual evita conflictos con los paquetes de Python del sistema, que Ubuntu 24.04 protege frente a `pip install` global. Instala el módulo `venv`: ```bash sudo apt install -y python3-venv ``` Crea el entorno, actívalo e instala el adaptador `dbt-postgres`, que trae `dbt-core` como dependencia: ```bash python3 -m venv ~/dbt-venv source ~/dbt-venv/bin/activate pip install --upgrade pip pip install dbt-postgres ``` Comprueba la instalación: ```bash dbt --version ``` ```output Core: - installed: 1.12.5 - latest: 1.12.5 - Up to date! Plugins: - postgres: 1.11.0 - Up to date! ``` Las versiones pueden ser más recientes. Recuerda ejecutar `source ~/dbt-venv/bin/activate` en cada sesión nueva antes de usar `dbt`. ## Paso 3: Crear el proyecto Inicializa un proyecto llamado `tienda`. La opción `--skip-profile-setup` evita el asistente interactivo; configurarás la conexión a mano en el paso siguiente: ```bash cd ~ dbt init tienda --skip-profile-setup cd ~/tienda ``` `dbt init` crea la estructura del proyecto (`models/`, `seeds/`, `tests/`, `macros/`, `snapshots/`, `analyses/`) y unos modelos de ejemplo que no necesitas. Elimínalos: ```bash rm -rf models/example ``` Abre el archivo de configuración del proyecto: ```bash nano dbt_project.yml ``` Al final del archivo hay un bloque `models:` que hace referencia a `example`. Sustitúyelo por este, que materializa la capa de staging como vistas y la capa de marts como tablas: ```yaml models: tienda: staging: +materialized: view marts: +materialized: table ``` Comprueba también que la línea `profile:` del mismo archivo vale `'tienda'`. dbt usará ese nombre para buscar la conexión. ## Paso 4: Configurar la conexión en profiles.yml Las credenciales viven fuera del proyecto, en `~/.dbt/profiles.yml`, para que nunca acaben en el repositorio. Crea el archivo: ```bash mkdir -p ~/.dbt nano ~/.dbt/profiles.yml ``` ```yaml tienda: target: dev outputs: dev: type: postgres host: localhost port: 5432 user: dbt_user password: "{{ env_var('DBT_PASSWORD') }}" dbname: analitica schema: dbt_dev threads: 4 ``` La contraseña se lee de la variable de entorno `DBT_PASSWORD` en lugar de escribirse en claro. `schema` es el esquema donde dbt creará las vistas y tablas del entorno `dev`. Restringe los permisos del archivo y exporta la variable: ```bash chmod 600 ~/.dbt/profiles.yml export DBT_PASSWORD='your_strong_password' ``` Comprueba la configuración y la conexión: ```bash dbt debug ``` ```output ... Connection test: [OK connection ok] All checks passed! ``` ## Paso 5: Cargar datos de ejemplo con seeds Los seeds son ficheros CSV pequeños que dbt carga como tablas. Sirven para datos de referencia y, en este caso, para tener datos con los que trabajar. Crea el fichero: ```bash nano seeds/ventas_raw.csv ``` ```text id_venta,cliente_email,importe,fecha_venta,estado 1,Ana@Example.com ,120.50,2026-01-15,pagada 2,luis@example.com,35.00,2026-01-20,completada 3,ana@example.com,80.00,2026-02-03,cancelada 4,marta@example.com,210.99,2026-02-11,pagada 5,luis@example.com,15.25,2026-03-02,pendiente ``` Carga el seed en la base de datos: ```bash dbt seed ``` ```output ... 1 of 1 OK loaded seed file dbt_dev.ventas_raw ........................ [INSERT 5 in 0.08s] ... Completed successfully ``` ## Paso 6: Crear los modelos Un modelo es un fichero `.sql` con una sentencia `SELECT`. dbt la envuelve en el `CREATE VIEW` o `CREATE TABLE` correspondiente y resuelve el orden de ejecución a partir de las llamadas a `ref()`. Crea los directorios de las dos capas: ```bash mkdir -p models/staging models/marts ``` El modelo de staging limpia y normaliza los datos en bruto: ```bash nano models/staging/stg_ventas.sql ``` ```sql select id_venta::integer as id_venta, lower(trim(cliente_email)) as email_cliente, importe::numeric(10, 2) as importe, fecha_venta::date as fecha_venta, case when estado in ('completada', 'pagada') then 'completada' when estado = 'cancelada' then 'cancelada' else 'pendiente' end as estado from {{ ref('ventas_raw') }} ``` El modelo de marts agrega las ventas completadas por mes a partir del modelo de staging: ```bash nano models/marts/ventas_mensuales.sql ``` ```sql select date_trunc('month', fecha_venta)::date as mes, count(*) as num_ventas, sum(importe) as total_ventas, count(distinct email_cliente) as clientes_unicos from {{ ref('stg_ventas') }} where estado = 'completada' group by 1 ``` Ejecuta los modelos: ```bash dbt run ``` ```output ... 1 of 2 OK created sql view model dbt_dev.stg_ventas ................. [CREATE VIEW in 0.05s] 2 of 2 OK created sql table model dbt_dev.ventas_mensuales .......... [SELECT 2 in 0.04s] ... Completed successfully ``` Consulta el resultado directamente en PostgreSQL: ```bash psql -h localhost -U dbt_user -d analitica -c 'SELECT * FROM dbt_dev.ventas_mensuales ORDER BY mes;' ``` ```output mes | num_ventas | total_ventas | clientes_unicos ------------+------------+--------------+----------------- 2026-01-01 | 2 | 155.50 | 2 2026-02-01 | 1 | 210.99 | 1 (2 rows) ``` Observa que el email `Ana@Example.com ` del seed se ha normalizado y cuenta como el mismo cliente que `ana@example.com`. Para ejecutar solo una parte del proyecto, usa `--select`. Por ejemplo, `dbt run --select stg_ventas+` ejecuta `stg_ventas` y todos los modelos que dependen de él. ## Paso 7: Añadir tests de calidad de datos Los tests genéricos se declaran en ficheros YAML junto a los modelos. Cada test es una consulta que busca filas que incumplen la regla; si encuentra alguna, falla. Crea el fichero de propiedades de la capa de staging: ```bash nano models/staging/_staging.yml ``` ```yaml version: 2 models: - name: stg_ventas description: "Ventas limpiadas y normalizadas a partir del seed ventas_raw." columns: - name: id_venta description: "Identificador único de la venta." data_tests: - unique - not_null - name: estado data_tests: - accepted_values: arguments: values: ['completada', 'cancelada', 'pendiente'] - name: importe data_tests: - not_null ``` Para reglas propias, crea un test singular: una consulta en `tests/` que debe devolver cero filas. Este comprueba que no hay importes negativos: ```bash nano tests/assert_importe_no_negativo.sql ``` ```sql select * from {{ ref('stg_ventas') }} where importe < 0 ``` Ejecuta los tests: ```bash dbt test ``` ```output ... Done. PASS=5 WARN=0 ERROR=0 SKIP=0 NO-OP=0 TOTAL=5 ``` En el día a día conviene usar `dbt build`, que carga seeds, ejecuta modelos y lanza sus tests en orden de dependencias. Si un test de `stg_ventas` falla, los modelos que dependen de él se omiten: ```bash dbt build ``` ## Paso 8: Crear un modelo incremental Un modelo `table` se reconstruye entero en cada ejecución. Con tablas grandes es mejor un modelo incremental, que solo procesa las filas nuevas. Crea uno de ejemplo: ```bash nano models/marts/ventas_incremental.sql ``` ```sql {{ config( materialized='incremental', unique_key='id_venta' ) }} select id_venta, email_cliente, importe, fecha_venta, estado from {{ ref('stg_ventas') }} {% if is_incremental() %} where fecha_venta > (select max(fecha_venta) from {{ this }}) {% endif %} ``` La primera ejecución crea la tabla completa. En las siguientes, el bloque `is_incremental()` añade el filtro y dbt solo inserta o actualiza las ventas posteriores a la última cargada: ```bash dbt run --select ventas_incremental ``` Si cambias la lógica del modelo y necesitas reconstruirlo desde cero, añade `--full-refresh`. ## Paso 9: Generar y consultar la documentación dbt genera un sitio web estático con la descripción de cada modelo, sus columnas, sus tests y el grafo de dependencias: ```bash dbt docs generate dbt docs serve --port 8080 ``` El servidor escucha en `127.0.0.1`. Para verlo desde tu equipo, abre en otra terminal un túnel SSH (sustituye `your_user` y `your_server_ip`): ```bash ssh -L 8080:127.0.0.1:8080 your_user@your_server_ip ``` Visita `http://localhost:8080` y abre la vista **Lineage Graph** para ver cómo `ventas_raw` alimenta a `stg_ventas` y este a los modelos de marts. Detén el servidor con `Ctrl+C` cuando termines. ## Solución de problemas **`Env var required but not provided: 'DBT_PASSWORD'`.** La variable no está definida en la sesión actual. Vuelve a ejecutar `export DBT_PASSWORD='...'` o añádela a un fichero que cargues antes de usar dbt. **`Could not find profile named 'tienda'`.** El valor de `profile:` en `dbt_project.yml` no coincide con la clave de primer nivel de `~/.dbt/profiles.yml`. Ambos deben ser idénticos. **`password authentication failed for user "dbt_user"`.** La contraseña de `DBT_PASSWORD` no coincide con la del rol. Cámbiala con `sudo -u postgres psql -c "ALTER ROLE dbt_user PASSWORD 'your_strong_password';"`. **Error de SQL en un modelo.** Revisa el SQL que dbt ha generado realmente con `dbt compile --select nombre_modelo`; el resultado se guarda en `target/compiled/tienda/models/`. ## Conclusión Has instalado dbt Core con PostgreSQL en Ubuntu 24.04 y has construido un proyecto con seeds, modelos en capas, tests de calidad, un modelo incremental y documentación del linaje. Como siguientes pasos, guarda el proyecto en Git, programa `dbt build --target prod` con un temporizador de systemd o cron añadiendo un segundo target en `profiles.yml`, y ejecuta `dbt build` en tu CI en cada pull request para detectar cambios que rompan los datos antes de desplegarlos.