golang-database

Name: golang-database
Author: samber

Go 資料庫最佳實務

Go 的 database/sql 為資料庫存取提供了堅實的基礎。在其上使用 sqlx 或 pgx 以獲得更好的操作體驗 — 永遠不要使用 ORM。

使用 sqlx 或 pgx 時，請參考該函式庫的官方文件和程式碼範例以取得最新的 API 簽名。

最佳實務摘要

使用 sqlx 或 pgx，不要用 ORM — ORM 隱藏 SQL，產生不可預測的查詢，並使除錯更困難
查詢必須使用參數化佔位符 — 絕不要將使用者輸入串接到 SQL 字串中
Context 必須傳遞給所有資料庫操作 — 使用 *Context 方法變體（QueryContext、ExecContext、GetContext）
sql.ErrNoRows 必須明確處理 — 使用 errors.Is 區分「找不到」與真正的錯誤
Rows 必須在迭代後關閉 — 在 QueryContext 呼叫後立即使用 defer rows.Close()
絕不要對不傳回行的陳述使用 db.Query — Query 傳回 *Rows，必須關閉；如果忘記，連線會洩漏回池中。請使用 db.Exec
對多陳述操作使用交易 — 將相關寫入包裝在 BeginTxx/Commit 中
在讀取打算修改的資料時使用 SELECT ... FOR UPDATE — 防止競爭條件
設定自訂隔離層級 — 當預設的 READ COMMITTED 不足時（例如，金融操作使用可序列化）
使用指標欄位（*string、*int）或 sql.NullXxx 型別處理可為 NULL 的欄位
必須設定連線池 — SetMaxOpenConns、SetMaxIdleConns、SetConnMaxLifetime、SetConnMaxIdleTime
使用外部工具進行遷移 — golang-migrate 或 Flyway，絕不要用手寫或 AI 產生的遷移 SQL
以合理的大小進行批次操作 — 不要逐行（太多往返），也不要一次數百萬行（鎖定和記憶體）
絕不要建立或修改資料庫綱要 — 在玩具資料上看起來正確的綱要可能在真實生產負載下產生熱點、鎖定競爭或遺失索引。綱要設計需要理解資料量、存取模式和生產限制，而 AI 並不具備這些
避免隱藏的 SQL 功能 — 不要在應用程式程式碼中依賴觸發器、檢視、具體化檢視、預存程序或列級安全性

函式庫選擇

函式庫	最適合	結構掃描	PostgreSQL 專用
`database/sql`	可攜性、最小依賴	手動 `Scan`	否
`sqlx`	多資料庫專案	`StructScan`	否
`pgx`	PostgreSQL（快 30-50%）	`pgx.RowToStructByName`	是（COPY、LISTEN、陣列）
GORM/ent	避免	魔法	被抽象化

為什麼不使用 ORM：

不可預測的查詢產生 — 在程式碼中看不到的 N+1 問題
魔法鉤子和回呼（BeforeCreate、AfterUpdate）使除錯更困難
綱要遷移與應用程式程式碼耦合
學習 ORM API 比學習 SQL 更難，而且抽象會洩漏

參數化查詢

// ✗ 非常糟糕 — SQL 注入漏洞
query := fmt.Sprintf("SELECT * FROM users WHERE email = '%s'", email)

// ✓ 良好 — 參數化（PostgreSQL）
var user User
err := db.GetContext(ctx, &user, "SELECT id, name, email FROM users WHERE email = $1", email)

// ✓ 良好 — 參數化（MySQL）
err := db.GetContext(ctx, &user, "SELECT id, name, email FROM users WHERE email = ?", email)

動態 IN 子句

query, args, err := sqlx.In("SELECT * FROM users WHERE id IN (?)", ids)
if err != nil {
    return fmt.Errorf("building IN clause: %w", err)
}
query = db.Rebind(query) // 根據驅動程式調整佔位符
err = db.SelectContext(ctx, &users, query, args...)

動態欄位名稱

絕不要從使用者輸入中內插欄位名稱。使用允許清單：

allowed := map[string]bool{"name": true, "email": true, "created_at": true}
if !allowed[sortCol] {
    return fmt.Errorf("invalid sort column: %s", sortCol)
}
query := fmt.Sprintf("SELECT id, name, email FROM users ORDER BY %s", sortCol)

更多注入防護模式，請參閱 samber/cc-skills-golang@golang-security 技能。

結構掃描與可為 NULL 的欄位

對 sqlx 使用 db:"column_name" 標籤，對 pgx 使用 pgx.CollectRows 搭配 pgx.RowToStructByName。使用指標欄位（*string、*time.Time）處理可為 NULL 的欄位 — 它們在掃描和 JSON 序列化時都能正常運作。請參閱掃描參考以取得所有方法的範例。

錯誤處理

func GetUser(id string) (*User, error) {
    var user User

    err := db.GetContext(ctx, &user, "SELECT id, name FROM users WHERE id = $1", id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, ErrUserNotFound // 轉換為領域錯誤
        }
        return nil, fmt.Errorf("querying user %s: %w", id, err)
    }

    return &user, nil
}

或者：

func GetUser(id string) (u *User, exists bool, err error) {
    var user User

    err := db.GetContext(ctx, &user, "SELECT id, name FROM users WHERE id = $1", id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, false, nil // 「沒有使用者」不是技術錯誤，而是領域錯誤
        }
        return nil, false, fmt.Errorf("querying user %s: %w", id, err)
    }

    return &user, true, nil
}

永遠關閉 rows

rows, err := db.QueryContext(ctx, "SELECT id, name FROM users")
if err != nil {
    return fmt.Errorf("querying users: %w", err)
}
defer rows.Close() // 防止連線洩漏

for rows.Next() {
    // ...
}
if err := rows.Err(); err != nil { // 迭代後務必檢查
    return fmt.Errorf("iterating users: %w", err)
}

常見資料庫錯誤模式

錯誤	如何偵測	動作
找不到資料列	`errors.Is(err, sql.ErrNoRows)`	回傳領域錯誤
唯一性約束	檢查驅動程式特定的錯誤碼	回傳衝突錯誤
連線被拒絕	`db.PingContext` 回傳 `err != nil`	快速失敗、記錄、以退避重試
序列化失敗	PostgreSQL 錯誤碼 `40001`	重試整個交易
Context 已取消	`errors.Is(err, context.Canceled)`	停止處理、傳播

Context 傳遞

始終使用 *Context 方法變體來傳遞截止時間和取消：

// ✗ 糟糕 — 沒有 context，即使客戶端中斷連線，查詢也會執行到完成
db.Query("SELECT ...")

// ✓ 良好 — 尊重 context 取消和逾時
db.QueryContext(ctx, "SELECT ...")

有關 context 模式的深入探討，請參閱 samber/cc-skills-golang@golang-context 技能。

交易、隔離層級與鎖定

有關交易模式、隔離層級、SELECT FOR UPDATE 和鎖定變體，請參閱交易。

連線池

db.SetMaxOpenConns(25)              // 限制總連線數
db.SetMaxIdleConns(10)              // 保持熱連線就緒
db.SetConnMaxLifetime(5 * time.Minute)  // 回收過時連線
db.SetConnMaxIdleTime(1 * time.Minute)  // 更快關閉閒置連線

有關大小調整指南和公式，請參閱資料庫效能。