Conectar una API de Spring Boot a PostgreSQL mediante Docker te permite levantar una base de datos lista en segundos, sin instalaciones pesadas ni configuraciones manuales. Esta guía es para desarrolladores backend que ya tienen un proyecto Spring Boot estructurado y quieren dar el salto a datos persistentes con un entorno reproducible.

La idea es simple: en lugar de instalar PostgreSQL en tu máquina, lo ejecutas dentro de un contenedor limpio, portable y fácil de eliminar cuando ya no lo necesites. Y aquí viene lo interesante: desde Spring Boot 3.1 existe una integración con Docker Compose que automatiza casi todo el proceso.

¿Qué dependencias necesito para conectar Spring Boot a PostgreSQL?

Para que tu proyecto hable con la base de datos necesitas tres piezas que puedes agregar desde start.spring.io (Spring Initializr) [01:15].

• Spring Data JPA: te da la capa de acceso a datos y el manejo de entidades.
• PostgreSQL Driver: el conector específico para hablar con Postgres.
• Docker Compose Support: detecta si los contenedores están detenidos y los levanta automáticamente, así evitas correr comandos de Docker a mano.

¿Qué hace la dependencia de Docker Compose en Spring Boot? Disponible desde Spring Boot 3.1, hace que Spring detecte el archivo compose.yaml y administre el ciclo de vida del contenedor en entorno de desarrollo, levantándolo cuando arrancas la app.

Una vez agregadas, copia las tres líneas al build.gradle de tu proyecto y refresca Gradle para que descargue todo. La de Docker Compose solo aplica en desarrollo, lo cual acelera muchísimo el flujo diario.

¿Cómo configuro el archivo docker-compose.yaml para Postgres?

El propio Spring Initializr te genera un compose.yaml base, pero conviene ajustarlo. Crea el archivo en la raíz del proyecto, hermano de build.gradle, y nómbralo docker-compose.yaml [03:25].

Dentro de la configuración del servicio de Postgres conviene ajustar varias propiedades clave:

• restart: unless-stopped: reinicia el contenedor solo si falla, no cuando lo detienes a propósito.
• ports: 5432:5432: mapea el puerto del contenedor al mismo puerto local de Postgres.
• volumes: pgdata en data/postgres: persiste la información para que no se borre al reiniciar.
• environment: define el nombre de la base, el usuario y la contraseña.

En el ejemplo, la base se llama platziplaydb, el usuario es alejandro y la contraseña alejandro.platzi. Recuerda declarar el volumen también al final del archivo siguiendo el mismo patrón del nombre.

¿Para qué sirve un volumen en Docker Compose? Es un espacio persistente fuera del contenedor donde Postgres guarda sus datos. Si reinicias o eliminas el contenedor, la información sigue intacta.

¿Cómo le digo a Spring Boot que use esta base de datos?

La configuración va en src/main/resources, distribuida entre el archivo general (application.properties) y el de desarrollo (application-dev.properties) [05:40].

La propiedad spring.datasource.driver-class-name con el valor org.postgresql.Driver puedes ponerla en el archivo general, porque aplica a cualquier entorno. Lo específico va en el archivo de desarrollo.

¿Qué propiedades de datasource debo definir?

Estas son las tres líneas que conectan tu app con el contenedor:

• spring.datasource.url: jdbc:postgresql://localhost:5432/platziplaydb.
• spring.datasource.username: alejandro.
• spring.datasource.password: alejandro.platzi.

Nota cómo la URL usa el protocolo jdbc:postgresql, apunta a localhost porque el contenedor expone el puerto en tu máquina, y termina con el nombre exacto de la base que definiste en el compose.

¿Qué pasa si Docker no está corriendo al iniciar la app?

Spring lanzará un error indicando que no puede conectarse a Docker. La solución es abrir Docker Desktop antes de arrancar la aplicación. Una vez activo, Spring descarga la imagen de Postgres, configura el contenedor y crea la conexión usando Hikari, el pool de conexiones por defecto. La primera ejecución tarda más porque baja la imagen; las siguientes son casi inmediatas.

¿Cómo verifico que la conexión funciona correctamente?

Puedes conectarte a la base con cualquier cliente SQL que prefieras. En la clase se usa DataGrip de JetBrains, pero pgAdmin o cualquier otro funciona igual [08:45].

Los pasos son los mismos en cualquier herramienta:

1. Crea un nuevo data source de tipo PostgreSQL.
2. Pega la URL, el usuario y la contraseña que configuraste.
3. Prueba la conexión y aplica.

Si todo está bien, verás la base platziplaydb lista, aún sin tablas. Ese contenedor aparece también en Docker Desktop con el nombre Platzi Play Default, junto con la imagen de PostgreSQL ya descargada.

Con la base de datos viva y conectada al proyecto, el siguiente paso natural es crear una entity, que generará automáticamente la tabla correspondiente y te permitirá empezar a guardar datos reales. ¿Ya tienes Docker corriendo en tu equipo o prefieres conectarte a un Postgres local? Cuéntame en los comentarios cómo te fue con la configuración.