diff --git a/.gitignore b/.gitignore
index 5d86ea8..a48fa2c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
HELP.md
.claude/settings.local.json
target/
+storage/*.db
!.mvn/wrapper/maven-wrapper.jar
!**/src/main/**/target/
!**/src/test/**/target/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17e1a6e..d9e0783 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,20 @@ Release names follow the **historic football clubs** naming convention (A–Z):
### Added
+- Integrate Flyway for database schema versioning and automated migrations;
+ add `spring-boot-starter-flyway` (Spring Boot 4.0 requires this dedicated
+ starter for autoconfiguration — `flyway-core` alone is insufficient) and
+ `flyway-database-postgresql` to `pom.xml`; create
+ migration directory `src/main/resources/db/migration/` with three versioned
+ scripts: `V1__Create_players_table.sql` (schema), `V2__Seed_starting11.sql`
+ (11 Starting XI players), `V3__Seed_substitutes.sql` (15 substitute players);
+ configure `spring.flyway.enabled=true` and `spring.flyway.locations` only —
+ no baseline settings, Flyway runs V1→V2→V3 from scratch on every empty
+ database; disable Flyway in test environment which continues to use SQLite
+ in-memory with `ddl.sql`/`dml.sql`; switch `spring.jpa.hibernate.ddl-auto`
+ from `none` to `validate` so Hibernate verifies entity mappings against the
+ Flyway-managed schema (#130)
+
### Changed
- Switch runtime base image from `eclipse-temurin:25-jdk-alpine` to
diff --git a/Dockerfile b/Dockerfile
index c77e70e..de6f6e7 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -44,11 +44,6 @@ COPY --chmod=444 README.md ./
COPY --chmod=555 scripts/entrypoint.sh ./entrypoint.sh
COPY --chmod=555 scripts/healthcheck.sh ./healthcheck.sh
-# The 'hold' is our storage compartment within the image. Here, we copy a
-# pre-seeded SQLite database file, which Compose will mount as a persistent
-# 'storage' volume when the container starts up.
-COPY --chmod=555 storage/ ./hold/
-
# Install SQLite runtime libs, add non-root user and prepare volume mount point
RUN apk add --no-cache sqlite-libs && \
addgroup -S spring && \
diff --git a/README.md b/README.md
index fab0231..08f4ade 100644
--- a/README.md
+++ b/README.md
@@ -269,6 +269,53 @@ spring.datasource.url=jdbc:sqlite::memory:
spring.jpa.hibernate.ddl-auto=create-drop
```
+## Database Migrations
+
+Schema versioning is managed by [Flyway](https://documentation.red-gate.com/flyway), which runs automatically on application startup and applies any pending migrations in order.
+
+### Migration files
+
+Versioned SQL scripts live in `src/main/resources/db/migration/` and follow the Flyway naming convention:
+
+```text
+V{version}__{description}.sql
+```
+
+| File | Description |
+| ---- | ----------- |
+| `V1__Create_players_table.sql` | Creates the `players` table (schema) |
+| `V2__Seed_starting11.sql` | Seeds 11 Starting XI players (`starting11 = 1`) |
+| `V3__Seed_substitutes.sql` | Seeds 15 Substitute players (`starting11 = 0`) |
+
+All migration SQL is written to be compatible with both **SQLite** (local dev) and **PostgreSQL** (see #286).
+
+### First start
+
+On first run, Flyway detects an empty database and applies V1 → V2 → V3 in sequence, creating the `players` table and seeding all 26 players. The database file (`storage/players-sqlite3.db`) is created automatically and is excluded from version control.
+
+### Adding a new migration
+
+Create a new file in `src/main/resources/db/migration/` with the next version number:
+
+```bash
+touch src/main/resources/db/migration/V4__Add_nationality_column.sql
+```
+
+Flyway applies it automatically on the next application startup. View the applied history by querying the `flyway_schema_history` table.
+
+### Reset local database
+
+Delete the SQLite file and restart — Flyway recreates the schema and seed data from scratch:
+
+```bash
+rm storage/players-sqlite3.db
+./mvnw spring-boot:run
+```
+
+### Tests
+
+The test environment keeps `spring.flyway.enabled=false` and uses SQLite in-memory with `ddl.sql`/`dml.sql` via Spring SQL init for fast, isolated test execution.
+
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on:
diff --git a/pom.xml b/pom.xml
index 2b5ba25..0a6b798 100644
--- a/pom.xml
+++ b/pom.xml
@@ -169,6 +169,31 @@
org.hibernate.orm
hibernate-community-dialects
+
+
+
+ org.springframework.boot
+ spring-boot-starter-flyway
+
+
+
+
+ org.flywaydb
+ flyway-database-postgresql
+