7.1. Flyway Overview and File Rules

7.1. Flyway Overview

7.1.1. DDL Management Principles

All database schema changes must be managed through Flyway migration files.

Item	Rule
Schema change method	Only Flyway migration files are permitted
Manual DDL execution	Prohibited (direct changes to production DB are not allowed)
Migration file modification	Applied files must never be modified
Rollback	Process rollbacks via new migration files

7.1.2. Dependencies

<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-database-postgresql</artifactId>
</dependency>

Since the version is managed by the Spring Boot BOM, explicit version specification is not required.

7.2. Migration File Rules

7.2.1. File Location

src/main/resources/
└── db/
    └── migration/
        ├── V1__create_users_table.sql
        ├── V2__create_orders_table.sql
        ├── V3__add_phone_to_users.sql
        └── V4__create_documents_table.sql

7.2.2. File Naming Rules

V{version_number}__{description}.sql

Component	Rule	Example
Prefix	V (uppercase)	V1, V10
Version number	Sequential integer	1, 2, 3
Separator	__ (double underscore)
Description	snake_case, English	create_users_table
Extension	.sql

Correct examples:

V1__create_users_table.sql
V2__create_orders_table.sql
V3__add_phone_to_users.sql
V4__create_idx_users_email.sql
V5__insert_initial_roles.sql

Incorrect examples:

V1_create_users.sql        # Single underscore (two required)
v1__create_users.sql       # Lowercase v
V1__CreateUsers.sql        # CamelCase used
V1__사용자_테이블_생성.sql     # Korean used

7.2.3. Version Numbering Strategy

The sequential integer method must be used.

V1, V2, V3, ... V10, V11, ...

• For large teams or when conflicts are frequent, the timestamp method is also permitted: V20260228100000__description.sql
• The method must be decided at the beginning of the project and maintained consistently.

7.2.4. No-modification Principle

Strictly Prohibited

Migration files that have already been recorded in the flyway_schema_history table must never be modified or deleted.

If a faulty migration needs to be corrected, a new version migration file must be written to apply the changes.