Spring PetClinic: The Official Spring Boot Sample Application

What Spring PetClinic Demonstrates and Who Uses It

Spring PetClinic is an official sample application maintained by the Spring team to demonstrate how Spring Boot features work together in a realistic application. The README describes it as a Spring Boot application built using Maven or Gradle that requires Java 17 or later.

The application models a veterinary clinic: owners, pets, vets, and visit records. This domain is familiar enough that readers understand the data model without domain explanation, and complex enough to show one-to-many relationships, form handling, and database queries in a realistic context.

The primary audience is developers learning Spring Boot for the first time, engineers evaluating how Spring handles specific concerns such as database migration, profile-based configuration, or containerization, and teams that want an agreed-upon baseline for comparing Spring Boot configurations. It is also used in conference presentations; the README links to slides from a Spring PetClinic presentation, though it notes those slides reference a legacy pre-Spring Boot version.

Running PetClinic Locally with Maven and Gradle

The README gives the full setup as three steps. First, clone the project:

git clone https://github.com/spring-projects/spring-petclinic.git
cd spring-petclinic

With Maven, start the application:

./mvnw spring-boot:run

With Gradle, the equivalent command is:

./gradlew bootRun

Both commands download dependencies, compile the application, and start an embedded web server. The application is then available at http://localhost:8080/. The project includes both the Maven wrapper (`mvnw`) and the Gradle wrapper (`gradlew`) so neither build tool needs to be installed on the developer's machine.

The default configuration starts with an H2 in-memory database populated with sample data at startup. The H2 console is exposed at http://localhost:8080/h2-console for inspecting the database. The README notes that the UUID for the in-memory database URL is printed to the console at startup, so the format is `jdbc:h2:mem:<uuid>` with that UUID substituted.

Java 17 or newer is required. The README states both the build requirement and the runtime requirement as Java 17 or later.

Database Profiles: H2, MySQL, and PostgreSQL

Spring PetClinic ships with support for three database backends controlled by Spring profiles. The default H2 configuration runs entirely in memory with no external dependencies. For a persistent MySQL or PostgreSQL setup, the application uses Docker to start the database container.

For MySQL:

docker run -e MYSQL_USER=petclinic -e MYSQL_PASSWORD=petclinic -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=petclinic -p 3306:3306 mysql:9.7

For PostgreSQL:

docker run -e POSTGRES_USER=petclinic -e POSTGRES_PASSWORD=petclinic -e POSTGRES_DB=petclinic -p 5432:5432 postgres:18.4

Alternatively, the docker-compose.yml in the repository provides named services for each database:

docker compose up mysql

or:

docker compose up postgres

After starting the database, activate the corresponding Spring profile when running the application. The README directs readers to the Spring Boot documentation for how to set the active profile, noting the values `mysql` and `postgres` for `spring.profiles.active`. Further setup documentation specific to each database is in the repository under `src/main/resources/db/mysql/` and `src/main/resources/db/postgres/`.

Building a Container Image Without a Dockerfile

Spring PetClinic has no Dockerfile in the repository. The README states this explicitly and provides the alternative: the Spring Boot build plugin can build a container image directly using Cloud Native Buildpacks.

With Maven:

./mvnw spring-boot:build-image

This command requires a running Docker daemon. It pulls a builder image, compiles the application, and produces a container image tagged `docker.io/library/spring-petclinic:latest`. To run the resulting image:

docker run -p 8080:8080 docker.io/library/spring-petclinic:latest

The buildpack approach produces a layered image optimized for caching. Because there is no Dockerfile, the image structure is determined by the Spring Boot plugin and the buildpack runtime, not by manual layer definitions. This is a deliberate demonstration of a Spring Boot production pattern rather than the absence of containerization.

IDE Setup, CSS Compilation, and Development Tooling

The README covers setup for four IDEs: Eclipse with the m2e plugin, Spring Tools Suite, IntelliJ IDEA, and VS Code. For IntelliJ IDEA, a run configuration named PetClinicApplication is created automatically if using a recent Ultimate version.

The application's CSS is compiled from SCSS. The repository contains `petclinic.css` in `src/main/resources/static/resources/css/`, generated from `petclinic.scss` combined with Bootstrap. If the SCSS is modified or Bootstrap is upgraded, the CSS must be recompiled using the Maven css profile:

./mvnw package -P css

The README notes there is no Gradle equivalent for CSS compilation. This is one area where Maven and Gradle support diverge in PetClinic.

A Gitpod configuration (.gitpod.yml) and a GitHub Codespaces configuration (.devcontainer/) allow opening the project in a browser-based IDE without local installation. Both badges in the README link to one-click launch URLs for these environments, which is a practical option for quickly exploring the codebase without a local Java setup.

Integration Tests with Testcontainers and Kubernetes Configuration

The README describes three test application classes. PetClinicIntegrationTests uses the default H2 database and adds Spring Boot Devtools for fast feedback. MySqlTestApplication uses Testcontainers to start a MySQL container in Docker for the test run. PostgresIntegrationTests uses Docker Compose to start the PostgreSQL service.

These test classes serve a dual purpose: they can be run as main() methods in an IDE for interactive testing, and they also function as integration test entry points for the CI pipeline. Testcontainers handles the container lifecycle automatically, so the MySQL tests do not require a pre-running MySQL instance; the container is started and stopped as part of the test run.

The repository also includes Kubernetes configuration in the k8s/ directory, noted in the repository's top-level entries, for teams evaluating Spring Boot applications in a container orchestration context. The README does not detail the Kubernetes setup beyond its existence in the layout.

Limitations and Variants

Spring PetClinic is a demonstration application, not a production template. Several defaults are appropriate for learning but not for deployment: the H2 console is open at a known URL, the MySQL and PostgreSQL docker run commands use simple predictable passwords (petclinic/petclinic), and the application seeds test data at startup. Any real deployment based on this application needs to address these points.

The README explicitly notes that the legacy presentation slides reference a pre-Spring Boot version and may not reflect the current implementation. The current codebase is the canonical reference; the slides are secondary.

A microservices variant of PetClinic, Spring PetClinic Microservices, exists as a separate repository. The related searches show consistent interest in `spring petclinic microservices`, which indicates that the single-application PetClinic is the starting point and the microservices version demonstrates a more complex distributed deployment. The monorepo version shown here is the simpler, more accessible introduction.

The last push to this repository was on 2026-08-26. The project is licensed under the Apache License 2.0, which permits use in commercial projects without copyleft restrictions.

Editorial conclusion

Spring PetClinic is the right resource for a developer learning Spring Boot who wants to see a complete, working application rather than isolated code snippets. It shows database profile switching, container image building without a Dockerfile, integration test setup with Testcontainers and Docker Compose, and CSS compilation from SCSS. It is not a production-ready template: it uses weak default credentials and an in-memory H2 database out of the box. Before using it as a starting point for a real project, replace the H2 default with a proper database configuration, remove the open H2 console endpoint, and review the default Petclinic data seeded at startup.

Frequently asked questions

Official sources

1. Official README
2. Project repository