Databricks 的 Schema 管理与 Flyway

飞架构变更管理

作者 : Kamalendu Biswas, 高级解决方案架构师 @ Databricks

数据库版本管理是什么？

数据库版本管理是现代软件开发中的关键实践，允许团队追踪、管理和控制数据库架构和数据随时间的变化情况。它涉及为不同数据库状态分配唯一的版本号或标签，使开发人员能够有效协作，如有需要可以回滚更改，并在各种环境中保持一致性。数据库版本管理工具通常使用迁移脚本或变更日志来记录修改，允许精确追踪谁进行了修改、何时以及为何进行修改。这种方法使部署更加顺畅，故障排除更为方便，并且在处理复杂的数据库系统时可以更好地协调团队成员。通过实施数据库版本管理，组织可以降低与数据库更改相关的风险，改进开发工作流程，并最终交付更可靠和高效的数据库驱动应用。

数据库版本管理工具：Flyway

Flyway 是一个广受欢迎的数据库迁移工具，帮助管理和跟踪数据库模式的变更。

Flyway简介

Flyway 是一个基于 Java 的工具，使用 SQL 脚本来进行数据库模式的迁移。主要功能有：

• 数据库模式的版本控制功能
• 支持多种数据库类型，并提供Databricks社区支持
• 使用带有版本号的SQL迁移脚本
• 与构建工具和框架（如Maven、Gradle和Spring）无缝集成
• 提供命令行界面和Java API

Flyway流程

Flyway 数据库迁移引擎是一个命令行工具，允许你自动化部署数据库更新，同时保持对数据库版本的严格控制。它通过执行一系列版本化的迁移脚本，将数据库从一个版本迁移到另一个版本。当这些迁移应用到数据库时，新的版本号会被记录在唯一的模式版本历史表中。

架构迁移

每个迁移脚本的文件名中都包含目标版本号以及描述。在这个例子中，存在四个迁移脚本，对应版本 V1.01 到 V1.0.3（使用 主版本.小版本.修订版本 的语义化版本系统，例如：主版本.小版本.修订版本）。当前数据库版本在模式版本历史表中记录为 V1.0.1，这意味着 V1.0.0 和 V1.0.1 的脚本已经应用。确认这些脚本自应用后未被修改后，Flyway 会自动运行 V1.0.2 和 V1.0.3 的脚本，将数据库升级到最新版本。

与Databricks集成 前提条件

（注：此处新增的换行是为了匹配英文原文的间距，并在"前提条件"后添加了冒号以匹配原文的标点符号。）

# 前提条件：

• 在开始使用Flyway进行数据库版本控制之前，首先要对它的核心概念和方法有一个基本的理解。第一步是查阅Flyway的“入门指南”文档。
• 已启用的Databricks统一目录能够使工作区访问Databricks SQL仓库。

• 确定项目的目录和模式。在这种情况下，我们将使用：

• 默认目录名称 : flyway_demo ; 这将会设置在JDBC URL中。

• 默认模式名称 : default ; Flyway将用来维护历史表。

• 模式 : bronze , silver , gold ; 不同的模式用于维护不同的数据库对象。

项目搭建 - 开始吧！ Databricks 设置

在你的 Databricks 工作区中建立默认目录和模式架构。

如果不存在 flyway_demo 数据库，则创建 flyway_demo 数据库；
如果不存在 flyway_demo.bronze 数据库，则创建 flyway_demo.bronze 数据库；
如果不存在 flyway_demo.silver 数据库，则创建 flyway_demo.silver 数据库；
如果不存在 flyway_demo.gold 数据库，则创建 flyway_demo.gold 数据库；

DDL 目录信息和创建模式的结果

2. 为您的 Databricks 工作区创建一个个人访问令牌（PAT）。

3. 获取你的 Databricks SQL 仓库的 JDBC URL 并设置默认数据库目录。

一个示例 JDBC URL  
如下：
jdbc:databricks://<host-name>:443/<default-schema>;transportMode=http;ssl=1;AuthMech=3;httpPath=<warehouse-http-path>;ConnCatalog=<default-catalog>;EnableArrow=0;

注意：如果未提供任何值，连接将默认使用“default”模式名。请确保默认模式名已存在，或者根据需要在JDBC URL中进行相应的修改。

