added flyWay docs

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
+<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:
+
+```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<version>__<description>.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
+

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."
+  }
+}