Go Database

安裝

# golang-migrate
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# goose
go install github.com/pressly/goose/v3/cmd/goose@latest

命名慣例

檔案結構

migrations/
├── 20260108120000_create_users_table.up.sql
├── 20260108120000_create_users_table.down.sql
├── 20260108130000_add_email_index.up.sql
├── 20260108130000_add_email_index.down.sql
├── 20260109100000_alter_orders_add_status.up.sql
└── 20260109100000_alter_orders_add_status.down.sql

命名格式

格式：YYYYMMDDHHMMSS_<description>.<up|down>.sql

規則：

• 時間戳：使用 UTC 時間，確保唯一性與排序
• 描述：使用蛇形命名法（snake_case），簡潔描述變更
• 必須成對：每個 .up.sql 都有對應的 .down.sql

範例：

# 正確
20260108120000_create_users_table.up.sql
20260108120000_create_users_table.down.sql

# 錯誤
2026-01-08-CreateUsers.sql          # 格式錯誤
create_users.up.sql                 # 缺少時間戳
20260108120000_AddUserEmail.up.sql  # 應使用 snake_case

Migration 內容範例

CREATE TABLE

20260108120000_create_users_table.up.sql：

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);

20260108120000_create_users_table.down.sql：

DROP INDEX IF EXISTS idx_users_email;
DROP TABLE IF EXISTS users;

ALTER TABLE

20260109100000_alter_orders_add_status.up.sql：

-- 新增欄位（帶預設值避免 NULL 問題）
ALTER TABLE orders
ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'pending';

-- 新增索引
CREATE INDEX idx_orders_status ON orders(status);

20260109100000_alter_orders_add_status.down.sql：

DROP INDEX IF EXISTS idx_orders_status;

ALTER TABLE orders
DROP COLUMN IF EXISTS status;

版本控制

規範

1. Migration 檔案必須納入 Git
2. 禁止修改已執行的 migration（新增新檔案修正）
3. 復原（down）必須與 up 對應，確保可回退
4. 團隊共享：所有開發者使用相同的 migration 版本

驗證 Migration 一致性

錯誤做法：

-- ❌ 修改已執行的 migration
-- 20260108120000_create_users_table.up.sql
CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) NOT NULL,
    -- 後來加上的欄位（不應修改已執行的 migration）
    phone VARCHAR(20) NOT NULL
);

正確做法：

-- ✅ 新增一個新的 migration
-- 20260110150000_add_phone_to_users.up.sql
ALTER TABLE users
ADD COLUMN phone VARCHAR(20);

CI/CD 整合

執行時機

原則：

• Migration 應在應用啟動前執行（init container 或 pre-deploy hook）
• 禁止在應用程式 main() 中執行 migration（避免多副本競爭）

Kubernetes 範例（Init Container）

# deployment.yaml
apiVersion: apps/v1