Flyway 配置

1. 下载 Flyway的最新社区版。比较企业版的功能，如果这些额外功能符合您的项目或组织需求，如有需要，可以考虑购买企业版的许可。

或者，如果你用的是 Mac，你可以通过 Homebrew（一个包管理器）来下载它。

使用brew安装flyway数据库迁移工具
brew install flyway

2. 创建您的项目或克隆这个仓库 - databricks-flyway-demo

3. 配置 /flyway/conf/flyway.toml:。一些最重要的配置如下：

    [environments.dev]  
    url = "<jdbc-url>;ConnCatalog=<default-catalog>;EnableArrow=0;"  
    user = "token"  
    password = "<token>"  
    schemas = [ "bronze", "silver", "gold" ]  

    [flyway]  
    environment="dev"   
    locations = [ "filesystem:./flyway/sql" ]  
    mixed = true  
    outOfOrder = true  
    validateMigrationNaming = true  
    defaultSchema = "默认架构"  
    baselineOnMigrate = "基线迁移启动"  

注意：JDBC URL 尝试连接到名为“default”的数据库模式。确保您的目录中有此数据库模式，或者在 URL 中将“default”替换为现有的模式名。

1. locations 是指向你项目中包含迁移脚本的 sql 文件夹的路径，例如 locations。
2. baselineOnMigrate = true 对现有数据库进行基线操作，排除所有到 baselineVersion 包括基线版本在内的迁移。更多细节请参阅 基线。
3. 查看所有 配置参数，并根据需要进行相应的调整。
4. 通过运行以下命令来验证设置，以确保一切配置正确无误。

运行迁移命令，配置文件路径为：/databricks-flyway-demo/flyway/conf/flyway.toml

    flyway migrate -configFiles="/databricks-flyway-demo/flyway/conf/flyway.toml"

    Flyway OSS 版本 10.17.3，由 Redgate 开发  

    请参阅发布说明：https://rd.gt/416ObMi  
    Databricks 是一个由社区贡献的数据库，详情请参阅：https://rd.gt/3SXtLDt  
    数据库：jdbc:databricks://adb-<workspace-id>.11.azuredatabricks.net:443/default;transportMode=http;ssl=1;AuthMech=3;httpPath=/sql/1.0/warehouses/d1184b8c2a8a87eb;ConnCatalog=flyway_demo;EnableArrow=0; (SparkSQL 3.1)  
    成功验证了 4 项迁移（耗时 00:02.918s）

迁移配置

1. 在 /sql 目录中创建第一个迁移，并确保其命名唯一。如前所述，Flyway 建议使用 主版本、次版本和修订 的命名语义。可以在文件名中添加 UNIX 纪元时间以确保其唯一性。

运行以下命令来获取当前时间的Unix时间戳：`date +"%s"`。输出结果为：1725742173。1725742173对应的是2025年1月1日 00:00:01。

迁移文件名：V001_1725742173_创建原始表格.sql

     --原始客户表  
    CREATE TABLE IF NOT EXISTS bronze.raw_customers (  
      customer_id INT,  
      customer_name STRING,  
      phone_number STRING,  
      email_address STRING,  
      address STRING,  
      post_code STRING,  
      city STRING,  
      country STRING,  
      platinum_flag INT,  
      record_created_at TIMESTAMP  
    )  
    ;  

    --原始订单表  
    CREATE TABLE IF NOT EXISTS bronze.raw_orders (  
      order_id INT,  
      order_date DATE,  
      customer_name STRING,  
      product_id INT,  
      product_name STRING,  
      quantity DECIMAL,  
      total_amount DECIMAL,  
      record_created_at TIMESTAMP  
    )  
    ;

2. 可以使用以下命令来执行第一个迁移:

# 原始命令应在此处替换

（将 # 原始命令应在此处替换 删除，以符合原文的准确性和流畅性要求。）

最终修正如下：

2. 可以使用以下命令来执行第一个迁移:

（直接展示命令，不包含替换提示。）

