From 0b1b815cf41186420a35258b748b15653735f157 Mon Sep 17 00:00:00 2001
From: Nano Taboada <nanotaboada@users.noreply.github.com>
Date: Fri, 10 Apr 2026 11:25:35 -0300
Subject: [PATCH 1/7] feat(db): integrate Flyway for database migrations (#130)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 11 +++++
 README.md                                     | 47 +++++++++++++++++++
 pom.xml                                       | 23 +++++++++
 src/main/resources/application.properties     | 13 ++++-
 .../db/migration/V1__Create_players_table.sql | 21 +++++++++
 .../db/migration/V2__Seed_starting11.sql      | 16 +++++++
 .../db/migration/V3__Seed_substitutes.sql     | 20 ++++++++
 src/test/resources/application.properties     |  4 ++
 8 files changed, 154 insertions(+), 1 deletion(-)
 create mode 100644 src/main/resources/db/migration/V1__Create_players_table.sql
 create mode 100644 src/main/resources/db/migration/V2__Seed_starting11.sql
 create mode 100644 src/main/resources/db/migration/V3__Seed_substitutes.sql

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17e1a6e..2bb1d23 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,17 @@ Release names follow the **historic football clubs** naming convention (A–Z):
 
 ### Added
 
+- Integrate Flyway for database schema versioning and automated migrations;
+  add `flyway-core` 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` with `baseline-on-migrate=true` for
+  backwards compatibility with existing databases; 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/README.md b/README.md
index fab0231..83e3665 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:
+
+```
+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).
+
+### 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.
+
+### Existing databases
+
+`baseline-on-migrate=true` ensures that databases created before Flyway was introduced are recognised as already at `V3` (schema + full seed data), so no migrations run against them. Fresh databases (new file) run V1 → V2 → V3 from scratch.
+
+### Reset local database
+
+Delete the SQLite file and restart the application — Flyway recreates the schema and seed data automatically:
+
+```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..a2a00e2 100644
--- a/pom.xml
+++ b/pom.xml
@@ -169,6 +169,29 @@
             <groupId>org.hibernate.orm</groupId>
             <artifactId>hibernate-community-dialects</artifactId>
         </dependency>
+        <!-- Flyway Core ================================================== -->
+        <!--
+            Flyway is an open-source database migration tool. It provides version
+            control for your database schema and automates migrations across all
+            environments. Includes built-in support for SQLite (community).
+            https://mvnrepository.com/artifact/org.flywaydb/flyway-core
+        -->
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-core</artifactId>
+        </dependency>
+        <!-- Flyway Database PostgreSQL ==================================== -->
+        <!--
+            Flyway 10+ modular architecture requires explicit database support
+            modules for non-community databases. Required for PostgreSQL support
+            (see #286 — Add PostgreSQL support with unified migration-based
+            initialization).
+            https://mvnrepository.com/artifact/org.flywaydb/flyway-database-postgresql
+        -->
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-database-postgresql</artifactId>
+        </dependency>
         <!-- H2 Database Engine ============================================ -->
         <!--
             Provides a fast in-memory database for testing. Used only in test
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
index 52a6bdf..83029e8 100644
--- a/src/main/resources/application.properties
+++ b/src/main/resources/application.properties
@@ -20,7 +20,18 @@ springdoc.swagger-ui.path=/swagger/index.html
 spring.datasource.url=jdbc:sqlite:${STORAGE_PATH:storage/players-sqlite3.db}
 spring.datasource.driver-class-name=org.sqlite.JDBC
 spring.jpa.database-platform=org.hibernate.community.dialect.SQLiteDialect
-spring.jpa.hibernate.ddl-auto=none
+spring.jpa.hibernate.ddl-auto=validate
 spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
 spring.jpa.show-sql=false
 spring.jpa.properties.hibernate.format_sql=true
+
+# Flyway Database Migration Configuration
+# Flyway manages all schema creation and seed data via versioned SQL migrations.
+# baseline-on-migrate: treats an existing database (without flyway_schema_history)
+#   as already at baseline-version, avoiding re-running migrations on pre-seeded DBs.
+# baseline-version=3: baselines existing databases at V3 (schema + all seed data
+#   already applied), while fresh databases run V1 → V2 → V3 from scratch.
+spring.flyway.enabled=true
+spring.flyway.locations=classpath:db/migration
+spring.flyway.baseline-on-migrate=true
+spring.flyway.baseline-version=3
diff --git a/src/main/resources/db/migration/V1__Create_players_table.sql b/src/main/resources/db/migration/V1__Create_players_table.sql
new file mode 100644
index 0000000..33a8f8c
--- /dev/null
+++ b/src/main/resources/db/migration/V1__Create_players_table.sql
@@ -0,0 +1,21 @@
+-- V1: Create players table
+-- Compatible with both SQLite (local dev) and PostgreSQL (see #286).
+-- TEXT columns use TEXT affinity in SQLite and the unlimited TEXT type in PostgreSQL.
+-- INTEGER is used for squadNumber (natural key) and starting11 (boolean flag: 1/0).
+-- UUID primary key is stored as VARCHAR(36) and generated at the application level.
+
+CREATE TABLE IF NOT EXISTS players (
+    id           VARCHAR(36)  NOT NULL,
+    squadNumber  INTEGER      NOT NULL,
+    firstName    TEXT         NOT NULL,
+    middleName   TEXT,
+    lastName     TEXT         NOT NULL,
+    dateOfBirth  TEXT         NOT NULL,
+    position     TEXT         NOT NULL,
+    abbrPosition TEXT         NOT NULL,
+    team         TEXT         NOT NULL,
+    league       TEXT         NOT NULL,
+    starting11   INTEGER      NOT NULL,
+    PRIMARY KEY (id),
+    UNIQUE (squadNumber)
+);
diff --git a/src/main/resources/db/migration/V2__Seed_starting11.sql b/src/main/resources/db/migration/V2__Seed_starting11.sql
new file mode 100644
index 0000000..8fb8aa7
--- /dev/null
+++ b/src/main/resources/db/migration/V2__Seed_starting11.sql
@@ -0,0 +1,16 @@
+-- V2: Seed Starting XI players (starting11 = 1)
+-- Argentina 2022 FIFA World Cup squad — 11 players who started the final.
+-- Rolling back this migration removes only the Starting XI, leaving substitutes intact.
+
+INSERT INTO players (id, squadNumber, firstName, middleName, lastName, dateOfBirth, position, abbrPosition, team, league, starting11) VALUES
+    ('01772c59-43f0-5d85-b913-c78e4e281452', 23, 'Damián',  'Emiliano',         'Martínez',  '1992-09-02T00:00:00.000Z', 'Goalkeeper',      'GK', 'Aston Villa FC',           'Premier League', 1),
+    ('da31293b-4c7e-5e0f-a168-469ee29ecbc4', 26, 'Nahuel',  NULL,               'Molina',    '1998-04-06T00:00:00.000Z', 'Right-Back',      'RB', 'Atlético Madrid',          'La Liga',        1),
+    ('c096c69e-762b-5281-9290-bb9c167a24a0', 13, 'Cristian','Gabriel',          'Romero',    '1998-04-27T00:00:00.000Z', 'Centre-Back',     'CB', 'Tottenham Hotspur',        'Premier League', 1),
+    ('d5f7dd7a-1dcb-5960-ba27-e34865b63358', 19, 'Nicolás', 'Hernán Gonzalo',   'Otamendi',  '1988-02-12T00:00:00.000Z', 'Centre-Back',     'CB', 'SL Benfica',               'Liga Portugal',  1),
+    ('2f6f90a0-9b9d-5023-96d2-a2aaf03143a6',  3, 'Nicolás', 'Alejandro',        'Tagliafico','1992-08-31T00:00:00.000Z', 'Left-Back',       'LB', 'Olympique Lyon',           'Ligue 1',        1),
+    ('b5b46e79-929e-5ed2-949d-0d167109c022', 11, 'Ángel',   'Fabián',           'Di María',  '1988-02-14T00:00:00.000Z', 'Right Winger',    'RW', 'SL Benfica',               'Liga Portugal',  1),
+    ('0293b282-1da8-562e-998e-83849b417a42',  7, 'Rodrigo', 'Javier',           'de Paul',   '1994-05-24T00:00:00.000Z', 'Central Midfield','CM', 'Atlético Madrid',          'La Liga',        1),
+    ('d3ba552a-dac3-588a-b961-1ea7224017fd', 24, 'Enzo',    'Jeremías',         'Fernández', '2001-01-17T00:00:00.000Z', 'Central Midfield','CM', 'SL Benfica',               'Liga Portugal',  1),
+    ('9613cae9-16ab-5b54-937e-3135123b9e0d', 20, 'Alexis',  NULL,               'Mac Allister','1998-12-24T00:00:00.000Z','Central Midfield','CM','Brighton & Hove Albion',   'Premier League', 1),
+    ('acc433bf-d505-51fe-831e-45eb44c4d43c', 10, 'Lionel',  'Andrés',           'Messi',     '1987-06-24T00:00:00.000Z', 'Right Winger',    'RW', 'Paris Saint-Germain',      'Ligue 1',        1),
+    ('38bae91d-8519-55a2-b30a-b9fe38849bfb',  9, 'Julián',  NULL,               'Álvarez',   '2000-01-31T00:00:00.000Z', 'Centre-Forward',  'CF', 'Manchester City',          'Premier League', 1);
diff --git a/src/main/resources/db/migration/V3__Seed_substitutes.sql b/src/main/resources/db/migration/V3__Seed_substitutes.sql
new file mode 100644
index 0000000..5398b8b
--- /dev/null
+++ b/src/main/resources/db/migration/V3__Seed_substitutes.sql
@@ -0,0 +1,20 @@
+-- V3: Seed Substitute players (starting11 = 0)
+-- Argentina 2022 FIFA World Cup squad — 15 players who did not start the final.
+-- Rolling back this migration removes only the substitutes, leaving the Starting XI intact.
+
+INSERT INTO players (id, squadNumber, firstName, middleName, lastName, dateOfBirth, position, abbrPosition, team, league, starting11) VALUES
+    ('5a9cd988-95e6-54c1-bc34-9aa08acca8d0',  1, 'Franco',    'Daniel',    'Armani',    '1986-10-16T00:00:00.000Z', 'Goalkeeper',        'GK', 'River Plate',               'Copa de la Liga',    0),
+    ('5fdb10e8-38c0-5084-9a3f-b369a960b9c2',  2, 'Juan',      'Marcos',    'Foyth',     '1998-01-12T00:00:00.000Z', 'Right-Back',        'RB', 'Villarreal',                'La Liga',            0),
+    ('bbd441f7-fcfb-5834-8468-2a9004b64c8c',  4, 'Gonzalo',   'Ariel',     'Montiel',   '1997-01-01T00:00:00.000Z', 'Right-Back',        'RB', 'Nottingham Forest',         'Premier League',     0),
+    ('9d140400-196f-55d8-86e1-e0b96a375c83',  5, 'Leandro',   'Daniel',    'Paredes',   '1994-06-29T00:00:00.000Z', 'Defensive Midfield','DM', 'AS Roma',                   'Serie A',            0),
+    ('d8bfea25-f189-5d5e-b3a5-ed89329b9f7c',  6, 'Germán',    'Alejo',     'Pezzella',  '1991-06-27T00:00:00.000Z', 'Centre-Back',       'CB', 'Real Betis Balompié',       'La Liga',            0),
+    ('dca343a8-12e5-53d6-89a8-916b120a5ee4',  8, 'Marcos',    'Javier',    'Acuña',     '1991-10-28T00:00:00.000Z', 'Left-Back',         'LB', 'Sevilla FC',                'La Liga',            0),
+    ('c62f2ac1-41e8-5d34-b073-2ba0913d0e31', 12, 'Gerónimo',  NULL,        'Rulli',     '1992-05-20T00:00:00.000Z', 'Goalkeeper',        'GK', 'Ajax Amsterdam',            'Eredivisie',         0),
+    ('d3b0e8e8-2c34-531a-b608-b24fed0ef986', 14, 'Exequiel',  'Alejandro', 'Palacios',  '1998-10-05T00:00:00.000Z', 'Central Midfield',  'CM', 'Bayer 04 Leverkusen',       'Bundesliga',         0),
+    ('b1306b7b-a3a4-5f7c-90fd-dd5bdbed57ba', 15, 'Ángel',     'Martín',    'Correa',    '1995-03-09T00:00:00.000Z', 'Right Winger',      'RW', 'Atlético Madrid',           'La Liga',            0),
+    ('ecec27e8-487b-5622-b116-0855020477ed', 16, 'Thiago',    'Ezequiel',  'Almada',    '2001-04-26T00:00:00.000Z', 'Attacking Midfield','AM', 'Atlanta United FC',         'Major League Soccer',0),
+    ('7cc8d527-56a2-58bd-9528-2618fc139d30', 17, 'Alejandro', 'Darío',     'Gómez',     '1988-02-15T00:00:00.000Z', 'Left Winger',       'LW', 'AC Monza',                  'Serie A',            0),
+    ('191c82af-0c51-526a-b903-c3600b61b506', 18, 'Guido',     NULL,        'Rodríguez', '1994-04-12T00:00:00.000Z', 'Defensive Midfield','DM', 'Real Betis Balompié',       'La Liga',            0),
+    ('7941cd7c-4df1-5952-97e8-1e7f5d08e8aa', 21, 'Paulo',     'Exequiel',  'Dybala',    '1993-11-15T00:00:00.000Z', 'Second Striker',    'SS', 'AS Roma',                   'Serie A',            0),
+    ('79c96f29-c59f-5f98-96b8-3a5946246624', 22, 'Lautaro',   'Javier',    'Martínez',  '1997-08-22T00:00:00.000Z', 'Centre-Forward',    'CF', 'Inter Milan',               'Serie A',            0),
+    ('98306555-a466-5d18-804e-dc82175e697b', 25, 'Lisandro',  NULL,        'Martínez',  '1998-01-18T00:00:00.000Z', 'Centre-Back',       'CB', 'Manchester United',         'Premier League',     0);
diff --git a/src/test/resources/application.properties b/src/test/resources/application.properties
index 7e0c762..1267428 100644
--- a/src/test/resources/application.properties
+++ b/src/test/resources/application.properties
@@ -15,6 +15,10 @@ spring.sql.init.data-locations=classpath:dml.sql
 spring.jpa.show-sql=false
 spring.jpa.properties.hibernate.format_sql=true
 
+# Flyway Configuration (disabled for tests)
+# Tests use SQLite in-memory with Spring SQL init (ddl.sql + dml.sql) instead.
+spring.flyway.enabled=false
+
 # Server Configuration (disabled for tests)
 server.port=0
 management.server.port=0

From 329ef414007efb67a58c64955a43dc1d04ba2c39 Mon Sep 17 00:00:00 2001
From: Nano Taboada <nanotaboada@users.noreply.github.com>
Date: Fri, 10 Apr 2026 11:52:03 -0300
Subject: [PATCH 2/7] docs(readme): add language specifier to fenced code block
 (#130)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 83e3665..77f1d19 100644
--- a/README.md
+++ b/README.md
@@ -277,7 +277,7 @@ Schema versioning is managed by [Flyway](https://documentation.red-gate.com/flyw
 
 Versioned SQL scripts live in `src/main/resources/db/migration/` and follow the Flyway naming convention:
 
-```
+```text
 V{version}__{description}.sql
 ```
 

