Posted inDatabase

Database Migration với Liquibase: Quản lý phiên bản Schema, Rollback an toàn và tự động hóa CI/CD

Hiếm có điều gì dễ làm đổ bể một đợt phát hành production hơn là việc cập nhật schema thủ công. Chắc hẳn chúng ta đều từng trải qua nỗi hoang mang trên Slack lúc 11 giờ đêm: ai đó quên chạy script ALTER TABLE trên môi trường staging, hoặc một lệnh đổi tên cột không đúng thời điểm đã kích hoạt cơ chế lock làm khóa chặt 10 triệu bản ghi, khiến API thanh toán bị sập hoàn toàn.

Liquibase giúp loại bỏ canh bạc rủi ro này. Tương tự như giải pháp tự động hóa migration database schema với Flyway, công cụ này xử lý các thay đổi schema của database tương tự như mã nguồn ứng dụng: được quản lý phiên bản trên Git, được kiểm duyệt kỹ càng qua pull request và được triển khai qua các pipeline tự động. Các cơ sở dữ liệu quan hệ như PostgreSQL và MySQL luôn đòi hỏi quy trình versioning nghiêm ngặt trước khi các bản vá tạm thời biến hệ thống thành một mớ bòng bong không thể gỡ rối.

Bắt đầu nhanh: Bản Migration đầu tiên của bạn trong 5 phút

Bạn chỉ cần hai file cấu hình nhỏ gọn để bắt đầu triển khai ngay. Hoàn toàn không cần phải đại tu database hiện có.

1. Cài đặt Liquibase CLI

Cài đặt file thực thi thông qua Homebrew, trình quản lý gói hoặc tải trực tiếp từ kho lưu trữ chính thức:

# macOS
brew install liquibase

# Kiểm tra cài đặt
liquibase --version

2. Cấu hình thông tin kết nối Database

Tạo file liquibase.properties tại thư mục gốc của dự án. File này sẽ chỉ dẫn cho Liquibase biết database mục tiêu nằm ở đâu và changelog nào cần được thực thi:

changeLogFile=changelog.xml
url=jdbc:postgresql://localhost:5432/appdb
username=postgres
password=secret
driver=org.postgresql.Driver
classpath=/path/to/postgresql-42.7.2.jar

3. Viết ChangeSet đầu tiên

Liquibase tổ chức các thao tác biến đổi schema thành các ChangeSet nằm bên trong một file changelog gốc. Hãy tạo file changelog.xml:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
    http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <changeSet id="001-create-users-table" author="alex">
        <createTable tableName="users">
            <column name="id" type="BIGINT" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="email" type="VARCHAR(255)">
                <constraints unique="true" nullable="false"/>
            </column>
            <column name="created_at" type="TIMESTAMP" defaultValueComputed="CURRENT_TIMESTAMP"/>
        </createTable>
        <rollback>
            <dropTable tableName="users"/>
        </rollback>
    </changeSet>

</databaseChangeLog>

4. Thực thi Migration

Chạy lệnh migration trực tiếp từ terminal của bạn:

liquibase update

Liquibase sẽ kết nối tới PostgreSQL, tạo bảng users và ghi lại lịch sử thực thi vào một sổ cái kiểm toán (audit ledger). Giờ đây, schema của bạn đã được quản lý như mã nguồn.

Bên dưới hệ thống: Cách Liquibase theo dõi trạng thái Schema

Sau khi chạy liquibase update một lần, bạn sẽ thấy hai bảng theo dõi tự động xuất hiện trong schema của mình:

  • DATABASECHANGELOG: Lịch sử kiểm toán. Mỗi ChangeSet đã áp dụng sẽ được ghi lại tại đây cùng với định danh duy nhất, mốc thời gian thực thi, thứ tự chạy và mã checksum MD5.
  • DATABASECHANGELOGLOCK: Cổng kiểm soát đồng thời. Một cờ boolean duy nhất (LOCKED) đảm bảo rằng chỉ có một tiến trình được phép áp dụng migration tại một thời điểm. Điều này ngăn ngừa xung đột dữ liệu (race condition) khi có 4 Kubernetes replica cùng khởi động một lúc.