flyway migrate -configFiles="/databricks-flyway-demo/flyway/conf/flyway.toml"` # 这条命令用于迁移数据库配置文件

2.a Flyway将在defaultSchema中创建flyway_schema_history表来记录所有更改。

2.b 迁移脚本中的 SQL 语句将会在 Databricks SQL 中运行。

2.c Flyway 会更新 flyway_schema_history 表包含迁移详情。

模式升级查询历史

历史记录

这是来自flyway迁移的表DDL更新

1. 创建第二个迁移脚本来加载原始数据。这包括一次性加载、手动更新或任何必要的DML操作。

迁移文件名：V002_1725742215__插入原始数据.sql

4. 再次运行 flyway migrate 命令，并等待数据插入操作完成。数据插入完成后，你将在 flyway_schema_history 表中看到一条新的迁移记录。

5. 创建一个新的迁移文件 V003_1725742392__create_silver_tables.sql，用于在银色架构中创建两个暂存表 stg_customer 和 stg_order，并执行 flyway 迁移。

请注意，这些表中没有主键。我们将创建一个新的迁移文件，为这些表添加主键。

6. 创建一个新的迁移文件 V004_1725753080__add_pk_silver_tables.sql ，以将主键添加到这些暂存表中，然后运行 flyway 迁移。

ALTER TABLE silver.stg_customer ADD CONSTRAINT stg_customer_pk PRIMARY KEY(customer_id);  
ALTER TABLE silver.stg_order ADD CONSTRAINT stg_order_pk PRIMARY KEY(order_id);

很遗憾的是，迁移失败了，因为主键字段需要设置为 NOT NULL，而我们在创建表时忘记设置了这一点。请注意，迁移的历史记录已经更新为 false；我们需要修复这个问题。所以，我们来修复这个迁移问题吧。

无效 — NOT NULL

迁移失败的日志

7. 修改迁移文件 V004_1725753080__add_pk_silver_tables.sql：将所需的列设置为 NOT NULL。

    ALTER TABLE silver.stg_customer ALTER COLUMN customer_id SET NOT NULL; -- 设置customer_id为非空
    ALTER TABLE silver.stg_order ALTER COLUMN order_id SET NOT NULL; -- 设置order_id为非空

    ALTER TABLE silver.stg_customer ADD CONSTRAINT stg_customer_pk PRIMARY KEY(customer_id); -- 为customer_id添加主键约束
    ALTER TABLE silver.stg_order ADD CONSTRAINT stg_order_pk PRIMARY KEY(order_id); -- 为order_id添加主键约束

8., 运行 flyway migrate 命令以重新运行迁移过程。哎呀！我们出了点问题；我们忘了修复 flyway 的历史记录。

9. 运行 flyway repair 命令来修复历史记录。

运行修复命令：flyway repair -configFiles="/databricks-flyway-demo/flyway/conf/flyway.toml"

10. 再次运行 flyway migrate 命令以重新运行修正后的迁移。此时你将看到 ALTER 语句在 Databricks SQL 上运行。flyway_schema_history 表也会被更新为最新状态。

正在运行的ALTER命令

成功迁移记录

11. 银色的 PK 舞台表已经更新了 PKs。

更新了表格啦！

1. 最后，我们进行了几次迁移以测试对Databricks功能（如液体聚类、删除向量、预测性优化、流表、物化视图等）的支持。

V005_1725864865__create_liquid_table.sql

V006_1725865484__alter_table_properties.sql

V007_1725866341__create_streaming_table.sql

V008_1725866372__创建物化视图.sql

CI/CD

为了简单起见，我们可以使用官方的Redgate Flyway GitHub Action来展示如何使用数据库迁移设置持续集成(CI)流程。值得注意的是，这个GitHub Action还没有提供所有配置选项的完全列表。不过，您可以使用官方的Flyway Docker镜像来自定义持续集成(CI)流程，以满足您的具体需求。

Flyway社区关于Github Actions限制的讨论在这里阅读。

结论:

在这篇博客里，我们成功创建并展示了一个项目，演示如何在 Databricks 中使用 Flyway 社区版有效地管理数据库版本。值得注意的是，这种集成是由社区管理和维护的，依赖于开发人员和用户的支持来增强其功能并解决可能出现的问题。

我们也简要探讨了该项目的CI/CD方面，重点是利用GitHub Actions来自动化和简化数据库版本管理流程。我们还可以将这些更改推进到更高层级的环境，例如QA或生产。