Spring PetClinic: The Reference App for Spring Boot, Not a Production Blueprint

What Spring PetClinic Actually Solves

Spring PetClinic is a sample application that shows how to build a web app with Spring Boot. It solves the problem of having no canonical, maintained example to point newcomers at. The README is explicit: it is a Spring Boot application built with Maven or Gradle. The domain is a veterinary clinic with owners, pets, and visits, but the domain is not the point. The point is to demonstrate the standard structure: a main class, controllers, services, repositories, and templates. It is for developers who want to see a complete, working Spring Boot app before they build their own. It is also for trainers and authors who need a small, predictable codebase to teach with. The project is not a production system. It uses an in-memory database by default and has no authentication. That is fine for learning, but it means the app is a starting point, not a deployable product.

How It Works: Profiles, Databases, and Startup Data

The application runs as a standard Spring Boot app. It uses an H2 in-memory database by default, and the README says the database is populated at startup with data. The H2 console is exposed at /h2-console, and you can inspect the database using a JDBC URL that includes a UUID printed to the console. That UUID is a small detail that shows the sample is meant for exploration, not for persistent use. The app also supports MySQL and PostgreSQL through Spring profiles. You set spring.profiles.active=mysql or spring.profiles.active=postgres to switch. The README gives docker commands for each database, and there is a docker-compose.yml with services named after the profiles. The data flow is simple: the app starts, Spring Boot creates the schema from SQL scripts in src/main/resources/db, and the profile determines which script runs. The integration tests follow the same pattern. PetClinicIntegrationTests uses H2 and Devtools, MySqlTestApplication uses Testcontainers, and PostgresIntegrationTests uses Docker Compose. This is a clean demonstration of how to handle multiple databases in one Spring Boot app without changing code.

Getting It Running: Commands That Work

The README gives exact commands, and they are the first thing you should trust. Clone the repo with git clone https://github.com/spring-projects/spring-petclinic.git, then cd into it. With Maven, run ./mvnw spring-boot:run. With Gradle, run ./gradlew bootRun. Both start the app on localhost:8080. Java 17 or later is required, both for building and running. The project uses Maven wrapper and Gradle wrapper, so you do not need a local Maven or Gradle install. To build a container image, run ./mvnw spring-boot:build-image, which uses the Spring Boot build plugin. There is no Dockerfile, which is a deliberate choice: the plugin generates the image. The README then shows docker run -p 8080:8080 docker.io/library/spring-petclinic:latest. For a persistent database, you start MySQL or PostgreSQL with the given docker run commands, then set the active profile. The docker-compose.yml is an alternative: docker compose up mysql or docker compose up postgres. These commands are concrete and repeatable, which is what you want from a sample.

The CSS Build Quirk: A Real Limitation

One limitation stands out: the CSS is generated from SCSS, and the build process is Maven-only. The README says there is a petclinic.css in src/main/resources/static/resources/css, generated from petclinic.scss combined with Bootstrap. If you change the SCSS or upgrade Bootstrap, you must recompile the CSS using the Maven profile: ./mvnw package -P css. There is no Gradle profile for CSS compilation. That means Gradle users cannot rebuild the styles without switching to Maven or manually running a separate process. This is a small but genuine friction point. For a sample app, it is acceptable, but it shows that the project assumes Maven as the primary build tool. If you are teaching Gradle, you will hit this wall. The README also mentions that the IDE setup for Eclipse and IntelliJ includes a step to generate resources: ./mvnw generate-resources. That is the same CSS generation step. So the project is not fully symmetric across build tools, and that is a concrete trade-off to know before you adopt it.

Where It Is the Wrong Tool

Spring PetClinic is the wrong tool if you need a production-ready application. It has no security layer, no user management, no audit logging, and the default database is in-memory, so all data vanishes on restart. The README does not mention authentication or authorization anywhere. That is not a flaw in a sample, but it is a hard boundary. If you are evaluating Spring Boot for a real project, do not copy this app's structure blindly. It also uses a single-module layout, which is fine for a demo but not for a large codebase. The project is also not a performance benchmark. It is a small CRUD app, so do not use it to judge Spring Boot's throughput or memory footprint. Another wrong use case is as a template for a microservices architecture. This is a monolith, and the README does not suggest any distributed patterns. If you need to learn Spring Cloud, Service Discovery, or API gateways, this is not the sample for you. It is a teaching tool, and using it beyond that scope will lead to gaps.

Alternatives: What Else to Look At

If Spring PetClinic does not fit, the main alternative is the official Spring Boot documentation and its getting-started guide, which the README links to. That guide shows a minimal single-file application, which is even simpler than PetClinic. The difference is that the guide is a tutorial, not a full app. For a more production-oriented sample, you might look at the Spring Initializr, which generates a project skeleton with your chosen dependencies. That gives you a starting point without the PetClinic domain. Another alternative is the Spring Boot Samples repository, which contains many small, focused examples, each demonstrating one feature. The difference in approach is that PetClinic is a single, integrated app, while those samples are isolated snippets. If your goal is to see how multiple features work together, PetClinic is better. If your goal is to understand one feature in isolation, the samples are better. For learning the Spring ecosystem, the difference is between a map and a compass.

Maintenance and Upgrade Cost

The repository is under the spring-projects organization, which is a positive sign for maintenance, but the README warns that the linked slides refer to a legacy, pre-Spring Boot version. That means the project has evolved, and some external documentation is outdated. The README itself is current, but you should verify the Spring Boot version in the pom.xml or build.gradle before relying on it. The project has no Dockerfile, so container builds depend on the Spring Boot build plugin. If you upgrade Spring Boot, the plugin behavior may change, and you will need to re-test the build-image step. The CSS build is another maintenance point: if you upgrade Bootstrap, you must recompile the CSS with the Maven profile. There is no Gradle path for that. The project uses Java 17 or later, so if you are on an older Java version, you cannot run it. The license is Apache-2.0, which means you can use the code in your own projects with attribution, but this is not legal advice. The practical cost is low: it is a sample, so upgrades are about testing, not about migrating a large codebase.

Editorial conclusion

Adopt Spring PetClinic if you are learning Spring Boot, teaching it, or need a small reference app to test libraries. Skip it if you need a production skeleton with security, monitoring, or a real persistence layer. Before relying on it, verify the current branch and the exact Spring Boot version, because the project evolves and the legacy slides are outdated. Treat it as a sample, not a template.

Official sources

1. Official README
2. Project repository