# 為什麼要進行資料庫版本控制？

現代軟體工程逐漸向持續整合、持續交付演進，軟體一次交付了事的場景逐漸無法滿足複雜多變的業務需求，“如何高效地進行軟體版本控制”成為我們面臨的挑戰。同時，軟體也不是僅僅部署到某一套環境中，而是需要部署到開發、測試、生產以及更多的客戶環境中，“如何一套程式碼適應不同的環境”也成為我們要思考的問題。

![1.png](https://ucc.alicdn.com/pic/developer-ecology/7ae346aad7a54379ac609fbdf84a7e34.png)
一套軟體的副本要部署在不同的環境（圖源：Flyway）

程式碼版本管理工具（Git、SVN 等）和託管平臺（Github、Erda DevOps Platform 等）讓我們能有效地進行程式碼版本管理。越來越豐富的 CI/CD 工具讓我們能定義可重複的構建和持續整合流程，釋出和部署變得簡單清晰。

“**基礎設施即程式碼**”的思想，讓我們可以用程式碼定義基礎設施，從而抹平了各個環境的差異。

可以說，在軟體側我們應對這些挑戰已經得心應手。

但是絕大多數專案都至少包含兩個重要部分：業務軟體，以及業務軟體所使用的資料庫——許多專案資料庫側的版本控制仍面臨亂局：

- 很多專案的資料庫版本控制仍依賴於“人肉維護”，需要開發者手動執行 SQL；
- 環境一多，幾乎沒人搞得清某個環境上資料庫是什麼狀態了；
- database migrations 指令碼沒有統一管理，遺失錯漏時有發生；
- 不確定指令碼的狀態是否應用，也許在這個環境應用了但在另個環境卻沒有應用；
- 指令碼里有一行破壞性程式碼，執行了後將一個表欄位刪除了，資料無法恢復，只能“從刪庫到跑路”；
- ……

為了應對這樣的亂局，我們需要**資料庫版本控制工具**。

資料庫版本控制，即 Database Migration，它能幫你：

- 管理資料庫的定義和遷移歷程
- 在任意時刻和環境從頭建立資料庫至指定的版本
- 以確定性的、安全的方式執行遷移
- 清楚任意環境資料庫處於什麼狀態

從而讓資料庫與軟體的版本管理同步起來，軟體版本始終能對應正確的資料庫版本，同時提高安全性、降低維護成本。

# Erda 如何實踐資料庫版本控制

Erda 是基於多雲架構的一站式企業數字化平臺，為企業提供 DevOps、微服務治理、多雲管理以及快資料管理等雲廠商無繫結的 IT 服務。Erda 既可以私有化交付，也提供了 SaaS 化雲平臺 Erda Cloud，以及開源的社群版。

當你正在閱讀這篇文章時，有無數來自不同組織的應用程式正在 Erda Cloud 或 Erda 私有化平臺的流水線上完成以構建和部署為核心的 CI/CD 流程，無數的程式碼，以這種持續而自動化的方式轉化成服務例項。

Erda 平臺不但接管了這些組織的應用程式的整合、交付，Erda 專案自身的整合也是託管在 Erda DevOps 平臺的。Erda 自身的持續整合和豐富的交付場景要求它能進行安全、高效、可持續的資料庫版本控制，託管在 Erda 上的應用程式也要求 Erda 提供一套完整的資料庫版本控制方案。

Erda 專案使用 Erda MySQL Migrator 作為資料庫版本控制工具，它被廣泛應用於 CI/CD 流程和命令列工具中。
 
## 基本原理

第一次使用 Erda MySQL Migrator 進行資料庫版本控制時會在資料庫中新建一個名為 schema_migration_history 的表，如下如所示：

![2.png](https://ucc.alicdn.com/pic/developer-ecology/811b20115799481bbd6c04008160d19c.png)
schema_migration_history 表的基本結構(部分主要欄位)

Erda MySQL Migrator 每次執行 database migration 時，會對比檔案系統中的 migrations 指令碼和 schema_migration_history 表中的執行記錄，標記出增量的部分。在一系列審查後，Erda MySQL Migrator 將增量的部分應用到目標 database 中。成功應用的指令碼被記錄在案。

## Erda MySQL Migrator 命令列工具

### erda-cli 工具的構建與安裝

`erda-cli` 是 erda 專案命令列工具，它整合了 Erda 平臺安裝、Erda 擴充管理以及開發腳手架。其中 `erda-cli migrate` 命令整合了資料庫版本控制全部功能。

從 erda 倉庫 拉取程式碼到本地，切換到 master 分支，執行以下命令可以編譯erda-cli ：

```
% make prepare-cli
% make cli
```

注意編譯前應確保當前環境已安裝 docker。編譯成功後專案目錄下生成了一個 `bin/erda-cli` 可執行檔案。

### 使用 erda-cli migrate 進行資料庫版本遷移

Erda MySQL Migrator 要求按 `modules/scripts` 兩級目錄組織資料庫版本遷移指令碼，以 erda 倉庫為例：

```
.erda/migrations
├── apim
│   ├── 20210528-apim-base.sql
│   ├── 20210709-01-add-api-example.py
│   └── requirements.txt
... ...
├── cmdb
│   ├── 20210528-cmdb-base.sql
│   ├── 20210610-addIssueSubscriber.sql
│   ├── 20210702-updateMbox.sql
│   └── 20210708-add-manageconfig.sql
└── config.yml
    └── 20200528-tmc-base.sql
```

erda 專案將資料庫遷移指令碼放在 `.erda/migrations` 目錄下，目錄下一層級是按模組名（微服務名）命名的指令碼目錄，其各自下轄本模組所有指令碼。與指令碼目錄同級的，還有一個 config.yml 的檔案，它是 Erda MySQL Migration 規約配置檔案，它描述了 migrations 指令碼所需遵循的規約。

指令碼目錄下按檔名字元序排列著 migrations 指令碼，目前支援 SQL 指令碼和 Python 指令碼。如果目錄下存在 Python 指令碼，則需要用 `requirements.txt` 來描述 Python 指令碼的依賴。

進入 migrations 指令碼所在目錄 `.erda/migrations`，執行 `erda-cli` migrate ：

```
% erda-cli migrate --mysql-host localhost \
    --mysql-username root \
    --mysql-password 123456789 \
    --sandbox-port 3307 \
    --database erda
INFO[0000] Erda Migrator is working                     
INFO[0000] DO ERDA MYSQL LINT....                       
INFO[0000] OK                           
INFO[0000] DO FILE NAMING LINT....                        
INFO[0000] OK                            
INFO[0000] DO ALTER PERMISSION LINT....                 
INFO[0000] OK                     
INFO[0000] DO INSTALLED CHANGES LINT....                
INFO[0000] OK                    
INFO[0000] COPY CURRENT DATABASE STRUCTURE TO SANDBOX.... 
INFO[0014] OK 
INFO[0014] DO MIGRATION IN SANDBOX....                  
INFO[0014] OK                                            
INFO[0014] DO MIGRATION....                             
INFO[0014]                 module=apim
... ...
INFO[0014]                 module=cmdb
INFO[0014] OK
INFO[0014] Erda MySQL Migrate Success !
```

執行 erda-cli migrate 命令

從執行日誌可以看到，命令列執行一系列檢查以及沙盒預演後，成功應用了本次 database migration。我們可以登入資料庫檢視到指令碼的應用情況。

登入 MySQl Server 檢視指令碼應用情況

### 基於 Python 指令碼的 data migration

從上一節我們看到，指令碼目錄中混合著 SQL 指令碼和 Python 指令碼，migrator 對它們一致地執行。Erda MySQL Migrator 在設計之初就決定了單指令碼化的 migration，即一個指令碼表示一次 migration 過程。大部分 database migration 都可以很好地用 SQL 指令碼表達，但仍有些包含複雜邏輯的 data migration 用 SQL 表達則會比較困難。對這類包含複雜業務邏輯的 data migration，Erda MySQL Migrator 支援開發者使用 Python 指令碼。

erda-cli 提供了一個命令列 `erda-cli migrate mkpy` 來幫助開發者建立一個基礎的 Python 指令碼。執行：

```
% erda-cli migrate mkpy --module my_module --name myfeature.py --tables blog,author,info
```

命令生成如下指令碼：

```
"""
Generated by Erda Migrator.
Please implement the function entry, and add it to the list entries.
"""

import django.db.models

class Blog(django.db.models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

class Meta:
        db_table = "blog"

class Author(django.db.models.Model):
    name = models.CharField(max_length=200)
    email = models.EmailField()

class Meta:
        db_table = "author"

class Info(django.db.models.Model):
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)
    headline = models.CharField(max_length=255)
    body_text = models.TextField()
    pub_date = models.DateField()
    mod_date = models.DateField()
    authors = models.ManyToManyField(Author)
    number_of_comments = models.IntegerField()
    number_of_pingbacks = models.IntegerField()
    rating = models.IntegerField()

class Meta:
        db_table = "info"

def entry():
    """
    please implement this and add it to the list entries
    """
    pass

entries: [callable] = [
    entry,
]
```

該指令碼可以分為四個部分：

1. import 匯入必要的包。指令碼中採用繼承了 *django.db.models.Model* 的類來定義庫表，因此需要匯入 *django.db.model* 庫。開發者可以根據實際情況匯入自己所需的包，但由於單指令碼提交的原則，指令碼中不應當匯入本地其他檔案。
2. 模型定義。指令碼中 `class Blog`、 `class Author` 和 `class Entry` 是命令列工具為開發者生成的模型類。開發者可以使用命令列引數 `--tables` 指定要生成哪些模型定義，以便在開發中引用它們。注意，生成這些模型定義類時並沒有連線資料庫，而是根據檔案系統下過往的 migration 所表達的 Schema 生成。生成的模型定義只表示了表結構而不包含表關係，如“一對一”、“一對多”、“多對多”等。如果開發者要使用關聯查詢，應當編輯模型，自行完成模型關係的描述。Django ORM 的模型關係僅表示邏輯層面的關係，與資料庫物理層的關係無關。
3. entry 函式。命令列為開發者生成了一個名為 `entry` 的函式，但是沒有任何函式體，開發者需要自行實現該函式體以進行 data migration。
4. entries，一個以函式為元素的列表，是程式執行的入口。開發者要將實現 data migration 的業務函式放到這裡，只有 entries 中列舉的函式才會被執行。

從以上指令碼結構可以看到，我們選用的 Django ORM 來描述模型和進行 CRUD 操作。

為什麼採用 Django ORM 呢？

因為 Django 是 Python 語言裡最流行的 web 框架之一，Django ORM 也是 Python 中最流行的 ORM 之一，其設計完善、易用、便於二次開發，且有詳盡的文件、豐富的學習材料以及活躍的社群。無論是 Go 開發者還是 Java 開發者，都能在掌握一定的 Python 基礎後快速上手該 ORM。我們透過兩個簡單的例子來了解下如何利用 Django ORM 來進行 CRUD 操作。

**示例 1** 建立一條新記錄。

```
# 示例 1
# 建立一條記錄
def create_a_blog():
    blog = Blog()
    blog.name = "this is my first blog"
    blog.tagline = "this is looong text"
    blog.save()
```

Django ORM 建立一條記錄十分簡單，引用模型類的例項，填寫欄位的值，呼叫 save()方法即可。

**示例 2** 刪除所有標題中包含 "Lennon" 的 Blog 條目。

Django 提供了一種強大而直觀的方式來“追蹤”查詢中的關係，在幕後自動處理 SQL JOIN 關係。它允許你跨模型使用關聯欄位名，欄位名由雙下劃線分割，直到拿到想要的欄位。

```
# 示例 2
# 刪除所有標題中含有 'Lennon' 的 Blog 條目:
def delete_blogs_with_headline_lennon():
    Blog.objects.filter(info__headline__contains='Lennon').delete()
```

最後，別忘了將這兩個函式放到 entries 列表中，不然它們不會被執行。

```
entries: [callable] = [
    create_a_blog,
    delete_blogs_with_headline_lennon,
]
```

可以看到，編寫基於 Python 的 data migration 是十分方便的。`erda-cli migrate mkpy` 命令列為開發者生成了模型定義，引用模型類及其例項可以便捷地運算元據變更，開發只須關心編寫函式中的業務邏輯。

想要進一步瞭解 Django ORM 的使用請檢視文件：

[Django - 執行查詢](https://docs.djangoproject.com/zh-hans/3.2/topics/db/queries/)

## 在 CI/CD 時進行資料庫版本控制

每日凌晨，Erda 上的一條流水線靜靜啟動，erda 倉庫的主幹分支程式碼都會被整合、構建、部署到整合測試環境。開發者一早開啟電腦，登入整合測試環境的 Erda 平臺驗證昨日整合的新 feature 是否正確，發現昨天新合併的 migrations 也一併應用到了整合測試環境。這是怎麼做到的呢 ？

![3.png](https://ucc.alicdn.com/pic/developer-ecology/f0a265b921a2477e8c5f7d3852a7529f.png)
Erda 每日自動化整合流水線（部分步驟）

原來這條流水線每日凌晨拉取 erda 倉庫主幹分支程式碼 -> 構建應用 -> 將構建產物製成部署製品 -> 在整合測試環境執行 Erda MySQL 資料遷移 -> 將製品部署到整合測試環境。**流水線中的 Erda MySQL 資料遷移 節點是整合了 Erda MySQL Migrator 全部功能的 Action，是 Erda MySQL Migrator 在 Erda CI/CD 流水線中的應用**。

Erda MySQL Migrator 除了可以作為 Action 編排在流水線中，還可以脫離 Erda 平臺作為命令列工具單獨使用。

# Erda MySQL Migrator 其他特性

## 規約檢查

成熟的團隊一般都會制定程式碼開發規約。Erda MySQL Migrator 支援開發者團隊透過配置規約檔案，來約定 SQL 指令碼規範，如啟用和禁用特定的 SQL 語句、約束表名與欄位名格式、約束欄位型別等。

比如要求 `id` 欄位必須是 varchar(36) 或 char(36)，可以新增如下配置：

```
- name: ColumnTypeLinter
  meta:
    columnName: id
    types:
      - type: varchar
        flen: 36
      - type: char
        flen: 36
```

比如要求表名必須以 "erda_" 開頭，可以新增如下配置：

```
- name: TableNameLinter
  alias: "TableNameLinter: 以 erda_ 開頭僅包含小寫英文字母數字下劃線"
  white:
    committedAt:
      - "<20220215"  ## 此處表示對提交時間早於2022年2月5日的檔案不作此條規約要求
  meta:
    patterns:
      - "^erda_[a-z0-9_]{1,59}"
```

關於如何編寫規約配置檔案的更新資訊見連結:
https://github.com/erda-project/erda-actions/tree/master/actions/erda-mysql-migration/1.0-57#%E8%A7%84%E7%BA%A6%E9%85%8D%E7%BD%AE

### 使用命令列工具進行規約檢查

`erda-cli migrate lint` 命令可以檢查指定目錄下所有指令碼的 SQL 語句是否符合規約。開發者在編寫 migration 時用該命令來預先檢查，避擴音交不合規了不合規的指令碼。

例如開發者在 SQL 指令碼中編寫了如下語句：

```
alter table dice_api_assets add column col_name varchar(255);
```

執行規約檢查：

```
% erda-cli migrate lint

2021/07/19 17:39:43 Erda MySQL Lint the input file or directory: .
apim/20210715-01-feature.sql:
    dice_api_assets:
        - 'missing necessary column definition option: COMMENT'
        - 'missing necessary column definition option: NOT NULL'

apim/20210715-01-feature.sql [lints]
apim/20210715-01-feature.sql:1: missing necessary column definition option: COMMENT: 
~~~> alter table dice_api_assets add column col_name varchar(255);

apim/20210715-01-feature.sql:1: missing necessary column definition option: NOT NULL: 
~~~> alter table dice_api_assets add column col_name varchar(255);
```

使用命令列工具進行本地規約檢查

可以看到命令列返回了檢查報告，指出了某個檔案中存在不合規的語句，並指出了具體的檔案、行號、錯誤原因等資訊。上面示例中指出了這條語句有兩條不合規處：一是新增列時，應當有列註釋，此處缺失；二是新增的列應當是 NOT NULL 的，此處沒有指定。

### 使用 CI 工具進行規約檢查

開發者自行使用命令列工具自檢是合規檢查的第一道關卡。在提交的程式碼合併到 erda 倉庫主幹分支前，PR 觸發的 CI 流程會利用命令列工具檢查 migrations 合規性則是第二道關卡。當提交包含不合規的 SQL 的 PR 時，CI 就會失敗：

![4.png](https://ucc.alicdn.com/pic/developer-ecology/35ec77fc95f0480eb7b718c139349d9e.png)
Github CI：Erda MySQL Lint 失敗提示

### 使用 Erda MySQL Migration Lint Action 進行規約檢查

對於託管在 Erda DevOps 平臺的專案，可以使用 Erda MySQL Migration Lint Action 進行規約檢查。前文中的 Erda MySQL 資料遷移 Action 已經包含了規約檢查功能，所以從功能上來說，Erda MySQL Migration Lint Action 可以看做 Erda MySQL 資料遷移 Action 的一部分。下圖是使用 Erda MySQL Migration Lint Action 編排的流水線檢查指令碼合規性的示例。

![5.jpeg](https://ucc.alicdn.com/pic/developer-ecology/c3e72bdcdc474dcebbbef692b45dd7c7.jpeg)
使用 Erda MySQL Migration Lint Action 編排流水線檢查指令碼合規性

示例中該 Action 失敗，開啟 Action 日誌可以檢視具體失敗原因。

## 沙盒與 Dryrun

引入沙盒是為了在將 migrations 應用到目標資料庫前進行一次模擬預演，期望將問題的發現提前，防止將問題 migration 應用到了目標資料庫中。對 Erda 這樣的有豐富的交付場景的專案而言，在 migrate 前先進行一道預演是十分有意義的。這是 Erda MySQL Migrator 根據自身實際設計的，是 Flyway 等工具所不具備的。

Erda MySQL Migrator 可以配置僅在沙盒中而不在真實的 MySQL Server 中執行執行 migration，從而達到 Dryrun 的目的。

## 檔案篡改檢查與修訂機制

Erda MySQL Migrator 不允許篡改已應用過的檔案。之所以這樣設計是因為一旦修改了已應用過的指令碼，那麼程式碼與真實資料庫狀態就不一致了。如果要修改表結構，應當增量地提交新的 migrations。這是一種常見的做法，Flyway 等工具也會對已執行的檔案進行檢查。

但實際生產中，“絕不修改過往檔案”這種理想狀態很難達到，Erda MySQL Migrator 提供了一種修訂機制。當使用者想修改一個檔名為“some-feature.sql”過往檔案時，他應該修改該檔案，並提交一個名為“patch-some-feature.sql”的包含了修改內容的檔案到 .patch 目錄中。

## 日誌收集

Erda MySQL Migrator 在 debug 模式下，會列印所有執行執行過程和 SQL 的標準輸出。除此之外，它還可以將純 SQL 輸出到指定目錄的日誌檔案中。

# 獲取工具
 
## erda-cli 下載地址

**Mac**

http://erda-release.oss-cn-hangzhou.aliyuncs.com/cli/mac/erda-cli

**Linux**

http://erda-release.oss-cn-hangzhou.aliyuncs.com/cli/linux/erda-cli

*注意：以上 erda-cli 僅用於 amd64 平臺，其他平臺請按文中介紹的安裝方式自行構建。*

## 原始碼地址

Erda MySQL MIgrator Action 原始碼地址
https://github.com/erda-project/erda-actions/tree/master/actions/erda-mysql-migration/1.0-57

這麼強？！Erda MySQL Migrator：持續整合的資料庫版本控制

相關文章

最新文章