Định danh và Checksum

Liquibase xác định từng ChangeSet dựa trên ba thuộc tính: id, author và đường dẫn file changelog. Khi bạn thực hiện lệnh cập nhật:

  1. Liquibase sẽ truy vấn DATABASECHANGELOG để kiểm tra xem khóa tổng hợp (id, author, filepath) đã tồn tại hay chưa.
  2. Nếu tìm thấy, hệ thống sẽ tính mã băm nội dung file ChangeSet trên máy cục bộ và so sánh mã băm MD5 đó với bản ghi trong bảng. Nếu trùng khớp, Liquibase sẽ bỏ qua không chạy lại.
  3. Nếu ai đó chỉnh sửa một ChangeSet đã được áp dụng trước đó, Liquibase sẽ dừng lại ngay lập tức với lỗi ValidationFailedException. Cơ chế này chặn đứng tình trạng trôi dạt cấu hình ngầm (configuration drift) trước khi câu lệnh SQL lỗi kịp chạm tới môi trường production.

Định dạng ChangeSet: XML, YAML hay Formatted SQL?

XML và YAML mang lại khả năng linh hoạt độc lập với cơ sở dữ liệu, tự động tạo ra cú pháp phù hợp cho PostgreSQL, MySQL hay Oracle ở phía sau. Tuy nhiên, các đội ngũ kỹ sư thường chuộng formatted SQL hơn để dễ đọc và rõ ràng khi review code:

--liquibase formatted sql

--changeset alex:002-add-user-status
ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'ACTIVE';
--rollback ALTER TABLE users DROP COLUMN status;

Formatted SQL giúp đội ngũ của bạn kiểm soát chính xác từng từ khóa đặc thù của database. Hãy sử dụng XML hoặc YAML khi phát triển các sản phẩm SaaS multi-tenant cần hỗ trợ đồng thời nhiều nhà cung cấp database khác nhau.

Các Pattern phòng vệ: Preconditions, Contexts và Rollbacks

Môi trường production thường kéo theo nhiều phức tạp như migration dữ liệu cồng kềnh, dữ liệu mẫu phục vụ kiểm thử và sự trôi dạt trạng thái ngoài dự tính.

Preconditions (Điều kiện tiên quyết)

Preconditions giúp xác thực trạng thái database trước khi một ChangeSet được chạy. Nếu một index đã tồn tại hoặc một cột cũ bị thiếu, bạn có thể chọn bỏ qua một cách an toàn thay vì làm hỏng toàn bộ đợt deploy:

<changeSet id="003-add-profile-bio" author="alex">
    <preConditions onFail="MARK_RAN">
        <not>
            <columnExists tableName="profiles" columnName="bio"/>
        </not>
    </preConditions>
    <addColumn tableName="profiles">
        <column name="bio" type="TEXT"/>
    </addColumn>
</changeSet>

Nhắm mục tiêu môi trường với Contexts

Bạn có thể cần 50 bản ghi khách hàng giả lập trên môi trường staging nội bộ, nhưng tuyệt đối không được đưa lên production. Contexts giúp phân vùng các đợt migration của bạn:

<changeSet id="seed-dev-users" author="alex" context="dev,test">
    <insert tableName="users">
        <column name="email" value="[email protected]"/>
    </insert>
</changeSet>

Thực thi có chọn lọc bằng cách truyền cờ context tương ứng:

liquibase --contexts=dev update

Thực hiện Rollback an toàn

Khi một bản cập nhật gây ra hiện tượng khóa bảng ngoài ý muốn hoặc phát sinh lỗi, Liquibase có thể rollback theo số lượng, theo tag hoặc theo mốc thời gian chỉ định:

# Rollback ChangeSet gần nhất
liquibase rollbackCount 1

# Đánh tag trạng thái hiện tại trước khi deploy, sau đó revert nếu canary check thất bại
liquibase tag v2.4.0
liquibase rollback v2.4.0

