Spring Demo: Tutorial 04 (Docker Compose Spring Boot Postgres)

Welcome back to Code College ZA! In this episode, Spring Demo Tutorial 4, we move away from the in-memory H2 database we used throughout Tutorial 1 and connect a real Spring Boot application to PostgreSQL, running entirely inside Docker, using Spring Boot's built-in Docker Compose integration. This is the tutorial where our Taco Cloud API stops resetting every time the app restarts and starts behaving like a genuine production service with persistent data. We begin by explaining exactly why this matters: H2 is fantastic for fast iteration and learning, but it's memory-only, meaning every piece of data you create disappears the moment the application stops. Real applications need durable storage, and PostgreSQL is one of the most widely used relational databases in the industry. Rather than manually installing Postgres on Windows and managing it as a separate service, we use Docker Compose to run it in an isolated, disposable container, and we show how Spring Boot 3.2's spring-boot-docker-compose dependency takes this even further by automatically starting and stopping that container for you whenever the application runs, with zero manual docker compose commands required in most cases. We walk through the compose.yaml file itself, which defines a single Postgres 16 service with environment variables for the database name, username, and password, and a dynamically assigned host port so there's no fixed-port collision with anything else running locally. This is a deliberate design choice we explain in depth: letting Docker assign the port avoids the exact kind of "port already in use" errors we fought through in earlier tutorials, and Spring Boot's Docker Compose support automatically detects whatever port got assigned and wires up the datasource connection behind the scenes, so you never have to hardcode a JDBC URL by hand. From there we update our existing TacoController, TacoRepository, and Taco entity to work against Postgres instead of H2. We show how little actually changes at the code level, since JPA and Hibernate abstract away most of the database-specific details, but we do walk through swapping the H2 dependency for the PostgreSQL JDBC driver, and we demonstrate the full annotation set this tutorial reinforces: @Entity and @Id for mapping, @Valid combined with @NotBlank and @Size for input validation, @RestControllerAdvice and @ResponseStatus for proper 400 and 404 error handling, and the complete CRUD set of @GetMapping, @PostMapping, @PutMapping, and @DeleteMapping. A big focus of this episode is proving that the data genuinely persists. We don't just tell you it works, we show it: we create a taco through the API, restart the entire application, and query it again to prove the row is still there, something that was never possible with H2. We then go one step further and connect directly into the running Postgres container using docker exec and psql, running a raw SQL query against the taco table to confirm the data matches exactly what the REST API reports, closing the loop between the application layer and the actual database. As always on this channel, we spend real time on the environment issues that come with this setup, because Docker on Windows brings its own category of friction that a lot of tutorials gloss over. We troubleshoot a genuinely broken Docker Desktop engine returning a 500 Internal Server Error on version checks, work through restarting the WSL2 backend, and explain the difference between the Docker CLI responding correctly while the underlying engine is still unhealthy. We also show how to verify Docker's status with docker ps before even attempting to start the Spring Boot application. We also demonstrate testing the finished API two different ways: first with PowerShell's Invoke-RestMethod for quick command-line checks, and then by building out a proper Postman collection with a shared baseUrl variable, covering GET, POST, PUT, and DELETE requests, along with validation failure and 404 scenarios so you can see exactly what a non-success response looks like in a real API client rather than just the happy path. By the end of this tutorial, you'll have a Spring Boot application backed by a real, persistent PostgreSQL database running in Docker, fully tested through both the command line and Postman, with the same validation and error-handling discipline we built in earlier episodes. This is the exact pattern used in real production Spring Boot services, and it sets up perfectly for later tutorials where we'll add API documentation with Swagger and eventually move into full microservices architecture. Drop a comment if you'd like us to cover database migrations with Flyway or Liquibase next, or multi-container setups with several services talking to each other. Like, subscribe, and turn on notifications so you don't miss the rest of this series. Follow Code College ZA everywhere: @CodeCollegeZA on YouTube, Instagram, Twitter/X, and GitHub.