架构与系统设计 / 系统课时

数据库初始化与迁移

数据库初始化与迁移

本课用 Flyway 建立一套可重复执行的数据库初始化流程,把平台表、租户表、索引和初始化数据拆成版本化脚本。完成后,新环境可以自动建库结构,已有环境也能按顺序安全升级,并留下可审计的迁移记录。

学习目标

  • 区分平台库迁移与租户库迁移的职责边界
  • 编写可追踪的建表、索引和初始化数据脚本
  • 执行迁移并通过历史表验证版本状态

先确定迁移边界

SaaS 系统通常至少有两类数据:平台数据保存租户、套餐和全局配置;租户数据保存某个租户自己的业务记录。两类脚本应放在不同目录,并分别维护迁移历史,避免平台升级误改租户表,也避免某个租户迁移失败阻塞整个平台。

平台库与租户库迁移关系

推荐目录如下。平台脚本由应用启动时执行,租户脚本由租户开通或升级任务针对目标数据源执行。

text
src/main/resources/
├── db/migration/platform/
│   ├── V1__create_platform_tables.sql
│   ├── V2__add_platform_indexes.sql
│   └── R__seed_platform_data.sql
└── db/migration/tenant/
    ├── V1__create_tenant_tables.sql
    └── V2__add_tenant_indexes.sql

版本脚本只执行一次,文件名使用 V版本__说明.sql;可重复脚本以 R__ 开头,内容变化后会再次执行,适合维护幂等的基础字典数据。

配置平台库自动迁移

以下配置让 Spring Boot 在启动时只扫描平台脚本。租户脚本不要放入同一个 locations,否则应用启动会把租户表建到平台库中。

yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/saas_platform?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: saas
    password: saas_password
  flyway:
    enabled: true
    locations: classpath:db/migration/platform
    baseline-on-migrate: true
    validate-on-migrate: true
    table: flyway_schema_history

baseline-on-migrate 只用于接管已有但尚未纳入 Flyway 的数据库。全新项目可以设为 false,以便数据库状态不符合预期时直接失败。

编写建表、索引与初始化数据

平台首个版本创建租户主表,业务编码使用唯一约束,避免重复创建同一租户。

sql
CREATE TABLE tenant (
    id BIGINT NOT NULL AUTO_INCREMENT,
    tenant_code VARCHAR(32) NOT NULL,
    tenant_name VARCHAR(100) NOT NULL,
    status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY uk_tenant_code (tenant_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

索引变化单独放入新版本,不能回头修改已经在其他环境执行过的 V1。

sql
CREATE INDEX idx_tenant_status_created_at
ON tenant (status, created_at);

初始化数据采用可重复且幂等的写法。即使脚本再次执行,也不会产生重复记录。

sql
CREATE TABLE IF NOT EXISTS platform_config (
    config_key VARCHAR(64) NOT NULL,
    config_value VARCHAR(255) NOT NULL,
    PRIMARY KEY (config_key)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

INSERT INTO platform_config (config_key, config_value)
VALUES ('default.locale', 'zh-CN')
ON DUPLICATE KEY UPDATE config_value = VALUES(config_value);

租户脚本连接到目标租户库后执行,因此表名不需要拼接租户编号。下面的脚本创建最小业务表及查询索引。

sql
CREATE TABLE customer (
    id BIGINT NOT NULL AUTO_INCREMENT,
    customer_no VARCHAR(32) NOT NULL,
    customer_name VARCHAR(100) NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY uk_customer_no (customer_no),
    KEY idx_customer_name (customer_name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

执行迁移并验证

在项目根目录启动应用,Flyway 会先校验历史脚本校验和,再执行尚未安装的版本。

bash
./mvnw -Dspring-boot.run.profiles=local spring-boot:run

预期输出:

text
Successfully validated <N> migrations
Migrating schema `saas_platform` to version "1 - create platform tables"
Migrating schema `saas_platform` to version "2 - add platform indexes"
Successfully applied <N> migrations

日志中的版本数量可能随脚本增加而变化。随后查询迁移历史表,确认每个版本都成功安装。

sql
SELECT installed_rank, version, description, type, success
FROM flyway_schema_history
ORDER BY installed_rank;

预期结果:

text
installed_rank | version | description               | type | success
1              | 1       | create platform tables    | SQL  | 1
2              | 2       | add platform indexes      | SQL  | 1
3              | null    | seed platform data        | SQL  | 1

迁移失败时的处理原则

迁移失败后,先修复 SQL 或数据库权限,再重新执行。已经在共享环境成功执行的版本脚本不得直接改写,否则会触发校验和不一致;应新增更高版本脚本完成修正。

租户迁移需要逐租户加锁并记录结果。某个租户失败时,只暂停该租户的后续版本,不要把其他租户已经成功的迁移整体回滚。删除列、缩短字段或重建大索引等高风险操作,应拆成兼容、切换、清理三个阶段。

本课总结

  • 平台库与租户库应使用独立脚本目录和独立迁移历史
  • 建表、索引与基础数据要版本化,已发布版本不可直接修改
  • 每次发布都应同时检查启动日志和 flyway_schema_history

下一课预告

下一课将串联健康检查、数据库、Redis 与业务接口,验证开发环境是否形成可调用、可观察的最小请求闭环。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

数据库初始化与迁移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通