forked from wangziqi/ruoyi-vue-pro
116 lines
5.0 KiB
Markdown
116 lines
5.0 KiB
Markdown
---
|
||
name: flyway-postgresql
|
||
description: 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:
|
||
|
||
```text
|
||
<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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```yaml
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```sql
|
||
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.
|