ruoyi-vue-pro/.claude/skills/flyway-postgresql/SKILL.md

name, description

name	description
flyway-postgresql	Flyway PostgreSQL migrations for this project. Use when adding or changing database schema, indexes, constraints, required seed data, migration baselines, or Flyway configuration.

Flyway PostgreSQL migrations

Use a forward-only migration process. Treat flyway_schema_history as immutable release history.

1. Inspect the migration state

Before editing:

1. Read CLAUDE.md PostgreSQL and Flyway rules.
2. Inspect yudao-server/src/main/resources/application-{local,dev}.yaml and yudao-server/pom.xml when configuration is involved.
3. List every db/migration directory and versioned migration across active modules.
4. Inspect the target table DO, Mapper, service use, and relevant PostgreSQL DDL.
5. Check the working tree so existing uncommitted work is preserved.

Complete when: the active Flyway locations, baseline, highest migration version, affected database objects, and pending user changes are known.

2. Choose the migration branch

New schema change

Create a new versioned SQL migration under:

<module>/src/main/resources/db/migration/<module>/

Use the next unused project-wide version after V4010. Leave gaps of 10 for normal changes when practical:

V4020__add_student_progress.sql
V4030__add_practice_report_index.sql

Fix an executed migration

Create a higher version that repairs or reverses the prior change. Preserve the executed file byte-for-byte.

Existing database adoption

The current baseline is 4009; V4010__initialize_education_flyway.sql is the first managed migration. Keep baseline-on-migrate only while existing environments are being adopted. After every existing environment has a baseline record, change it to false in a separate reviewed change.

Configuration change

Flyway must target the dynamic datasource master, never slave. Keep these safeguards enabled:

validate-on-migrate: true
clean-disabled: true
out-of-order: false

Allow FLYWAY_URL, FLYWAY_USER, and FLYWAY_PASSWORD to override master credentials.

Complete when: exactly one branch is selected and its version/configuration does not conflict with the current repository state.

3. Write PostgreSQL-native SQL

Follow these project conventions:

• Identity primary key: BIGINT GENERATED BY DEFAULT AS IDENTITY.
• Time: TIMESTAMP; use CURRENT_TIMESTAMP for defaults.
• Boolean: BOOLEAN NOT NULL DEFAULT false where appropriate.
• Idempotency/upsert: ON CONFLICT ... DO NOTHING or DO UPDATE SET ... EXCLUDED.column.
• Null fallback: COALESCE.
• Date formatting: TO_CHAR; date parts: EXTRACT.
• Bounded delete: delete by IDs selected in an ordered, limited subquery or CTE.
• Add comments for business tables and non-obvious columns.
• Add indexes from observed query and conflict targets, not speculation.
• Required seed data must be deterministic and idempotent.
• Put CREATE INDEX CONCURRENTLY in its own non-transactional migration; otherwise prefer transactional PostgreSQL DDL.

Keep verification queries in comments when useful. Put rollback notes in the change description or a separate operational document; production recovery is another forward migration.

Complete when: every affected object, data backfill, constraint, index, and application assumption is represented in PostgreSQL-native SQL.

4. Align application code

Update all affected DOs, Mappers, services, tests, and fixtures. Search Java annotations and MyBatis XML for stale column names and incompatible SQL. For a new identity/sequence-backed DO, follow the surrounding project’s @TableId and @KeySequence pattern.

Complete when: every code reference agrees with the post-migration schema and no active runtime SQL depends on the previous shape.

5. Verify

Run, in order:

git diff --check
mvn -pl yudao-server -am -DskipTests clean compile

Confirm each migration is present under the owning module’s target/classes/db/migration/... after compilation. If an authorized disposable PostgreSQL database is available, run Flyway against it and inspect:

SELECT installed_rank, version, description, script, checksum, success
FROM flyway_schema_history
ORDER BY installed_rank;

Run focused tests for the affected module. Report any skipped database execution separately from compilation success.

Complete when: formatting and compilation pass, migration packaging is confirmed, focused tests pass or their exact blocker is reported, and any real-database migration status is stated truthfully.

Release rules

• Version numbers are project-wide across every Flyway location.
• One committed migration version has one immutable meaning.
• Production migrations move forward; recovery is a higher version.
• clean remains disabled.
• Demo/test seed data lives outside production migrations.
• Do not copy the legacy sql/postgresql/ruoyi-vue-pro.sql dump into a versioned runtime migration; it contains destructive bootstrap statements and embedded transactions. Use it only to initialize a disposable empty database or to establish the pre-Flyway baseline.