tian/QAUP_Management

Fork 0

Tian jianyong c5ab993e24 增加 Flyway 支持

2025-08-08 13:35:47 +08:00

9.1 KiB

Raw Blame History

Design Document

Overview

本设计文档描述了为QAUP项目集成Flyway数据库迁移工具的技术方案。通过分析现有的SQL文件结构和部署流程，设计一个完整的数据库版本管理系统，包括基线迁移脚本的创建、Flyway配置集成、部署脚本修改以及开发流程规范。

Architecture

系统架构图

graph TB
    A[开发环境] --> B[Maven构建]
    B --> C[Flyway迁移脚本]
    C --> D[应用启动]
    D --> E[Flyway自动迁移]
    E --> F[PostgreSQL数据库]
    
    G[现有SQL文件] --> H[脚本整理工具]
    H --> I[基线迁移脚本]
    I --> C
    
    J[部署脚本] --> K[Docker容器]
    K --> D
    
    L[开发流程] --> M[新迁移脚本]
    M --> C

核心组件

Flyway Core: 数据库迁移引擎
Migration Scripts: 版本化的SQL迁移脚本
Baseline Migration: 基于现有SQL文件的初始化脚本
Configuration Management: Spring Boot集成配置
Deployment Integration: 部署流程集成

Components and Interfaces

1. Flyway配置组件

Maven依赖配置

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

Spring Boot配置

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
    baseline-version: 1.0.0
    baseline-description: "Initial baseline from existing database"
    validate-on-migrate: true
    clean-disabled: true
    out-of-order: false

2. 迁移脚本组件

目录结构

src/main/resources/
└── db/
    └── migration/
        ├── V1.0.0__Initial_baseline.sql
        ├── V1.0.1__Add_traffic_light_tables.sql
        ├── V1.0.2__Add_vehicle_filter_config.sql
        └── V1.0.3__Update_geofence_schema.sql

脚本命名规范

格式: V{version}__{description}.sql
版本号: 语义化版本控制 (major.minor.patch)
描述: 英文下划线分隔，简洁明了

3. 基线脚本生成组件

SQL文件分析器

public class SqlFileAnalyzer {
    public List<SqlScript> analyzeSqlFiles(Path sqlDirectory);
    public SqlScript mergeScripts(List<SqlScript> scripts);
    public void generateBaselineScript(SqlScript mergedScript, Path outputPath);
}

脚本合并策略

表结构优先: 先创建所有表结构
索引和约束: 然后添加索引和外键约束
初始数据: 最后插入基础数据
去重处理: 移除重复的CREATE语句

4. 部署集成组件

Docker启动脚本修改

# 在应用启动前等待数据库就绪
wait_for_database() {
    until pg_isready -h qaup-postgres -p 5432 -U qaup; do
        echo "等待数据库启动..."
        sleep 2
    done
}

# 应用启动时自动执行Flyway迁移
start_application() {
    wait_for_database
    java -jar /app/app.jar --spring.config.location=/app/config.yml
}

Data Models

1. Flyway元数据表

Flyway会自动创建 flyway_schema_history 表来跟踪迁移历史：

CREATE TABLE flyway_schema_history (
    installed_rank INTEGER NOT NULL,
    version VARCHAR(50),
    description VARCHAR(200) NOT NULL,
    type VARCHAR(20) NOT NULL,
    script VARCHAR(1000) NOT NULL,
    checksum INTEGER,
    installed_by VARCHAR(100) NOT NULL,
    installed_on TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    execution_time INTEGER NOT NULL,
    success BOOLEAN NOT NULL
);

2. 迁移脚本数据模型

public class MigrationScript {
    private String version;
    private String description;
    private String content;
    private LocalDateTime createdAt;
    private String author;
    private List<String> dependencies;
}

3. 基线数据模型

基于现有SQL文件分析，基线脚本将包含：

系统核心表: sys_user, sys_role, sys_dept等RuoYi框架表
业务表: sys_vehicle_info, sys_driver_info, sys_vehicle_type等
空间数据表: vehicle_location, airport_area等PostGIS表
配置表: sys_config及其初始数据
索引和约束: 所有必要的数据库索引和外键约束

Error Handling

1. 迁移失败处理

@Component
public class FlywayMigrationHandler {
    
    @EventListener
    public void handleMigrationFailure(FlywayMigrationFailureEvent event) {
        log.error("数据库迁移失败: {}", event.getException().getMessage());
        // 发送告警通知
        alertService.sendMigrationFailureAlert(event);
        // 记录详细错误信息
        errorLogService.logMigrationError(event);
    }
    