From d34b06315ddfccb3188d4221f455a224bc6cbd18 Mon Sep 17 00:00:00 2001
From: Nano Taboada <nanotaboada@users.noreply.github.com>
Date: Fri, 10 Apr 2026 12:15:54 -0300
Subject: [PATCH 3/7] fix(db): use BOOLEAN for starting11 to pass Hibernate 7
 schema validation (#130)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hibernate 7 (Spring Boot 4.0.0) strictly validates Boolean → BOOLEAN;
INTEGER no longer satisfies the check. Update V1 migration and test DDL
to declare starting11 as BOOLEAN (native in PostgreSQL; stored as 0/1
with BOOLEAN affinity in SQLite). Regenerate storage/players-sqlite3.db
from the migration scripts so the pre-seeded Docker image matches.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../db/migration/V1__Create_players_table.sql |   2 +-
 src/test/resources/ddl.sql                    |   2 +-
 storage/players-sqlite3.db                    | Bin 28672 -> 16384 bytes
 3 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/main/resources/db/migration/V1__Create_players_table.sql b/src/main/resources/db/migration/V1__Create_players_table.sql
index 33a8f8c..11d5c85 100644
--- a/src/main/resources/db/migration/V1__Create_players_table.sql
+++ b/src/main/resources/db/migration/V1__Create_players_table.sql
@@ -15,7 +15,7 @@ CREATE TABLE IF NOT EXISTS players (
     abbrPosition TEXT         NOT NULL,
     team         TEXT         NOT NULL,
     league       TEXT         NOT NULL,
-    starting11   INTEGER      NOT NULL,
+    starting11   BOOLEAN      NOT NULL,
     PRIMARY KEY (id),
     UNIQUE (squadNumber)
 );
diff --git a/src/test/resources/ddl.sql b/src/test/resources/ddl.sql
index 25e8bc0..32e2b9b 100644
--- a/src/test/resources/ddl.sql
+++ b/src/test/resources/ddl.sql
@@ -15,5 +15,5 @@ CREATE TABLE players (
     abbrPosition TEXT        NOT NULL,
     team        TEXT         NOT NULL,
     league      TEXT         NOT NULL,
-    starting11  INTEGER      NOT NULL
+    starting11  BOOLEAN      NOT NULL
 );
diff --git a/storage/players-sqlite3.db b/storage/players-sqlite3.db
index 0a15fd4fa82b749225040ff24e5cf444264ec9ae..4d7389dd10f13dc19cd8f61049dc59bfd2144272 100644
GIT binary patch
delta 185
zcmZp8z}V2hI6+#FnSp_U1&CpQaiWf~Ff)T*-Y#DLHw?_YO$@wE{CoNPHVY~U@N%_q
zGO~+HOEb1-PIll4oIICDWAhmvCq_>ve}5lWM?VEH@beE*@C)_v(cuDd1A;t#9fKkj
zyj>#|G%`~(A)=vvo`IpR3L3?QrHLtirMXF|MVefiy3CU&@ar(M=rRFm6;8u~oW#o1
TqGIOFZ}>$778wXE3J?GQp?EBi

