Schema 结构管理与版本校验 (Schema Management & Version Verification)

与许多在应用启动时内置数据迁移框架（如 Liquibase 或 Flyway）直接变更数据库表结构的传统应用不同，StackSaga 严格推行数据库管理权限与应用运行时执行权限的清晰分离原则：

应用运行时权限边界 (Application Runtime Privilege Boundary)： 通过 R2DBC 连接数据库的应用运行时账号，仅需对事件存储表具备基础数据访问权限 (SELECT, INSERT, UPDATE, DELETE)。应用程序在启动期间绝不执行任何 DDL，也绝不擅自修改数据库元数据对象。

在应用发布部署之前，应由 DBA 或 CI/CD 自动化流水线使用具备 DDL 权限的高权限账号预先执行框架提供的 schema.sql 脚本。

启动前预检 Schema 版本自动校验 (Pre-Flight Schema Version Verification)

为了杜绝因数据库未初始化或版本不匹配而导致的字段缺失异常或静默数据不一致，StackSaga Starter 在应用启动时会执行自动化的、非阻塞预检 Schema 版本校验：

  1. 当 Spring 单例 Bean 完成实例化且连接池预热完成后，StackSaga 会查询 stacksaga_schema_version 元数据表。

  2. 校验表中是否已准确记录当前框架所需的 Schema 目标版本号（例如 1.0.0）。

  3. 如果该版本表不存在，或者缺少对应的版本记录行，应用程序将拒绝启动并立即快速失败 (Fail-Fast)，抛出包含明确修复指引的 SchemaVersionMismatchException。

获取 Schema 初始化 DDL 脚本

开发人员与 DBA 可以通过多种方式轻松获取 DDL 脚本：

  • 从依赖 JAR 包中提取：

    标准的官方 DDL 脚本打包在依赖 JAR 的以下路径中：

    db/stacksaga/<database>/schema.sql

  • 通过 Java 代码编程式获取（适用于本地开发、单元测试与 Testcontainers）：

    在集成测试（如 Testcontainers 容器化测试启动）、自动化迁移工具或自定义初始化脚本中，您可以直接将原始 DDL 脚本以 String 形式提取出来：

    String ddl = StackSaga<Database>AutoConfiguration.getSchemaScript();

  • IDE 一键运行打印：

    如需快速查看或复制脚本，只需在 IDE（IntelliJ IDEA、Eclipse、VS Code）中定位到 StackSaga<Database>AutoConfiguration 类并运行其 main() 方法。该类会将完整的 DDL 脚本直接打印到控制台，您可以轻松复制并粘贴到数据库客户端（如 DBeaver、MySQL Workbench、pgAdmin 或终端 CLI）中执行。

累积性与幂等性升级机制 (Cumulative and Idempotent Upgrades)

schema.sql 的每次发布均严格遵循累积性 (Cumulative) 与幂等性 (Idempotent) 设计：

  • 全新环境初始化：执行 schema.sql 将自动创建所有必需的表结构、索引与约束，并在 stacksaga_schema_version 表中盖上版本戳。

  • 存量数据库原地升级：重新执行 schema.sql 是完全安全且非破坏性的——现有业务数据和表结构完整保留，仅安全增补新的 Schema 对象，并写入最新的版本记录行。