架构与系统设计 / 系统课时
数据库初始化与迁移
数据库初始化与迁移
本课用 Flyway 建立一套可重复执行的数据库初始化流程,把平台表、租户表、索引和初始化数据拆成版本化脚本。完成后,新环境可以自动建库结构,已有环境也能按顺序安全升级,并留下可审计的迁移记录。
学习目标
- 区分平台库迁移与租户库迁移的职责边界
- 编写可追踪的建表、索引和初始化数据脚本
- 执行迁移并通过历史表验证版本状态
先确定迁移边界
SaaS 系统通常至少有两类数据:平台数据保存租户、套餐和全局配置;租户数据保存某个租户自己的业务记录。两类脚本应放在不同目录,并分别维护迁移历史,避免平台升级误改租户表,也避免某个租户迁移失败阻塞整个平台。

推荐目录如下。平台脚本由应用启动时执行,租户脚本由租户开通或升级任务针对目标数据源执行。
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,否则应用启动会把租户表建到平台库中。
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_historybaseline-on-migrate 只用于接管已有但尚未纳入 Flyway 的数据库。全新项目可以设为 false,以便数据库状态不符合预期时直接失败。
编写建表、索引与初始化数据
平台首个版本创建租户主表,业务编码使用唯一约束,避免重复创建同一租户。
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。
CREATE INDEX idx_tenant_status_created_at
ON tenant (status, created_at);初始化数据采用可重复且幂等的写法。即使脚本再次执行,也不会产生重复记录。
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);租户脚本连接到目标租户库后执行,因此表名不需要拼接租户编号。下面的脚本创建最小业务表及查询索引。
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 会先校验历史脚本校验和,再执行尚未安装的版本。
./mvnw -Dspring-boot.run.profiles=local spring-boot:run预期输出:
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日志中的版本数量可能随脚本增加而变化。随后查询迁移历史表,确认每个版本都成功安装。
SELECT installed_rank, version, description, type, success
FROM flyway_schema_history
ORDER BY installed_rank;预期结果:
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 与业务接口,验证开发环境是否形成可调用、可观察的最小请求闭环。