delta 514
zcmZ9{ze^io7zgn8y`SFY?!Fh3cwVzyphCphDuRPslp91XF({a+M!7=a8mh6hT{NO7
zh)6=f$tjbQAaN2bojM6Zr!JNbg+g&~@DJ$w(9*#dzMqHZ{RK~>!5cq#Gn>pY#&i)?
zL=rJtg)u+Jp4BdG=RH%bapnwI<G8{R_ON%p{V8GY#Io*XvwZ(~`_P`Zf>L>Uu2`-F
zGhwBDYv=V~@x}D~V%SxkN#4G<GfU=RNz%NbAzs<2uEbG&Eq=Wby{t!T@1ol3<5r$3
zhsA|3SSU`;hQXt|`C9c&R1hx*amT&$?G%@W)pipFSsPYFeQJ!pjjJD{^}5o%L)tZM
zF%rWA!>?{}#7C=n+X>v(oSx)jpXR1$BGSL}o6d+kVTuhO%MADUji30AZ}^I9e8Fd2
z;sR$lMF%H1MiU3v#U?&r9Wh>E`R^|!drOr$f8vvVKiTh*ULV<)Av0+*og!1cWN(s8
ux}*yd4(ZsWZIM=jOqir;kVX&Lqm#NuYO0zOMNz1cWm1x4*)YUd|JNTYL1jV!


From 0643be7cd2139b3f9457b7da38f24094704c6ec0 Mon Sep 17 00:00:00 2001
From: Nano Taboada <nanotaboada@users.noreply.github.com>
Date: Fri, 10 Apr 2026 12:21:35 -0300
Subject: [PATCH 4/7] =?UTF-8?q?chore(docker):=20simplify=20entrypoint=20?=
 =?UTF-8?q?=E2=80=94=20use=20log=20helper,=20remove=20seed=20copy=20(#130)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flyway now handles database initialization, so the seed copy logic is
no longer needed. Align with the Rust entrypoint style: use a log()
helper for formatted output, add Swagger UI endpoint to the startup
banner, keep health check endpoint.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 scripts/entrypoint.sh | 45 +++++++++++++++++--------------------------
 1 file changed, 18 insertions(+), 27 deletions(-)

diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh
index 5f87856..53e9daf 100644
--- a/scripts/entrypoint.sh
+++ b/scripts/entrypoint.sh
@@ -1,37 +1,28 @@
 #!/bin/sh
 set -e
 
-echo "✔ Executing entrypoint script..."
+# Helper function for formatted logging
+log() {
+    echo "[ENTRYPOINT] $(date '+%Y/%m/%d - %H:%M:%S') | $1"
+    return 0
+}
 
-IMAGE_STORAGE_PATH="/app/hold/players-sqlite3.db"
-VOLUME_STORAGE_PATH="/storage/players-sqlite3.db"
+log "✔ Starting container..."
 
-echo "✔ Starting container..."
+STORAGE_PATH="${STORAGE_PATH:-storage/players-sqlite3.db}"
 
-if [ ! -f "$VOLUME_STORAGE_PATH" ]; then
-  echo "⚠️ No existing database file found in volume."
-  if [ -f "$IMAGE_STORAGE_PATH" ]; then
-    echo "Copying database file to writable volume..."
-    if cp "$IMAGE_STORAGE_PATH" "$VOLUME_STORAGE_PATH"; then
-      echo "✔ Database initialized at $VOLUME_STORAGE_PATH"
-    else
-      echo "❌ Failed to copy database from $IMAGE_STORAGE_PATH to $VOLUME_STORAGE_PATH"
-      echo "   Check file permissions and available disk space."
-      exit 1
-    fi
-  else
-    echo "⚠️ Database file missing at $IMAGE_STORAGE_PATH"
-    exit 1
-  fi
+mkdir -p "$(dirname "$STORAGE_PATH")"
+
+if [ ! -f "$STORAGE_PATH" ]; then
+    log "⚠️ No existing database file found at $STORAGE_PATH."
+    log "🗄️ Flyway migrations will initialize the database on first start."
 else
-  echo "✔ Existing database file found. Skipping seed copy."
+    log "✔ Existing database file found at $STORAGE_PATH."
 fi
 
-echo "✔ Ready!"
-echo "🚀 Launching app..."
-echo ""
-echo "🔌 Endpoints:"
-echo "   Health:  http://localhost:9001/actuator/health"
-echo "   Players: http://localhost:9000/players"
-echo ""
+log "✔ Ready!"
+log "🚀 Launching app..."
+log "🔌 API endpoints | http://localhost:9000"
+log "📚 Swagger UI    | http://localhost:9000/swagger/index.html"
+log "❤️  Health check  | http://localhost:9001/actuator/health"
 exec "$@"

From 7500bba7e4db7c4f2e24f47b2d5556410a1b685b Mon Sep 17 00:00:00 2001
From: Nano Taboada <nanotaboada@users.noreply.github.com>
Date: Fri, 10 Apr 2026 12:28:36 -0300
Subject: [PATCH 5/7] fix(db): let Flyway own full DB lifecycle on fresh
 installs (#130)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

baseline-on-migrate=true with baseline-version=3 caused Flyway to mark
an empty database as already at V3 (due to its own schema_history table
creation), skipping all migrations and leaving no players table. Remove
the baseline settings so Flyway runs V1→V2→V3 normally on first start.

Remove the pre-seeded storage/players-sqlite3.db from version control
and the Dockerfile COPY ./hold/ layer — Flyway now creates the database
and seeds all 26 players automatically. Add storage/.gitkeep and ignore
storage/*.db. Update README accordingly.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore                                |   1 +
 Dockerfile                                |   5 -----
 README.md                                 |  10 +++++-----
 scripts/entrypoint.sh                     |   6 +++---
 src/main/resources/application.properties |   7 +------
 storage/.gitkeep                          |   0
 storage/players-sqlite3.db                | Bin 16384 -> 0 bytes
 7 files changed, 10 insertions(+), 19 deletions(-)
 create mode 100644 storage/.gitkeep
 delete mode 100644 storage/players-sqlite3.db

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/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 77f1d19..08f4ade 100644
--- a/README.md
+++ b/README.md
@@ -289,6 +289,10 @@ V{version}__{description}.sql
 
 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:
@@ -299,13 +303,9 @@ 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.
 
-### Existing databases
-
-`baseline-on-migrate=true` ensures that databases created before Flyway was introduced are recognised as already at `V3` (schema + full seed data), so no migrations run against them. Fresh databases (new file) run V1 → V2 → V3 from scratch.
-
 ### Reset local database
 
-Delete the SQLite file and restart the application — Flyway recreates the schema and seed data automatically:
+Delete the SQLite file and restart — Flyway recreates the schema and seed data from scratch:
 
 ```bash
 rm storage/players-sqlite3.db
diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh
index 53e9daf..179b7ec 100644
--- a/scripts/entrypoint.sh
+++ b/scripts/entrypoint.sh
@@ -22,7 +22,7 @@ fi
 
 log "✔ Ready!"
 log "🚀 Launching app..."
-log "🔌 API endpoints | http://localhost:9000"
-log "📚 Swagger UI    | http://localhost:9000/swagger/index.html"
-log "❤️  Health check  | http://localhost:9001/actuator/health"
+log "🔌 API endpoints   | http://localhost:9000"
+log "📚 Swagger UI      | http://localhost:9000/swagger/index.html"
+log "❤️ Health check    | http://localhost:9001/actuator/health"
 exec "$@"
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
index 83029e8..6f5be93 100644
--- a/src/main/resources/application.properties
+++ b/src/main/resources/application.properties
@@ -27,11 +27,6 @@ spring.jpa.properties.hibernate.format_sql=true
 
 # Flyway Database Migration Configuration
 # Flyway manages all schema creation and seed data via versioned SQL migrations.
-# baseline-on-migrate: treats an existing database (without flyway_schema_history)
-#   as already at baseline-version, avoiding re-running migrations on pre-seeded DBs.
-# baseline-version=3: baselines existing databases at V3 (schema + all seed data
-#   already applied), while fresh databases run V1 → V2 → V3 from scratch.
+# On first start, Flyway creates the database and runs V1 → V2 → V3 in order.
 spring.flyway.enabled=true
 spring.flyway.locations=classpath:db/migration
-spring.flyway.baseline-on-migrate=true
-spring.flyway.baseline-version=3
diff --git a/storage/.gitkeep b/storage/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/storage/players-sqlite3.db b/storage/players-sqlite3.db
deleted file mode 100644
index 4d7389dd10f13dc19cd8f61049dc59bfd2144272..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 16384
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


From 90e4421134c73cb6ae1dd16e2dddcfc8db31b8d8 Mon Sep 17 00:00:00 2001
From: Nano Taboada <nanotaboada@users.noreply.github.com>
Date: Fri, 10 Apr 2026 12:43:25 -0300
Subject: [PATCH 6/7] fix(db): replace flyway-core with
 spring-boot-starter-flyway (#130)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spring Boot 4.0 moved Flyway auto-configuration out of
spring-boot-autoconfigure into a dedicated starter module. Adding only
flyway-core to the classpath is no longer sufficient to trigger
FlywayAutoConfiguration or the spring.flyway.* properties — the starter
is required, following the same convention as spring-boot-starter-data-jpa,
spring-boot-starter-webmvc, etc.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md |  4 +++-
 pom.xml      | 16 +++++++++-------
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2bb1d23..7a7a921 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,7 +43,9 @@ Release names follow the **historic football clubs** naming convention (A–Z):
 ### Added
 
 - Integrate Flyway for database schema versioning and automated migrations;
-  add `flyway-core` and `flyway-database-postgresql` to `pom.xml`; create
+  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);
diff --git a/pom.xml b/pom.xml
index a2a00e2..0a6b798 100644
--- a/pom.xml
+++ b/pom.xml
@@ -169,16 +169,18 @@
             <groupId>org.hibernate.orm</groupId>
             <artifactId>hibernate-community-dialects</artifactId>
         </dependency>
-        <!-- Flyway Core ================================================== -->
+        <!-- Spring Boot Starter Flyway ==================================== -->
         <!--
-            Flyway is an open-source database migration tool. It provides version
-            control for your database schema and automates migrations across all
-            environments. Includes built-in support for SQLite (community).
-            https://mvnrepository.com/artifact/org.flywaydb/flyway-core
+            Spring Boot 4.0 moved Flyway auto-configuration out of
+            spring-boot-autoconfigure into this dedicated starter. Adding only
+            flyway-core is no longer sufficient — this starter is required to
+            enable FlywayAutoConfiguration and the spring.flyway.* properties.
+            Transitively brings in flyway-core (version managed by Spring BOM).
+            https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-flyway
         -->
         <dependency>
-            <groupId>org.flywaydb</groupId>
-            <artifactId>flyway-core</artifactId>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-flyway</artifactId>
         </dependency>
         <!-- Flyway Database PostgreSQL ==================================== -->
         <!--

From d7c2b743157dc8aeda6c16e8db40429adb02bd50 Mon Sep 17 00:00:00 2001
From: Nano Taboada <nanotaboada@users.noreply.github.com>
Date: Fri, 10 Apr 2026 13:15:59 -0300
Subject: [PATCH 7/7] fix(docs): correct CHANGELOG and harden entrypoint
 permissions check (#130)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md          | 11 ++++++-----
 scripts/entrypoint.sh | 10 ++++++++++
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a7a921..d9e0783 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,11 +49,12 @@ Release names follow the **historic football clubs** naming convention (A–Z):
   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` with `baseline-on-migrate=true` for
-  backwards compatibility with existing databases; 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)
+  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
 
diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh
index 179b7ec..e95e8f4 100644
--- a/scripts/entrypoint.sh
+++ b/scripts/entrypoint.sh
@@ -13,6 +13,16 @@ STORAGE_PATH="${STORAGE_PATH:-storage/players-sqlite3.db}"
 
 mkdir -p "$(dirname "$STORAGE_PATH")"
 
+if [ ! -w "$(dirname "$STORAGE_PATH")" ]; then
+    log "❌ Storage directory is not writable: $(dirname "$STORAGE_PATH")"
+    exit 1
+fi
+
+if [ -f "$STORAGE_PATH" ] && [ ! -w "$STORAGE_PATH" ]; then
+    log "❌ Database file is not writable: $STORAGE_PATH"
+    exit 1
+fi
+
 if [ ! -f "$STORAGE_PATH" ]; then
     log "⚠️ No existing database file found at $STORAGE_PATH."
     log "🗄️ Flyway migrations will initialize the database on first start."