Tuyệt đối không chạy rollback mù quáng trên production. Song song với việc duy trì pipeline tự động restore và kiểm tra tính toàn vẹn database để sẵn sàng ứng cứu sự cố, hãy luôn xem trước chính xác câu lệnh SQL mà Liquibase sẽ thực thi:

liquibase rollbackCountSQL 1 > rollback_preview.sql

Tự động hóa CI/CD & Best Practices trên Production

Việc chạy migration trực tiếp từ máy cá nhân tiềm ẩn rủi ro lệch phiên bản và lộ thông tin đăng nhập. Bên cạnh việc thiết lập pipeline kiểm thử database với Testcontainers để phát hiện lỗi sớm, việc tích hợp Liquibase vào CI/CD giúp quá trình nâng cấp database diễn ra hoàn toàn tự động và có thể kiểm toán rõ ràng.

GitHub Actions Workflow

Workflow dưới đây sẽ kiểm tra các ChangeSet đang chờ và thực thi migration mỗi khi có lượt push vào nhánh main:

name: Database Migration

on:
  push:
    branches: [ main ]
    paths:
      - 'db/changelogs/**'

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout mã nguồn
        uses: actions/checkout@v4

      - name: Cài đặt Liquibase
        uses: liquibase-github-actions/setup-liquibase@v1
        with:
          liquibaseVersion: '4.27.0'

      - name: Kiểm tra các thay đổi đang chờ
        run: |
          liquibase \
            --changeLogFile=db/changelogs/master.xml \
            --url="${{ secrets.STAGING_DB_URL }}" \
            --username="${{ secrets.STAGING_DB_USER }}" \
            --password="${{ secrets.STAGING_DB_PASS }}" \
            status --verbose

      - name: Chạy cập nhật
        run: |
          liquibase \
            --changeLogFile=db/changelogs/master.xml \
            --url="${{ secrets.STAGING_DB_URL }}" \
            --username="${{ secrets.STAGING_DB_USER }}" \
            --password="${{ secrets.STAGING_DB_PASS }}" \
            update

Quy tắc thực chiến để phát hành không gián đoạn (Zero-Downtime)

  • Không bao giờ chỉnh sửa một ChangeSet đã áp dụng: Khi một ChangeSet đã chạy trên staging hoặc production, mã checksum của nó sẽ bị khóa chặt. Nếu cần nới rộng một cột từ VARCHAR(50) lên VARCHAR(100), hãy tạo một ChangeSet mới.
  • Áp dụng pattern Expand-Contract: Tránh xóa hoặc đổi tên các cột đang hoạt động trong cùng một đợt phát hành. Trước tiên, hãy thêm cột mới và deploy mã nguồn hỗ trợ ghi đồng thời vào cả hai trường (dual-write). Bù đắp dữ liệu (backfill) cho các dòng cũ một cách bất đồng bộ. Tiếp theo, chuyển hướng các câu truy vấn đọc sang cột mới. Cuối cùng, mới tiến hành xóa cột cũ trong một đợt phát hành kế tiếp.
  • Cấu trúc changelog theo dạng module: Tránh các file changelog dài tới 5.000 dòng. Hãy gom nhóm các migration theo từng đợt phát hành (ví dụ: v1.2/01-orders.xml) và liên kết chúng thông qua thẻ <include file="..."/> trong file master.xml cha.
  • Luôn viết lệnh rollback tường minh: Cơ chế tự động đảo ngược migration chỉ hoạt động với các câu lệnh DDL đơn giản như createTable. Các truy vấn SQL phức tạp, đổi tên bảng và bù dữ liệu đều đòi hỏi bạn phải tự tay viết các khối <rollback> chi tiết.
  • Tránh khóa bảng đối với các bảng lớn: Chạy CREATE INDEX trên một bảng có 20 triệu dòng có thể làm khóa thao tác ghi trong suốt 15 phút. Hãy sử dụng các lệnh không gây khóa bảng như CREATE INDEX CONCURRENTLY của PostgreSQL hoặc ALGORITHM=INPLACE của MySQL bên trong các ChangeSet formatted SQL.
Share:
Tags: