chore: Clean migration (#296)

Co-authored-by: Stefan Nemeth <[email protected]>

.github/workflows/flyway-validate.yml

@@ -6,9 +6,9 @@ on:
   workflow_call: {}
 
 env:
-  FLYWAY_URL: jdbc:postgresql://localhost:5432/helios
-  FLYWAY_USER: helios
-  FLYWAY_PASSWORD: helios
+  DATASOURCE_URL: jdbc:postgresql://localhost:5432/helios
+  DATASOURCE_USERNAME: helios
+  DATASOURCE_PASSWORD: helios
 
 jobs:
   validate-migrations:
@@ -19,8 +19,8 @@ jobs:
         image: postgres
 
         env:
-          POSTGRES_USER: ${{ env.FLYWAY_USER }}
-          POSTGRES_PASSWORD: ${{ env.FLYWAY_PASSWORD }}
+          POSTGRES_USER: ${{ env.DATASOURCE_USERNAME }}
+          POSTGRES_PASSWORD: ${{ env.DATASOURCE_PASSWORD }}
           POSTGRES_DB: helios
         ports:
           - 5432:5432

docs/development/local/migrations.rst

@@ -1,17 +1,57 @@
 ===================
-Database migrations
+Database Migrations
 ===================
 
-We are using `Flyway <https://flywaydb.org/>`__ for database migrations. A GitHub Actions workflow validates these migrations during CI/CD by ensuring that the migration scripts are correctly formatted and can be applied without errors. for database migrations. When changing the database schema, create a new migration file in ``src/main/resources/db/migration`` within the application server with the following naming convention: ``V<VERSION-NUMBER>__<description>.sql``, e.g. ``V1__create_users.sql``.
+Overview
+--------
+We use `Flyway <https://flywaydb.org/>`_ for database schema versioning and migrations. All database changes are tracked through version-controlled SQL scripts, ensuring consistent database states across all environments.
 
-The migrations are automatically applied when starting the application.
+Migration Files
+---------------
+**Location**
+
+All migration scripts should be placed in::
+
+    src/main/resources/db/migration
+
+**Naming Convention**
+
+Format::
+
+    V<VERSION-NUMBER>__<description>.sql
+
+Example::
+
+    V1__create_users.sql
+
+The version number should be sequential and unique across all migrations.
 
 Branching Strategy
 ------------------
 1. Create migration files in feature branches
-2. Prefix with next available version (just increment the last version number)
+2. Use the next available version number (increment from the last existing version)
 3. Rebase if conflicts occur
-4. Run migrations locally to verify that they work as expected, even though migrations are automatically applied on application startup
+4. Test migrations locally before merging (just start application-server to apply migrations)
 5. Merge to main
 
-**Important**: Never modify committed migrations! If a migration needs to be corrected or updated, create a new migration file to apply the necessary changes rather than altering an existing one.
+.. warning::
+
+   Never modify existing/committed migrations! Create new migration files for any necessary changes.
+
+Handling Migration Conflicts
+----------------------------
+When working with multiple branches, you may encounter migration conflicts. Here's how to handle them:
+
+1. Clean existing migrations::
+
+    ./gradlew flywayClean flywayMigrate
+
+2. Apply current branch migrations:
+
+   * Start application-server to apply migrations automatically
+
+3. When switching branches, clean and reapply migrations again::
+
+    ./gradlew flywayClean flywayMigrate
+
+

server/application-server/build.gradle

@@ -170,4 +170,30 @@ openApi {
 
 tasks.named('test') {
     useJUnitPlatform()
-}
+}
+
+// Load environment variables from the .env file
+// into the project properties so that they can be used
+def envFile = file('.env')
+if (envFile.exists()) {
+    envFile.readLines().each { line ->
+        def (key, value) = line.tokenize('=')
+        if (key && value) {
+            // Replace the double quotes around the value with an empty string
+            project.ext.set(key, value.trim().replaceAll('^"(.*)"$', '$1'))
+        }
+    }
+}
+
+flyway {
+    url = project.hasProperty('DATASOURCE_URL')
+        ? project.DATASOURCE_URL
+        : System.getenv('DATASOURCE_URL')
+    user = project.hasProperty('DATASOURCE_USERNAME')
+        ? project.DATASOURCE_USERNAME
+        : System.getenv('DATASOURCE_USERNAME')
+    password = project.hasProperty('DATASOURCE_PASSWORD')
+        ? project.DATASOURCE_PASSWORD
+        : System.getenv('DATASOURCE_PASSWORD')
+    cleanDisabled = false
+}

server/application-server/src/main/resources/application-dev.yml

@@ -9,8 +9,7 @@ spring:
         url: ${DATASOURCE_URL}
         user: ${DATASOURCE_USERNAME}
         password: ${DATASOURCE_PASSWORD}
-        baselineOnMigrate: true
-        baseline-version: 1
+        baselineOnMigrate: false
     jpa:
         database: POSTGRESQL
         show-sql: false