    @EventListener
    public void handleMigrationSuccess(FlywayMigrationSuccessEvent event) {
        log.info("数据库迁移成功完成，当前版本: {}", event.getTargetVersion());
    }
}

2. 版本冲突处理

检测机制: 启动时检查是否有版本冲突
解决策略:
- 开发环境: 允许out-of-order迁移
- 生产环境: 严格按版本顺序执行
回滚机制: 提供手动回滚工具和脚本

3. 数据完整性保护

-- 在迁移脚本中添加数据验证
DO $$
BEGIN
    -- 验证关键数据完整性
    IF NOT EXISTS (SELECT 1 FROM sys_config WHERE config_key = 'sys.user.initPassword') THEN
        RAISE EXCEPTION '关键配置数据缺失，迁移中止';
    END IF;
END $$;

Testing Strategy

1. 迁移脚本测试

单元测试

@SpringBootTest
@Testcontainers
class FlywayMigrationTest {
    
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgis/postgis:17-3.5-alpine")
            .withDatabaseName("qaup_test")
            .withUsername("test")
            .withPassword("test");
    
    @Test
    void testBaselineMigration() {
        // 测试基线迁移脚本
        Flyway flyway = Flyway.configure()
                .dataSource(postgres.getJdbcUrl(), postgres.getUsername(), postgres.getPassword())
                .locations("classpath:db/migration")
                .load();
        
        MigrateResult result = flyway.migrate();
        assertThat(result.migrationsExecuted).isGreaterThan(0);
    }
    
    @Test
    void testIncrementalMigration() {
        // 测试增量迁移
    }
}

集成测试

@SpringBootTest
@TestPropertySource(properties = {
    "spring.flyway.locations=classpath:db/migration,classpath:db/testdata"
})
class DatabaseIntegrationTest {
    
    @Test
    void testDatabaseSchemaAfterMigration() {
        // 验证迁移后的数据库结构
    }
    
    @Test
    void testDataIntegrityAfterMigration() {
        // 验证数据完整性
    }
}

2. 性能测试

迁移性能测试

大数据量测试: 模拟生产环境数据量
并发测试: 测试多实例启动时的迁移行为
回滚性能: 测试回滚操作的性能

监控指标

@Component
public class FlywayMetrics {
    private final MeterRegistry meterRegistry;
    
    public void recordMigrationTime(String version, Duration duration) {
        Timer.Sample sample = Timer.start(meterRegistry);
        sample.stop(Timer.builder("flyway.migration.duration")
                .tag("version", version)
                .register(meterRegistry));
    }
}

3. 环境测试

多环境验证

开发环境: 频繁迁移测试
测试环境: 完整迁移流程验证
预生产环境: 生产数据迁移模拟
生产环境: 蓝绿部署迁移测试

Docker环境测试

# docker-compose.test.yml
services:
  qaup-postgres-test:
    image: postgis/postgis:17-3.5-alpine
    environment:
      POSTGRES_DB: qaup_test
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
    volumes:
      - ./test-data:/docker-entrypoint-initdb.d

Implementation Plan

Phase 1: 基础设施搭建

添加Flyway依赖和配置
创建迁移脚本目录结构
开发SQL文件分析和合并工具

Phase 2: 基线迁移创建

分析现有SQL文件依赖关系
生成统一的基线迁移脚本
验证基线脚本的完整性和正确性

Phase 3: 部署集成

修改Docker配置支持Flyway
更新部署脚本
创建数据库初始化流程

Phase 4: 开发流程规范

制定迁移脚本开发规范
创建代码审查检查清单
建立版本管理流程

Phase 5: 监控和维护

实现迁移状态监控
创建故障排除工具
建立备份和回滚机制

Security Considerations

1. 权限控制

Flyway执行用户权限最小化
生产环境禁用clean操作
迁移脚本访问权限控制

2. 数据保护

敏感数据迁移加密
备份策略集成
审计日志记录

3. 环境隔离

不同环境使用不同的迁移配置
生产环境额外的安全检查
迁移脚本签名验证

Performance Optimization

1. 迁移性能优化

批量操作优化
索引创建策略
大表迁移分批处理

2. 启动性能优化

并行迁移支持
增量检查优化
缓存机制集成

3. 资源使用优化

内存使用控制
连接池配置优化
临时空间管理

9.1 KiB Raw Blame History Unescape Escape