triz-docs/docs/workflow/FlyWay for postgresql + CICD/FlyWay workflow + CICD.md

Flyway Setup Guide for PostgreSQL + Tomcat Deployment

Goal

This setup allows automatic database updates during deployment.

Each database modification is added as a new SQL migration file. During CI/CD deployment, Flyway executes only the missing migrations safely and in order.

This avoids:

• giant SQL files
• duplicate executions
• manual tracking of DB changes
• production inconsistencies

---

Environment

This guide is adapted for:

• PostgreSQL 17
• Java 17
• Maven Wrapper (mvnw.cmd)
• Tomcat deployment
• Existing production databases
• Windows CI/CD runner

---

1. Add Flyway to Maven

Add Flyway Maven Plugin

In pom.xml:

<plugin>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-maven-plugin</artifactId>
    <version>11.0.0</version>
</plugin>

---

2. Create Migration Folder

Create this folder inside the project:

src/main/resources/db/migration

---

3. Migration Naming Convention while for each Db modification a new file is added

Flyway requires this exact format:

V<version>__<description>.sql

Examples:

V1__initial_schema.sql
V2__task301_add_tables_t1_t2.sql
V3__add_client_phone.sql
V4__fix_invoice_indexes.sql

Important:

• Use TWO underscores (__) after the version
• Never rename old migrations after execution
• Never modify old executed migrations

---

4. Existing Database Initialization (One-Time Only)

Since the database already exists in production, Flyway must first create its history table.

First Migration

Create:

V1__initial_schema.sql

This file represents the current database structure.

---

Baseline Existing Database

Run once only:

mvn flyway:baseline ^
-Dflyway.url=jdbc:postgresql://localhost:5432/TrizTresorie ^
-Dflyway.user=postgres ^
-Dflyway.password=YOUR_PASSWORD ^
-Dflyway.baselineVersion=1

This creates:

flyway_schema_history

and marks version 1 as already applied WITHOUT executing the SQL.

---

5. Adding New Database Changes

Every new database modification must be added as a new migration file.

Example:

V2__task301_add_tables_t1_t2.sql

Example content:

CREATE TABLE table1 (
    id BIGSERIAL PRIMARY KEY
);

CREATE TABLE table2 (
    id BIGSERIAL PRIMARY KEY
);

Commit the migration file with the application code.

---

6. Running Migrations

To execute pending migrations:

mvn flyway:migrate ^
-Dflyway.url=jdbc:postgresql://localhost:5432/TrizTresorie ^
-Dflyway.user=postgres ^
-Dflyway.password=YOUR_PASSWORD

Flyway will:

1. Check flyway_schema_history
2. Detect already executed migrations
3. Execute only new migrations
4. Save execution history automatically

---

7. CI/CD Integration

Add this step before starting Tomcat.

Example

# --------------------------------------------------
# Run database migrations
# --------------------------------------------------
- name: Run database migrations
  shell: cmd
  run: |
    cd %WORKSPACE_DIR%
    mvnw.cmd flyway:migrate ^
    -Dflyway.url=%DB_URL% ^
    -Dflyway.user=%DB_USER% ^
    -Dflyway.password=%DB_PASSWORD%    

Recommended:

• Store DB credentials in CI/CD secrets or environment variables
• Do not hardcode passwords inside the repository

---

8. Recommended Developer Workflow

When a developer needs a database change:

DO

Create a new migration:

V5__add_product_status.sql

Commit and push.

---

DO NOT

Do NOT modify:

V1__initial_schema.sql

or any already executed migration.

Always create a new migration instead.

---

9. Important Notes

Migration Order

Flyway executes migrations in version order:

V1
V2
V3
V4

---

Failed Migrations

If a migration fails:

• deployment stops
• Tomcat should not start
• database remains protected from partial execution

Fix the migration and rerun deployment.

---

Production Safety

Do not:

• delete flyway_schema_history
• modify old executed migrations
• manually rerun executed SQL files

---

10. Example Project Structure

project/
│
├── src/
│   └── main/
│       └── resources/
│           └── db/
│               └── migration/
│                   ├── V1__initial_schema.sql
│                   ├── V2__task301_add_tables_t1_t2.sql
│                   ├── V3__add_client_phone.sql
│                   └── V4__fix_indexes.sql
│
├── pom.xml
└── mvnw.cmd

---

11. Final Deployment Flow

Recommended deployment sequence:

1. Clone source
2. Build application
3. Stop Tomcat
4. Backup configuration
5. Deploy new application
6. Restore configuration
7. Run Flyway migrations
8. Start Tomcat
9. Cleanup workspace

---

Result

With this setup:

• database updates become automatic
• all environments stay synchronized
• production deployments become safer
• developers only add new migration files
• no manual SQL tracking is needed