KingbaseES客户端编程开发框架-Flyway.pdf

KingbaseES 客户端编程开发框架-Flyway 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 什么是 Flyway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Flyway 的工作原理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 第 3 章 Flyway 配置说明 5 第 4 章 Flyway 注意点 7 版权声明 8 服务周期承诺 9 I 第 1 章 前言 1 第 章 前言 本文档描述了数据库版本管理工具 Flyway 的使用方法和注意事项。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 《KingbaseES Flyway 指南》面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用程序开发人 员。 1.2 相关文档 有关 Flyway 的更多信息，请参阅以下资源： Flyway Documentation 1.3 术语 无 1 第 1 章 前言 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 2.1 什么是 Flyway Flyway 是一个开源的数据库迁移工具。相比于配置，它更多的是支持便捷和约定。 Flyway 仅基于 7 个基本的命令：migrate、clean、info、validate、undo、baseline 和 repair。 迁移可以用 SQL 或 Java 编写。 支持多种运行方式，如命令行、JAVA API、Maven 插件、Gradle 插件等。 2.2 Flyway 的工作原理 最简单的情况是当您将 Flyway 指向一个空数据库时。Flyway 将会尝试定位其架构历史表。由于数据库时空的， Flyway 找不到这个表，所以会创建它。现在就有了一个默认情况下只有一个名为 flyway_schema_history 的空表的 数据库。该表用于跟踪数据库的状态。紧接着，Flyway 将开始扫描文件系统或应用程序的类路径以进行迁移，然后 根据版本号对迁移进行排序，并按照顺序进行应用。随着每次迁移的应用，架构历史表也会相应的更新： 表 2.2.1: flyway_schema_history installed version description type script checksum installed installed execution _by _on _time 1996767037 axel 2016- 546 true 127 true _rank 1 1 Initial SQL Setup V1_Initial _Setup.sql success 02-04 22:23:00.0 2 2 First Changes SQL V2_First 1279644856 axel _Changes.sql 201602-06 09:18:00.0 现在有了元数据和初始状态，可以开始迁移到更新版本。 3 第 2 章 概述 Flyway 将再次扫描文件系统或应用程序的类路径以进行迁移。根据架构历史记录表检查迁移。如果它们的版本 号低于或等于标记为当前的版本之一，则将被忽略。 剩余的迁移时待处理的迁移：可用但未应用。然后它们按照版本号排序并按顺序执行。架构历史表也会相应的更 新： installed version description type script _rank 1 1 Initial SQL Setup V1_Initial checksum installed installed execution _by _on _time 1996767037 axel 2016- 546 true 127 true 251 true _Setup.sql success 02-04 22:23:00.0 2 2 First Changes SQL V2_First 1279644856 axel _Changes.sql 201602-06 09:18:00.0 3 2.1 Refactoring JDBC V2_1 Changes _Refactoring axel 201602-10 09:18:00.0 依次类推。每当需要扩展数据库时，无论是结构数据（DDL）还是引用数据（DML），只需要创建一个版本号 高于当前版本号的新迁移。下次 Flyway 启动时，它将找到这个版本号并相应的升级数据库。 4 第 3 章 FLYWAY 配置说明 3 第 章 Flyway 配置说明 以 JAVA API 为例。 a. 导入 flyway 的依赖包。 org.flywaydbflyway-core6.4.1 b. 配置迁移文件。 在迁移目录 classpath:/db/migration 下创建迁移文件，文件命名以 V 开头，以.sql 结尾，数字为版本号， 迁移文件版本号后面是两个连续的下划线。 第一个迁移文件 V1__create_person_table.sql create table person( id serial primary key, name text, date date, sex bool, blob blob, clob clob ); 第二个迁移文件 V2__insert_person.sql insert into person(name,date,sex,blob,clob) values('aaa','2020-01-01','f','aaa','bbb'); c. 执行迁移。 普通 java 程序执行以下代码进行迁移： 5 第 3 章 FLYWAY 配置说明 String url = "jdbc:postgresql://localhost:54321/test"; String user = "system"; String password = "123456"; Flyway flyway = Flyway.configure().dataSource(url, user, password).load(); flyway.migrate(); 如果是 springboot 项目，由参数 spring.flyway.enabled 来控制 flyway 的开启，flyway 默认启用，在项目 启动部署后就会自动加载。 spring.flyway.enabled=true 6 第4章 4 第 章 FLYWAY 注意点 Flyway 注意点 a. 适配 Flyway 需要直接使用 pg 形态的驱动，即直接使用 pg 的驱动类（org.postgresql.Driver）和连接串（jdbc: postgresql://localhost:54321/test）。 b. 当前 KingbaseES 在使用 Flyway 过程中，暂不支持 Oracle 模式下的 PL/SQL 语法，如果您有这方面的需求的 话，请联系我们的技服人员。 7 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 8 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 9 服务周期承诺 开方式宣布产品服务终止日期。 10