From 03812b1d149b60a47cad4443ae754d5b930658ad Mon Sep 17 00:00:00 2001 From: Abderrahmane Date: Thu, 7 May 2026 17:22:51 +0100 Subject: [PATCH] added flyWay docs --- .../FlyWay workflow + CICD.md | 306 ++++++++++++++++++ .../_category_.json | 8 + 2 files changed, 314 insertions(+) create mode 100644 docs/workflow/FlyWay for postgresql + CICD/FlyWay workflow + CICD.md create mode 100644 docs/workflow/FlyWay for postgresql + CICD/_category_.json diff --git a/docs/workflow/FlyWay for postgresql + CICD/FlyWay workflow + CICD.md b/docs/workflow/FlyWay for postgresql + CICD/FlyWay workflow + CICD.md new file mode 100644 index 0000000..e67db88 --- /dev/null +++ b/docs/workflow/FlyWay for postgresql + CICD/FlyWay workflow + CICD.md @@ -0,0 +1,306 @@ +# 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`: + +```xml + + org.flywaydb + flyway-maven-plugin + 11.0.0 + +``` + +--- + +## 2. Create Migration Folder + +Create this folder inside the project: + +```text +src/main/resources/db/migration +``` + +--- + +# 3. Migration Naming Convention while for each Db modification a new file is added + +Flyway requires this exact format: + +```text +V__.sql +``` + +Examples: + +```text +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: + +```text +V1__initial_schema.sql +``` + +This file represents the current database structure. + +--- + +## Baseline Existing Database + +Run once only: + +```cmd +mvn flyway:baseline ^ +-Dflyway.url=jdbc:postgresql://localhost:5432/TrizTresorie ^ +-Dflyway.user=postgres ^ +-Dflyway.password=YOUR_PASSWORD ^ +-Dflyway.baselineVersion=1 +``` + +This creates: + +```text +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: + +```text +V2__task301_add_tables_t1_t2.sql +``` + +Example content: + +```sql +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: + +```cmd +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 + +```yaml +# -------------------------------------------------- +# 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: + +```text +V5__add_product_status.sql +``` + +Commit and push. + +--- + +## DO NOT + +Do NOT modify: + +```text +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: + +```text +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 + +```text +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 + diff --git a/docs/workflow/FlyWay for postgresql + CICD/_category_.json b/docs/workflow/FlyWay for postgresql + CICD/_category_.json new file mode 100644 index 0000000..6370f63 --- /dev/null +++ b/docs/workflow/FlyWay for postgresql + CICD/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Data Base Modification Workflow + flyway + CICD", + "position": 2, + "link": { + "type": "generated-index", + "description": "Standard workflow for Data Base Modification + flyway + CICD." + } +}