Spring Boot Seeding Demo

Simple Spring Boot application, demoing a lightweight mechanism for seeding a database.

Features

• Spring Boot 3.4.5 with Java 24
• PostgreSQL database integration
• Spring Data JPA for data access
• Spring Data REST for automatic REST endpoints
• HAL Browser to navigate the app's resources
• Database seeding with JavaFaker
• MapStruct for object mapping
• Docker Compose support for local development
• Test suite with TestContainers

Prerequisites

• Java 24 or later
• A container runtime, preferably compatible with the Docker API
• Gradle 8.x or later

Getting Started

1. Clone the repository:

   git clone <repository-url>
   cd seeding-demo

2. Build and run the application in development mode:

   SPRING_PROFILES_ACTIVE=dev ./gradlew bootRun

   This also starts the compose stack.

Project Structure

src/main/java/com/demo/seeding/
├── config/         # Application configuration
├── domain/         # Domain models and repositories
│   ├── model/      # JPA entities
│   └── repository/ # Spring Data repositories
├── system/         # System components
│   └── seeding/    # Seeding abstraction and components
├── web/            # Web controllers and DTOs
│   ├── dto/        # Data transfer objects
│   └── mapper/     # MapStruct mappers
└── Application.java

Database Seeding

The seeding mechanism is made up of two constituents:

• Seeder - an abstraction, composed of a target repository, and a strategy for generating entities of type E,
• SeederExecutor - a component which auto-discovers Seeder implementations, and executes them.

How It Works

1. Seeders are automatically discovered and executed when the application starts in development mode
2. The SeederExecutor component manages the execution of all registered seeders
3. Seeders are executed in the order they are discovered, when using @Component-based definitions, or in order their of declaration, when using @Bean-based definitions

Creating Your Own Seeders

You may create your Seeders by either:

• defining a Seeder<E> @Bean factory method, or
• subclassing Seeder<E>, and either registering it as a @Component, or via a @Bean method

Example:

    @Bean
    Seeder<PetType> petTypeFixturesSeeder(PetTypeRepository petTypeRepository) {
        return new Seeder<>(
            petTypeRepository,
            () -> Stream
                .generate(
                    () -> PetType.builder()
                        .name(faker.witcher().monster())
                        .build()
                )
                .limit(10)
                .toList()
        );
    }

@Component
class PetTypeFixturesSeeder extends Seeder<PetType> {

    public PetTypeFixturesSeeder(PetTypeRepository repository) {
        super(
            repository,
            () -> List.of(
                PetType.builder().name("Dog").build(),
                PetType.builder().name("Cat").build()
            )
        );
    }
}

By default, seeders are only executed in development mode. See:

• @DevelopmentOnly.
• SeederExecutor.

Example Seeders

Example Seeders can be found at:

• SeederProvider - example Seeders for Pet and PetType entities, where the PetSeeder depends on the PetTypeSeeder being executed first.

• WellKnownSeedersConfig - example Seeder for Pets, with static data for tests.

Testing

Run the test suite:

./gradlew test

The test suite includes:

• Integration tests using TestContainers
• REST API tests using REST Assured

API Documentation

Once the application is running, you can access:

• HAL Explorer: http://localhost:8080
• Actuator endpoints: http://localhost:8080/actuator