# 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