範例資料表

本模組各篇都用同一組表：一家書店的顧客與訂單。orders.note 允許 NULL，用來示範 NULL 的讀取；customers.email 有唯一約束，用來示範約束違反的錯誤。

 1CREATE TABLE customers (
 2  id         bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
 3  name       text        NOT NULL,
 4  email      text        NOT NULL,
 5  created_at timestamptz NOT NULL DEFAULT now(),
 6  CONSTRAINT customers_email_key UNIQUE (email)
 7);
 8
 9CREATE TABLE orders (
10  id          bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
11  customer_id bigint      NOT NULL REFERENCES customers (id),
12  amount      integer     NOT NULL,
13  note        text,
14  ordered_at  timestamptz NOT NULL DEFAULT now()
15);
16
17INSERT INTO customers (id, name, email) VALUES
18  (1, '佳穎', 'jiaying@example.com'), (2, '宗翰', 'zonghan@example.com'), (3, '雅文', 'yawen@example.com');
19INSERT INTO orders (id, customer_id, amount, note) VALUES
20  (101, 1, 300, NULL), (102, 1, 500, '禮物包裝'), (103, 2, 250, NULL);
21
22-- 明確指定 id 寫入 identity 欄位不會推進它的序列；不補這兩行，下一個由資料庫配號的 INSERT 會撞主鍵
23SELECT setval(pg_get_serial_sequence('customers', 'id'), (SELECT max(id) FROM customers));
24SELECT setval(pg_get_serial_sequence('orders', 'id'), (SELECT max(id) FROM orders));

雅文沒有訂單，佳穎的兩張訂單只有一張有備註。範例程式的連線字串是 postgres://postgres:pw@localhost:55432/bookstore?sslmode=disable，帳號、密碼、port 與資料庫名稱換成手上那一台的值。各篇的輸出都以剛執行完上面這段 SQL 的資料為起點；前一篇的示範改過資料時（例如本篇〈交易〉那一節會改金額），先 DROP TABLE orders, customers 再重跑這段 SQL。

範例程式的 Go 模組要先取得驅動（後面各篇另外取得各自的套件）：

1go mod init example.com/bookstore   # 模組名稱自訂
2go get github.com/jackc/pgx/v5@v5.11.0

驅動與 sql.Open

database/sql 只定義介面，實際和資料庫通訊的是資料庫驅動程式（database driver，以下簡稱驅動）。驅動在自己的 init 函式裡向 database/sql 註冊一個名字，程式用空白匯入（blank import）觸發註冊，之後用那個名字開啟：

1import (
2	"database/sql"
3
4	_ "github.com/jackc/pgx/v5/stdlib" // 註冊名為 "pgx" 的驅動
5)
6
7db, err := sql.Open("pgx", dsn)

sql.Open 只建立 *sql.DB 這個物件並檢查參數格式，不連線。密碼錯了，sql.Open 照樣回傳 nil 錯誤，要到第一次需要連線時才失敗。所以服務啟動時接著呼叫 PingContext，讓設定錯誤在啟動那一刻就浮現，而不是在第一個請求進來時：

1open with wrong password, err = <nil>
2ping: failed to connect to `user=postgres database=bookstore`: ... failed SASL auth: FATAL: password authentication failed for user "postgres" (SQLSTATE 28P01)

*sql.DB 與連線池

*sql.DB 代表的是一個連線池（connection pool），不是一條連線。每次查詢時它從池裡取一條閒置的連線，沒有閒置的就新開一條，查詢結束後放回池裡。它可以被多個 goroutine 同時使用，所以一個程序（process）建立一個、在整個服務裡共用；每個請求各開一個 *sql.DB 會讓每個請求都重新建立連線，也讓池的上限失去作用。

池的大小由四個設定決定：

MaxOpenConns 預設不設上限，意思是流量尖峰時 Go 會一直開新連線，直到資料庫的 max_connections 拒絕為止；多個服務實例共用同一個資料庫時，全部實例的上限加起來要小於資料庫的 max_connections 扣掉維運保留的連線（各語言執行模型下的估算見 1.17 應用程式存取資料庫的工具分層〈各語言執行模型下的連線模型〉）。ConnMaxLifetime 設成比中間的負載平衡器或防火牆的閒置逾時短，連線就不會在池裡被對方悄悄斷掉。

db.Stats() 回傳池的即時狀態，〈查詢結果讀取物件（*sql.Rows）的關閉與連線洩漏〉那一節會用到其中三個欄位：InUse（使用中的連線數）、Idle（閒置的連線數）、WaitCount（因為池滿而排隊等連線的累計次數）。

查詢：QueryContext、QueryRowContext 與 ExecContext

三個方法依「預期回幾列」分工：

查詢的參數用佔位符（placeholder）傳，不要把值拼進 SQL 字串。佔位符的寫法由驅動決定：PostgreSQL 的驅動用 $1、$2，MySQL 的驅動用 ?。值拼進字串會讓使用者輸入的內容被當成 SQL 的一部分執行，也就是 SQL 注入（SQL injection）；佔位符把值交給驅動，pgx 預設把值和 SQL 分開送給資料庫，值只會被當成值。

1var name string
2err := db.QueryRowContext(ctx, "SELECT name FROM customers WHERE id = $1", 999).Scan(&name)
3if errors.Is(err, sql.ErrNoRows) {
4	// 沒有這個顧客：這是業務上的「找不到」，不是系統錯誤
5}

QueryRowContext 查不到資料時，Scan 回傳 sql.ErrNoRows。repository 通常在這裡把它轉成自己的「找不到」錯誤，讓上層不必認得 database/sql 的型別（轉換的位置見 Repository Adapter 實作）。

每個方法都有不帶 Context 的版本（Query、QueryRow、Exec），服務程式一律用帶 Context 的版本：請求被取消或逾時時，驅動會通知資料庫中止那一段查詢；pgx 接著關閉那條連線，database/sql 把它從池裡丟掉，空出的名額由下一個請求開新連線補上。不帶 Context 的版本等同傳入 context.Background()，查詢會一直跑到資料庫回應為止。

Scan 與 NULL

Scan 把一列的欄位依序寫進傳入的指標。欄位值是 NULL 而目標是 string 時，Scan 回傳錯誤，因為 string 沒有一個值可以代表「沒有值」。以 SELECT note FROM orders WHERE id = $1 讀訂單 101 的備註進 var note string：

1scan NULL into string: sql: Scan error on column index 0, name "note": converting NULL to string is unsupported

可以是 NULL 的欄位有兩種接法：

1var note sql.NullString // NULL 時 note.Valid == false，非 NULL 時值在 note.String
2var notePtr *string     // NULL 時 notePtr == nil

兩種都能分辨「NULL」與「空字串」。sql.NullString 這類型別（還有 NullInt64、NullTime，以及泛型的 sql.Null[T]）是 database/sql 自己的型別，放進 domain 的 struct 會讓上層也依賴資料庫套件；指標是語言本身的寫法，轉成 JSON 時 nil 直接變成 null。多數專案在 repository 的 row struct 用其中一種，轉成 domain 型別時再決定 NULL 代表什麼。

查詢結果讀取物件（*sql.Rows）的關閉與連線洩漏

QueryContext 回傳的 *sql.Rows 是查詢結果的讀取物件（其他中文資料常寫作游標，英文是 cursor，譯名的分辨見 Cursor）。它在讀取期間一直佔著池裡的一條連線，直到被關閉才放回去。關閉有兩種途徑：Next 讀到最後一列之後回傳 false 時自動關閉，或者程式呼叫 Close。

讀到一半就離開、又沒有呼叫 Close，那條連線就一直被佔著。把池的上限設成 1 就能直接看到：

1db.SetMaxOpenConns(1)
2rows, _ := db.QueryContext(ctx, "SELECT id FROM orders")
3rows.Next() // 只讀一列就離開，沒有 Close
4
5ctx2, cancel := context.WithTimeout(ctx, 2*time.Second)
6defer cancel()
7err := db.QueryRowContext(ctx2, "SELECT 1").Scan(new(int))

1stats after leaking rows: InUse=1 Idle=0
2second query: context deadline exceeded WaitCount = 1
3after Close: InUse=0 Idle=1

第二個查詢排隊等那唯一的一條連線，等了兩秒仍然等不到。正式環境的池上限比 1 大，同樣的連線洩漏（connection leak）要累積到把池佔滿才浮現，症狀是請求慢慢變慢、最後全部逾時，而資料庫本身的負載並不高。db.Stats() 的 InUse 一直接近上限、WaitCount 持續增加，是這個狀況的訊號。

所以讀多列的標準寫法固定是這個形狀：

 1rows, err := db.QueryContext(ctx, "SELECT id, amount FROM orders ORDER BY id")
 2if err != nil {
 3	return err
 4}
 5defer rows.Close() // 中途 return 也會關閉
 6
 7for rows.Next() {
 8	var id int64
 9	var amount int
10	if err := rows.Scan(&id, &amount); err != nil {
11		return err
12	}
13	// 使用 id、amount
14}
15return rows.Err() // 讀取途中斷線之類的錯誤在迴圈結束後才回報

rows.Err() 不能省：Next 回傳 false 有兩種原因，一種是正常讀完，一種是讀取途中出錯，只有 rows.Err() 分得出來。少了它，讀到一半斷線的結果會被當成完整的結果交給呼叫端。

交易：BeginTx、defer Rollback 與 Commit

交易（transaction）綁在一條連線上：BeginTx 從池裡取一條連線、送出 BEGIN，回傳的 *sql.Tx 之後的每個查詢都走這條連線，直到 Commit 或 Rollback 才把連線放回池裡。

 1// 把訂單 101 的 50 元折抵改記到同一位顧客的訂單 102：只成功一半的話，顧客會多拿到或少拿到 50 元
 2func moveDiscount(ctx context.Context, db *sql.DB) error {
 3	tx, err := db.BeginTx(ctx, nil)
 4	if err != nil {
 5		return err
 6	}
 7	defer tx.Rollback() // Commit 成功之後再呼叫只會回 ErrTxDone，不會撤銷
 8
 9	if _, err := tx.ExecContext(ctx, "UPDATE orders SET amount = amount - 50 WHERE id = $1", 101); err != nil {
10		return err
11	}
12	if _, err := tx.ExecContext(ctx, "UPDATE orders SET amount = amount + 50 WHERE id = $1", 102); err != nil {
13		return err
14	}
15	return tx.Commit()
16}

defer tx.Rollback() 讓每一條提早 return 的錯誤路徑都會撤銷交易並放回連線。Commit 成功之後，那個 Rollback 仍然會執行，只是回傳錯誤、什麼都不做。下面這一行的最後一個值是 errors.Is(err, sql.ErrTxDone)：

1rollback after commit: sql: transaction has already been committed or rolled back true

交易裡的查詢一定要用 tx 的方法，不能用 db 的。db.ExecContext 會從池裡另取一條連線，那個查詢就跑在交易之外：交易撤銷時它不會跟著撤銷，而且交易裡尚未提交的修改它也看不到。池上限是 1 的時候，這個錯誤直接變成卡住，因為唯一的連線被交易佔著。

隔離等級由 BeginTx 的第二個參數 &sql.TxOptions{Isolation: sql.LevelSerializable} 指定，nil 代表用資料庫的預設值（PostgreSQL 是 read committed）。等級之間的差別見 Isolation Level，交易範圍要劃在哪裡見 Transaction Boundary；交易要跨好幾個 repository 共用時，交易物件怎麼傳進各個 repository（以及傳錯時的徵兆，見 Transaction Propagation），見 1.4 Repository Adapter 實作〈Transaction 傳遞〉。

本模組其餘工具各自接手哪一段

1.17 應用程式存取資料庫的工具分層 把存取資料庫的工作分成寫出 SQL、取得連線並執行（連線池、交易）、把查詢結果對映成程式的值。用 database/sql 時，連線池由它管理，程式仍然要寫 SQL 字串、逐欄 Scan 進變數，並負責讀取物件與交易的收尾。本模組其餘的工具各自接手其中幾件：

sqlx、pgx 原生介面與 sqlc 接手之後，送出的 SQL 仍然寫在程式碼或 .sql 檔裡看得見；GORM 接手之後，SQL 也從程式碼上消失，要靠它的 SQL 記錄才看得到。怎麼在這些工具之間選，見 10.7 Go 專案的資料庫存取工具選型：GORM、sqlc 與 pgx 的組合。

兩種用法：database/sql 驅動與原生介面

pgx 同一個模組提供兩種入口：

兩者連的是同一個 PostgreSQL、用的是同一套通訊協定實作，差別在程式碼看到的 API：

• 原生介面多出來的能力：PostgreSQL 專有型別的直接對應（陣列、jsonb、inet 對應到 netip.Prefix）、COPY 協定的大量寫入、一次送出多個查詢的批次（Batch）、LISTEN／NOTIFY。database/sql 的介面是為所有資料庫設計的，這些功能放不進去。
• database/sql 驅動保留的相容性：只接受 *sql.DB 的函式庫——sqlx、GORM、多數 migration 工具——都要透過這一個入口。

所以程式只連 PostgreSQL、而且沒有依賴只吃 *sql.DB 的函式庫時，原生介面是比較直接的選擇；要和那些函式庫在同一個交易裡寫入時，用驅動那一個；只要共用連線池的話，pgx 的 stdlib.OpenDBFromPool(pool) 可以從 pgxpool 做出一個共用同一個池的 *sql.DB，交給那些函式庫。兩者可以在同一個程式裡並存；分別建立時各有一個連線池（連線數要合起來算），而且不論池是否共用， pgx.Tx 與 *sql.Tx 互不相容，一段要一起成功的寫入必須全部走同一個入口。

pgxpool：連線池

原生介面的連線池是 pgxpool。pgx.Connect 只建立一條連線、不能被多個 goroutine 同時使用，服務程式用 pgxpool.New：

1// 連線字串的帳號、密碼、port 與資料庫名稱換成手上那一台的值；pool_max_conns 是池的上限
2pool, err := pgxpool.New(ctx, "postgres://postgres:pw@localhost:55432/bookstore?sslmode=disable&pool_max_conns=10")
3if err != nil {
4	return err
5}
6defer pool.Close()

池的設定可以寫在連線字串裡（pool_max_conns、pool_max_conn_lifetime、pool_max_conn_idle_time 等），也可以先用 pgxpool.ParseConfig 解析成設定物件再改欄位。pool_max_conns 不寫時，上限是 4 與執行機器 CPU 核心數兩者中較大的那一個；這個預設值和 database/sql 的「不設上限」相反，流量大的服務常常是排隊等連線，而不是把資料庫連線開滿。

pool.Stat() 回傳池的狀態，可以直接輸出成監控指標：

EmptyAcquireCount 持續增加、AcquireDuration 跟著變長，代表請求在等連線；這和 database/sql 連線池的 WaitCount 是同一種訊號，持續發生而查詢本身不慢時，先查有沒有借了連線不還（Connection Leak）。

讀取結果：CollectRows 與 RowToStructByName

原生介面也可以逐欄 Scan，寫法和 database/sql 幾乎一樣。多出來的是一組把整列對映進 struct 的輔助函式：

 1type Order struct {
 2	ID         int64
 3	CustomerID int64
 4	Amount     int
 5	Note       *string // NULL 時是 nil
 6	OrderedAt  time.Time
 7}
 8
 9rows, _ := pool.Query(ctx,
10	"SELECT id, customer_id, amount, note, ordered_at FROM orders WHERE customer_id = $1 ORDER BY id", 1)
11orders, err := pgx.CollectRows(rows, pgx.RowToStructByName[Order])

pool.Query 的錯誤可以先忽略，因為 CollectRows 會把查詢的錯誤一併回傳，並在結束時關閉讀取物件，database/sql 那種忘了 Close 而佔住連線的問題在這個寫法裡不會發生。

RowToStructByName 依欄位名稱對映：查詢結果的 customer_id 對到 struct 的 CustomerID，比對時忽略大小寫與底線；名稱不同時用 db:"欄位名" 這個 struct tag 指定。對映發生在執行時，查詢結果有一個 struct 裡找不到的欄位，就在那一次呼叫回傳錯誤：

1type Bad struct {
2	ID    int64
3	Total int // 查詢結果的欄位叫 amount
4}
5rows, _ = pool.Query(ctx, "SELECT id, amount FROM orders")
6_, err = pgx.CollectRows(rows, pgx.RowToStructByName[Bad])

1mismatch: struct doesn't have corresponding row field amount

反方向的情形是 struct 有、查詢結果沒有的欄位：RowToStructByName 報錯，RowToStructByNameLax 讓那些欄位保持零值。查詢結果多出來的欄位，兩者都報錯，要改的是查詢列出的欄位。

查不到資料時，QueryRow(...).Scan 回傳的是 pgx.ErrNoRows，不是 sql.ErrNoRows；從 database/sql 換到原生介面時，判斷「找不到」的那幾行要一起改。

錯誤：*pgconn.PgError

資料庫回報的錯誤會被包成 *pgconn.PgError，裡面有 PostgreSQL 的錯誤代碼（SQLSTATE）與被違反的約束名稱：

1_, err := pool.Exec(ctx, "INSERT INTO customers (name, email) VALUES ($1, $2)", "重複", "jiaying@example.com")
2
3var pgErr *pgconn.PgError
4if errors.As(err, &pgErr) && pgErr.Code == "23505" {
5	// 23505 是唯一約束違反；pgErr.ConstraintName 說是哪一個
6}

1pgerr: 23505 customers_email_key

一張表通常有好幾個唯一約束（email、帳號名稱），錯誤代碼只說「有唯一約束被違反」，要回報「email 已被使用」還是「帳號已被使用」得看 ConstraintName。所以建表時替約束取明確的名字（CONSTRAINT customers_email_key UNIQUE (email)），程式就能依名字判斷，不必解析錯誤訊息的文字。

交易：BeginFunc

原生介面的交易同樣是 Begin 加 defer tx.Rollback(ctx) 加 Commit。pgx 另外提供 pgx.BeginFunc，把這三步包成一個函式：傳入的函式回傳 nil 就提交，回傳錯誤就撤銷：

1err := pgx.BeginFunc(ctx, pool, func(tx pgx.Tx) error {
2	if _, err := tx.Exec(ctx, "UPDATE orders SET amount = amount - 10 WHERE id = $1", 101); err != nil {
3		return err
4	}
5	return errors.New("中途失敗") // 回傳錯誤，前面的 UPDATE 一起撤銷
6})

1beginfunc err: 中途失敗 amount still: 300

大量寫入：CopyFrom

一次寫入大量資料列時，逐列 INSERT 每一列都是一次來回（round trip）；多列寫成一句 INSERT ... VALUES (...), (...) 可以減少來回，但參數數量有上限（PostgreSQL 的單一查詢最多 65535 個參數）。CopyFrom 走 PostgreSQL 的 COPY 協定，把資料列串流送給資料庫，沒有參數數量的限制，而且通常是三種寫法裡最快的：

1n, err := pool.CopyFrom(ctx,
2	pgx.Identifier{"orders"},              // 寫入哪張表
3	[]string{"customer_id", "amount"},      // 寫入哪些欄位
4	pgx.CopyFromRows([][]any{{3, 120}, {3, 80}}),
5)

1copy: 2 <nil>

COPY 是整批成功或整批失敗，其中一列違反約束，整批都不會寫入；它也不支援 ON CONFLICT，所以要「已存在就略過」的寫入不適合用它（重送的事件用 INSERT ... ON CONFLICT DO NOTHING 冪等寫入的做法見 1.18 高頻計數的寫入與彙總：熱點列的鎖、只新增的事件、可以重跑的彙總與重送的事件）。資料來源很大時，用 pgx.CopyFromFunc 逐列產生資料，不必先把全部資料放進記憶體。

pgx 的語句快取與 PgBouncer 交易模式

pgx 預設會把執行過的查詢在每條連線上建成預先解析的查詢（prepared statement）並快取起來，同一段 SQL 第二次執行時，資料庫不必再解析；執行計畫是否重用，由 PostgreSQL 的計畫快取決定（見 Prepared Statement 的通用計畫那一點）。在 PostgreSQL 開啟語句記錄就看得到這件事（ALTER DATABASE bookstore SET log_statement = 'all'; 之後新開的連線生效；PostgreSQL 跑在容器裡時用 docker logs <容器名稱> 讀記錄）：用 pool.QueryRow 對兩個顧客各執行一次 SELECT count(*) FROM orders WHERE customer_id = $1，兩次都以同一個 stmtcache_ 開頭的名字執行。

1LOG:  execute stmtcache_209ed55a1131ce455f4cfc90494ae99f1af9c243b09d5ff6: SELECT count(*) FROM orders WHERE customer_id = $1
2DETAIL:  Parameters: $1 = '1'
3LOG:  execute stmtcache_209ed55a1131ce455f4cfc90494ae99f1af9c243b09d5ff6: SELECT count(*) FROM orders WHERE customer_id = $1
4DETAIL:  Parameters: $1 = '2'

預先解析的查詢存在資料庫端的那一條連線上。應用程式和 PostgreSQL 之間有一層 PgBouncer 這類連線池代理（connection pooler），而它用交易模式（transaction pooling，pool_mode = transaction）時，應用程式連到 PgBouncer 的那條連線不變，而 PgBouncer 每個交易都可能從它自己對 PostgreSQL 的連線裡挑另一條，名字就對不上。pgx 的 stmtcache_ 名字由查詢內容雜湊而成，同一段 SQL 在每條應用程式連線上都叫同一個名字，所以另一條應用程式連線先在那條資料庫連線上建了同名的查詢，這一條再建一次就撞名。PgBouncer 1.25.2 設成交易模式、max_prepared_statements = 0，六條 pgx 連線同時執行同一段查詢 300 次，失敗的 200 次全是同一個錯誤：

1ERROR: prepared statement "stmtcache_209ed55a1131ce455f4cfc90494ae99f1af9c243b09d5ff6" already exists (SQLSTATE 42P05)

同樣的程式改用下面任一種處理方式之後，300 次全部成功。處理方式有兩種：PgBouncer 1.21 起可以在交易模式下追蹤預先解析的查詢，要把 max_prepared_statements 設成非 0，1.24 起預設就是 200（PgBouncer 本身的設定見 PostgreSQL pgBouncer 配置 + 連線池治理）；或者在 pgx 的連線字串加上 default_query_exec_mode=exec，改成每次執行都不留下具名的預先解析查詢。交易模式對其他連線層級設定（session state）的限制見 Transaction Pooling。

pgx 原生介面的適用範圍：只連 PostgreSQL 的程式

pgx 的原生介面接手了 PostgreSQL 型別的轉換、讀取物件的關閉與依欄名的對映，代價是程式只能連 PostgreSQL，而且只吃 *sql.DB 的函式庫用不上它的連線池。SQL 仍然是程式裡的字串，欄位名稱拼錯要到執行那一行才知道。10.4 sqlc：從 SQL 產生型別安全的 Go 程式碼 從同樣的 SQL 產生呼叫 pgx 的程式碼，把這類錯誤提前到產生程式碼時（sqlc generate）；只想在 database/sql 上補齊依欄名對映的，是 10.3 sqlx：手寫 SQL 加上 struct 對映。

sqlx.DB 與 database/sql 的關係

*sqlx.DB 內嵌了 *sql.DB，所以 10.1 database/sql：連線池、查詢結果的讀取與交易 的內容都照樣成立：同一個連線池、同樣的 SetMaxOpenConns、同樣要關閉的讀取物件、同樣的交易規則。sqlx 只在上面加方法，驅動也沿用 database/sql 的那一個：

1import (
2	_ "github.com/jackc/pgx/v5/stdlib"
3	"github.com/jmoiron/sqlx"
4)
5
6db, err := sqlx.ConnectContext(ctx, "pgx", dsn) // Open 加上 Ping

sqlx.ConnectContext 等於 sql.Open 再 PingContext，設定錯誤在這一行就回報。手上已經有一個 *sql.DB 時，用 sqlx.NewDb(db, "pgx") 包起來，兩者共用同一個連線池。

Get 與 Select：依 db tag 對映

sqlx 依 struct 欄位上的 db tag 對應查詢結果的欄位名稱：

 1type Order struct {
 2	ID         int64     `db:"id"`
 3	CustomerID int64     `db:"customer_id"`
 4	Amount     int       `db:"amount"`
 5	Note       *string   `db:"note"` // NULL 時是 nil
 6	OrderedAt  time.Time `db:"ordered_at"`
 7}
 8
 9var orders []Order
10err := db.SelectContext(ctx, &orders,
11	"SELECT id, customer_id, amount, note, ordered_at FROM orders WHERE customer_id = $1 ORDER BY id", 1)
12
13var o Order
14err = db.GetContext(ctx, &o, "SELECT * FROM orders WHERE id = $1", 999)

1select: 2 <nil>
2get none: sql: no rows in result set

SelectContext 讀出多列放進 slice，內部做完 database/sql 讀多列的那一整套「Next、Scan、Close、Err」；GetContext 讀一列，查不到時回傳的仍然是 sql.ErrNoRows，判斷「找不到」的寫法和 database/sql 相同。沒有 db tag 的欄位，sqlx 預設用欄位名稱的小寫去比對（CustomerID 比對 customerid），和資料庫慣用的 customer_id 對不上，所以每個欄位都寫 tag。

查詢結果的欄位多於 struct 時

對映發生在執行時。查詢結果有一個 struct 裡沒有的欄位，那一次呼叫就回傳錯誤：

1type Small struct {
2	ID int64 `db:"id"`
3}
4var s []Small
5err := db.SelectContext(ctx, &s, "SELECT id, amount FROM orders")

1extra column: missing destination name amount in *[]main.Small

這個行為在查詢寫 SELECT * 時會變成部署事故：資料表新增一個欄位之後，所有用 SELECT * 讀進同一個 struct 的查詢，從 migration 套用的那一刻起同時開始失敗，而 Go 程式一行都沒改。反方向（struct 有、查詢結果沒有的欄位）不會報錯，那個欄位保持零值，同樣不會被發現。所以用 sqlx 時查詢明確列出欄位，struct 與欄位清單一起改。

sqlx 提供 db.Unsafe()，回傳一個會略過多出來欄位的 *sqlx.DB。它讓上面那種事故不發生，代價是 struct 和查詢對不上時一律安靜通過。

具名參數與 IN

sqlx 補了兩個 database/sql 沒有的參數寫法。具名參數用 :名稱，值從 map 或 struct（依 db tag）取：

1res, err := db.NamedExecContext(ctx,
2	"UPDATE orders SET note = :note WHERE id = :id",
3	map[string]any{"id": 103, "note": "改地址"})

IN 後面要放一組值時，佔位符的數量要跟著值的數量變。sqlx.In 把一個 slice 展開成對應數量的 ?，Rebind 再把 ? 換成驅動用的佔位符寫法：

1q, args, err := sqlx.In("SELECT id FROM orders WHERE id IN (?)", []int64{101, 103})
2q = db.Rebind(q)
3var ids []int64
4err = db.SelectContext(ctx, &ids, q, args...)

1in: SELECT id FROM orders WHERE id IN (?, ?) [101 103] <nil>
2rebind: SELECT id FROM orders WHERE id IN ($1, $2)
3ids: [101 103] <nil>

只連 PostgreSQL 時另一種寫法是 WHERE id = ANY($1)，把整個 slice 當成一個陣列參數傳，佔位符的數量固定，查詢文字也不隨值的數量改變。

sqlx 留給程式的同步工作：struct 與查詢的欄位清單

sqlx 接手了逐欄 Scan 與讀取物件的收尾，而 struct 的欄位與每一段查詢列出的欄位是兩份清單，要在兩處同步改：查詢多一欄是執行時的錯誤，struct 多一欄是安靜的零值，兩者都要測試實際跑過才看得到。把這類檢查提前到產生程式碼時（sqlc generate）的是 10.4 sqlc：從 SQL 產生型別安全的 Go 程式碼；只連 PostgreSQL、不需要 *sql.DB 相容性的話，10.2 pgx：PostgreSQL 驅動的原生介面、連線池與 COPY 大量寫入 的 RowToStructByName 提供同樣依欄名的對映，不必再加一個函式庫；它在 struct 有、查詢結果沒有的欄位上會報錯，sqlx 則讓那個欄位保持零值。

sqlc 是開發時執行的命令列工具，不是程式在執行時匯入的函式庫；執行時的程式碼只依賴它產生出來的檔案與 pgx。產生出來的 store 套件放在專案的 Go 模組裡，呼叫端以 import "<go.mod 的 module 名稱>/sqlcdemo/store" 引用。

設定檔與目錄

 1migrations/                 # 專案的 migration 目錄，與 sqlcdemo/ 同一層
 2├── 001_init.up.sql
 3└── 001_init.down.sql
 4sqlcdemo/
 5├── sqlc.yaml
 6├── query/
 7│   └── orders.sql      # 手寫的查詢
 8└── store/              # sqlc 產生，不手動修改
 9    ├── db.go
10    ├── models.go
11    └── orders.sql.go

 1version: "2"
 2sql:
 3  - engine: "postgresql"
 4    schema: "../migrations"   # 建表的 SQL；指向 migration 目錄
 5    queries: "query"          # 手寫查詢所在的目錄
 6    gen:
 7      go:
 8        package: "store"
 9        out: "store"            # 產生的程式碼放哪裡
10        sql_package: "pgx/v5"   # 產生的程式碼呼叫 pgx 的原生介面

不寫 sql_package 時，產生的是呼叫 database/sql 的程式碼。要和 GORM 在同一個交易裡執行就選它，見 10.7 Go 專案的資料庫存取工具選型：GORM、sqlc 與 pgx 的組合〈混用時共用同一個交易〉。

schema 指向專案的 migration 目錄（資料表結構的版本化變更檔，見 Schema Migration），sqlc 依序讀裡面的檔案、算出最終的資料表結構。它認得幾種 migration 工具的檔名慣例，例如 golang-migrate 的 001_init.up.sql 與 001_init.down.sql 放在同一個目錄時，只讀 up 那一份；把 down 也讀進去的話，DROP TABLE 會讓後面的查詢全部找不到表。schema 的權威因此留在 migration，sqlc 只是讀它。

查詢檔與註記

每一段查詢上方的註記（query annotation）決定產生的函式名稱與回傳形狀：

 1-- name: ListOrdersByCustomer :many
 2SELECT id, customer_id, amount, note, ordered_at
 3FROM orders
 4WHERE customer_id = $1
 5ORDER BY id;
 6
 7-- name: GetCustomer :one
 8SELECT id, name, email FROM customers WHERE id = $1;
 9
10-- name: CreateCustomer :one
11INSERT INTO customers (name, email) VALUES ($1, $2)
12RETURNING id, created_at;
13
14-- name: TotalByCustomer :many
15SELECT c.name, sum(o.amount) AS total
16FROM customers c JOIN orders o ON o.customer_id = c.id
17GROUP BY c.name
18ORDER BY c.name;

產生指令在設定檔所在的目錄執行：

1# 不安裝，直接執行指定版本；第一次要下載並編譯，需要一兩分鐘
2go run github.com/sqlc-dev/sqlc/cmd/sqlc@v1.31.1 generate
3
4# 安裝成執行檔之後，每次產生只要不到一秒；執行檔放在 $(go env GOPATH)/bin，那個目錄要在 PATH 裡
5go install github.com/sqlc-dev/sqlc/cmd/sqlc@v1.31.1
6sqlc generate

sqlc v1.31.1 要求 Go 1.26 以上來編譯它自己；手上的 Go 版本較舊時，Go 會依 GOTOOLCHAIN 的預設設定自動下載符合的工具鏈，這不影響專案本身用的 Go 版本。版本號寫在指令裡，團隊每個人產生的程式碼才會一致；產生出來的檔案開頭也會記下產生它的 sqlc 版本。

產生出來的程式碼

ListOrdersByCustomer 產生的函式就是 10.1 database/sql：連線池、查詢結果的讀取與交易 讀多列的標準寫法，只是由工具寫出來：

 1func (q *Queries) ListOrdersByCustomer(ctx context.Context, customerID int64) ([]Order, error) {
 2	rows, err := q.db.Query(ctx, listOrdersByCustomer, customerID)
 3	if err != nil {
 4		return nil, err
 5	}
 6	defer rows.Close()
 7	var items []Order
 8	for rows.Next() {
 9		var i Order
10		if err := rows.Scan(&i.ID, &i.CustomerID, &i.Amount, &i.Note, &i.OrderedAt); err != nil {
11			return nil, err
12		}
13		items = append(items, i)
14	}
15	if err := rows.Err(); err != nil {
16		return nil, err
17	}
18	return items, nil
19}

參數與回傳型別依查詢決定：查詢選的欄位剛好是一整張表時，回傳那張表對應的 struct（Order，定義在 models.go）；選了部分欄位或含運算結果時，另外產生一個 XxxRow struct（TotalByCustomer 回傳 []TotalByCustomerRow，sum(o.amount) 推成 int64）；參數超過一個時產生一個 XxxParams struct（CreateCustomerParams{Name, Email}）。呼叫端的寫法如下：

1pool, err := pgxpool.New(ctx, dsn)
2q := store.New(pool)
3
4orders, err := q.ListOrdersByCustomer(ctx, 1)
5totals, err := q.TotalByCustomer(ctx)

1[{Name:佳穎 Total:800} {Name:宗翰 Total:250}] <nil>

store.New 接受的是 DBTX 這個介面（Exec、Query、QueryRow 三個方法），*pgxpool.Pool 與 pgx.Tx 都符合。交易裡執行時用 q.WithTx(tx) 取得一個綁在那個交易上的 *Queries，交易的開始與收尾仍然照 pgx 那一篇的寫法由程式負責。

產生時擋下的錯誤

sqlc 在產生時解析每一段查詢、對照 schema，欄位或表名寫錯就不產生程式碼。把 GetCustomer 那一行的 name 打成 nmae 再產生一次：

1# package store
2query/orders.sql:8:12: column "nmae" does not exist

同樣的錯字在 sqlx 或 pgx 裡是一個要等到執行那一行才會出現的錯誤。換成 sqlc 之後，schema 改了欄位名稱，重新產生時所有用到舊名稱的查詢一起報錯，連帶呼叫端用到的 struct 欄位也跟著改名，Go 編譯器接著指出每一個要改的呼叫位置。

NULL 與型別對應

pgx v5 的預設對應裡，可以是 NULL 的欄位與 timestamptz 都產生成 pgx 的 pgtype 型別：

1type Order struct {
2	ID         int64
3	CustomerID int64
4	Amount     int32
5	Note       pgtype.Text        // 可以是 NULL 的 text
6	OrderedAt  pgtype.Timestamptz
7}

pgtype 型別讓產生的 struct 依賴 pgx 的套件，放進 domain 型別或 JSON 回應前都要轉換一次。兩個設定改掉這個預設，加在前面 sqlc.yaml 的 gen.go 底下、和 sql_package 同一層：

1gen:
2  go:
3    emit_pointers_for_null_types: true   # 可以是 NULL 的欄位改成指標，例如 *string
4    overrides:
5      - db_type: "timestamptz"
6        go_type: "time.Time"             # NOT NULL 的 timestamptz 對應成 time.Time

1type Order struct {
2	ID         int64
3	CustomerID int64
4	Amount     int32
5	Note       *string
6	OrderedAt  time.Time
7}

依 db_type 寫的 override 預設只套用在 NOT NULL 的欄位；可以是 NULL 的 timestamptz 欄位要另寫一條加上 nullable: true 的 override（例如 go_type: {type: "time.Time", pointer: true}），否則仍然是 pgtype.Timestamptz。

integer 欄位產生的是 int32，因為 PostgreSQL 的 integer 就是 32 位元；要 int64 的話建表時用 bigint，或同樣用 overrides 指定。

選擇性的篩選條件

sqlc 產生的函式裡，SQL 文字在產生時就固定了，「有給最低金額才加這個條件」這類依輸入增減的條件，寫法是把條件寫成「參數是 NULL 時永遠成立」。把下面這段加進 query/orders.sql 再重新產生：

1-- name: SearchOrders :many
2SELECT id, amount FROM orders
3WHERE customer_id = $1
4  AND (sqlc.narg(min_amount)::int IS NULL OR amount >= sqlc.narg(min_amount))
5ORDER BY id;

sqlc.narg 宣告一個可以是 NULL 的具名參數。在開了 emit_pointers_for_null_types 的設定下，產生的參數 struct 裡它是指標（預設是 pgtype.Int4）：

1type SearchOrdersParams struct {
2	CustomerID int64
3	MinAmount  *int32 // nil 代表不篩選
4}

1MinAmount = nil  → [{101 300} {102 500}]
2MinAmount = 400  → [{102 500}]

這個寫法在條件只有兩三個時清楚好讀。條件多到十幾個、排序欄位也由使用者決定時，OR 堆疊的查詢讀起來吃力，資料庫為它選的執行計畫也可能不是最好的；那類查詢交給查詢建構器（Query Builder）或 ORM 的條件串接，和 sqlc 並存（混用的方式見 10.7 Go 專案的資料庫存取工具選型：GORM、sqlc 與 pgx 的組合）。

sqlc 帶進來的工作

sqlc 把 SQL 的錯誤提前到產生時，代價是多了一個產生步驟：

• schema 或查詢改了要重新產生，產生的檔案通常提交進版本控制，審查時看得到產生結果的差異。
• CI 裡跑一次產生，再確認工作目錄沒有差異，可以擋下「改了 SQL 卻忘了重新產生」的提交。
• 產生的程式碼不手動修改；要改行為就改 SQL、設定檔，或在產生的函式外面再包一層。

不想要這個步驟、而查詢以單表增刪查改為主的專案，看的是 10.5 GORM：model、關聯載入與 ORM 送出的 SQL。

GORM 的 PostgreSQL 方言套件（gorm.io/driver/postgres，GORM 稱為 dialector）底層用的是 pgx 的 database/sql 驅動，所以 database/sql 那一篇的連線池設定照樣適用：db.DB() 取得底下的 *sql.DB，在它上面呼叫 SetMaxOpenConns。

model 與命名慣例

GORM 用 struct 描述資料表，GORM 稱這種 struct 為 model，欄位與表名依命名慣例推出：

 1type Customer struct {
 2	ID        int64     // 名為 ID 的欄位是主鍵
 3	Name      string
 4	Email     string
 5	CreatedAt time.Time // 名為 CreatedAt 的欄位，建立時由 GORM 填入現在時間
 6	Orders    []Order   // 一對多關聯：orders.customer_id 指向 customers.id
 7}
 8
 9type Order struct {
10	ID         int64
11	CustomerID int64   // 欄位 customer_id
12	Amount     int
13	Note       *string // 可以是 NULL
14	OrderedAt  time.Time
15}

Customer 對到資料表 customers（struct 名稱轉成蛇形命名（snake_case）再加複數），CustomerID 對到欄位 customer_id。名稱不符合慣例時，用 TableName() 方法或 gorm:"column:..." tag 指定。

CreatedAt 這個名稱帶有行為：建立資料時 GORM 用應用程式的時鐘填入現在時間，再放進 INSERT，所以資料表上的 DEFAULT now() 不會被用到（下面〈寫入時的預設交易〉那一節的語句記錄裡看得到這個值被當成參數送出）。多個服務實例的時鐘不一致時，建立時間的順序就不一定等於寫入的順序；需要依時間排序的地方，改依主鍵排序，或讓資料庫給值。主鍵與資料庫給的時間反映的是配號與交易開始的順序，不是提交的順序，拿它們當「處理到哪裡」的位置會漏掉晚提交的資料（見 1.18 高頻計數的寫入與彙總：熱點列的鎖、只新增的事件、可以重跑的彙總與重送的事件〈已處理位置與交易的提交順序〉）。

GORM 的 SQL 記錄

GORM 的記錄器（logger）設成 Info 層級，每一個查詢都會連同耗時與影響列數印出來：

1db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
2	Logger: logger.New(log.New(os.Stdout, "", 0), logger.Config{LogLevel: logger.Info}),
3})

下面的範例為了簡短，直接在 db 上呼叫；服務程式裡每個查詢都從 db.WithContext(ctx) 開始，理由和 10.1 database/sql：連線池、查詢結果的讀取與交易 要求一律用帶 Context 的方法相同：請求取消或逾時時，查詢跟著中止。

這個記錄是 GORM 的方法呼叫與實際送出的 SQL 之間的對照，下面多數的 SQL 取自它；實際每個查詢前面還有呼叫位置與耗時一行，文中的輸出只留 SQL。GORM 自動包的 begin 與 commit 不出現在它的記錄裡，要看交易的那幾節改用 PostgreSQL 的語句記錄（log_statement = 'all'）。兩種記錄各記到什麼、正式環境怎麼開，見 Query Log。

查一筆：First、Take 與重用的變數

1var c Customer
2db.First(&c, 1)
3db.Take(&c, 1)

1SELECT * FROM "customers" WHERE "customers"."id" = 1 ORDER BY "customers"."id" LIMIT 1
2SELECT * FROM "customers" WHERE "customers"."id" = 1 AND "customers"."id" = 1 LIMIT 1

First 在條件之外加上依主鍵排序，取排序後的第一筆；Take 不排序，取資料庫回傳的任何一筆。依唯一欄位查一筆時兩者結果相同，Take 省掉排序。

第二行多了一個重複的 "customers"."id" = 1，原因是 Take 傳入的 c 已經被 First 填過，主鍵是 1，GORM 會把傳入物件上已有的主鍵加進條件。重用同一個變數去查另一筆時，這個行為會讓查詢靜默地查不到：

1db.Where("email = ?", "jiaying@example.com").First(&c) // c.ID 還是 1
2db.First(&c, 999)                                     // 想查 id 999

1SELECT * FROM "customers" WHERE email = 'jiaying@example.com' AND "customers"."id" = 1 ORDER BY "customers"."id" LIMIT 1
2SELECT * FROM "customers" WHERE "customers"."id" = 999 AND "customers"."id" = 1 ORDER BY "customers"."id" LIMIT 1

第二個查詢的條件是 id = 999 AND id = 1，永遠不會有結果。每一次查詢用一個新宣告的變數，就不會帶到前一次留下的主鍵。

找不到資料的判斷

First、Take、Last 查不到時回傳 gorm.ErrRecordNotFound；Find 查不到時不回傳錯誤，只是 slice 是空的：

1err := db.First(&c, 999).Error
2// record not found, errors.Is(err, gorm.ErrRecordNotFound) == true
3
4var cs []Customer
5err = db.Where("id = ?", 999).Find(&cs).Error
6// err == nil, len(cs) == 0

用 Find 加上一個 struct（不是 slice）去查一筆，查不到時同樣不回錯誤，struct 保持零值；要「找不到就報錯」的地方用 First 或 Take。

關聯：迴圈裡的查詢與 Preload

逐一讀每個顧客的訂單時，在迴圈裡查就是 N+1：一次查顧客，再每個顧客一次查訂單。

1var all []Customer
2db.Find(&all)
3for i := range all {
4	db.Where("customer_id = ?", all[i].ID).Find(&all[i].Orders)
5}

1SELECT * FROM "customers"
2SELECT * FROM "orders" WHERE customer_id = 1
3SELECT * FROM "orders" WHERE customer_id = 2
4SELECT * FROM "orders" WHERE customer_id = 3

顧客有一千個就是一千零一次查詢，每一次都是一次資料庫來回（round trip）（N+1 的成本與判讀見 1.13 應用層查詢反模式與 Query 預算）。Preload 改成兩次查詢，第二次用 IN 一次取回全部顧客的訂單，再由 GORM 依 customer_id 分配回各個顧客：

1var all []Customer
2db.Preload("Orders").Find(&all)

1SELECT * FROM "orders" WHERE "orders"."customer_id" IN (1,2,3)
2SELECT * FROM "customers"

（記錄的順序是 GORM 印出的順序，執行時先查顧客、再依取回的主鍵查訂單。）GORM 沒有存取屬性時自動查詢的延遲載入（lazy loading，Eloquent 與 SQLAlchemy 有，對照見 1.17 應用程式存取資料庫的工具分層〈ORM 送出的查詢次數：延遲載入與 N+1〉），沒有 Preload 的關聯欄位就是空的；所以在 GORM 裡，N+1 的來源是程式自己在迴圈裡查，而不是框架代查，GORM 的 SQL 記錄裡同一個形狀的查詢重複出現 N 次就是訊號。

更新：零值欄位與 Updates

用 struct 更新時，GORM 只寫入非零值的欄位，因為它分不出「欄位是 0」與「沒有設定這個欄位」：

1var o Order
2db.Take(&o, 103)
3db.Model(&o).Updates(Order{Amount: 0})                // 想把金額改成 0
4db.Model(&o).Updates(map[string]any{"amount": 0})

GORM 的記錄裡，第一個 Updates 沒有任何 UPDATE；第二個才有：

1UPDATE "orders" SET "amount"=0 WHERE "id" = 103

PostgreSQL 的語句記錄（log_statement）顯示第一個 Updates 送出了一組空的交易（begin 之後直接 commit；GORM 的寫入預設包在交易裡，見〈寫入時的預設交易〉），沒有錯誤、影響零列，程式完全不會發現金額沒有改。範例的 Order 沒有 UpdatedAt；model 帶 UpdatedAt（嵌入 gorm.Model 就有，見 10.6 GORM 的 gorm.Model、軟刪除與 Save：慣例欄位加上的查詢條件與整列寫回）時，GORM 仍會送出只更新 updated_at 的 UPDATE，影響列數是 1，看起來像更新成功，而金額照樣沒改。和 Eloquent、SQLAlchemy 這類追蹤變更的 ORM 不同（對照見 1.17 應用程式存取資料庫的工具分層〈ORM 寫回哪些欄位：變更追蹤、全部欄位與零值〉）。要寫入零值（0、""、false）時，用 map、用 Select("amount") 指定欄位，或用 Update("amount", 0) 更新單一欄位。可以是 NULL 的欄位宣告成指標（*int），nil 是「不寫」、指向 0 的指標是「寫成 0」，兩者就分得開。

寫入時的預設交易

GORM 的每一個建立、更新、刪除，預設都包在一個交易裡。在 PostgreSQL 開啟語句記錄（log_statement = 'all'）就看得到：

1LOG:  statement: begin
2LOG:  execute stmtcache_230b...: INSERT INTO "customers" ("name","email","created_at") VALUES ($1,$2,$3) RETURNING "id"
3DETAIL:  Parameters: $1 = '新顧客', $2 = 'new@example.com', $3 = '2026-10-06 04:59:33.855131+00'
4LOG:  statement: commit

stmtcache_ 開頭的名字是 pgx 在連線上快取的預先解析查詢（見 Prepared Statement）。一個 INSERT 變成三次來回。GORM 這樣做，是因為一次 Create 可能連帶寫入關聯的資料（建立顧客時一併建立訂單），包在交易裡才會一起成功或一起失敗。寫入沒有關聯、或交易由程式自己用 db.Transaction 控制時，這一層是多出來的，gorm.Config{SkipDefaultTransaction: true} 關掉它之後，同樣的 INSERT 只剩一行，前後沒有 begin 與 commit。

這兩次多出來的來回在一般的增刪查改流量下不構成瓶頸，在寫入密集的路徑上才量得出差別；而關掉它的前提是那條路徑沒有依賴它的連帶寫入。所以這個預設值是否要關，取決於壓測或正式環境的延遲數字有沒有指向它。

db.Transaction(func(tx *gorm.DB) error { ... }) 是程式自己控制的交易，回傳 nil 提交、回傳錯誤撤銷；函式裡每一個查詢都要用參數 tx，用外面的 db 會從池裡另取一條連線、跑在交易之外（交易物件怎麼傳進各個 repository、誤用時交易外的寫入卡在交易持有的鎖上，見 Transaction Propagation），和 10.1 database/sql：連線池、查詢結果的讀取與交易〈交易：BeginTx、defer Rollback 與 Commit〉是同一個規則。

錯誤判讀：唯一約束

jiaying@example.com 已經是範例資料裡佳穎的 email，而 customers_email_key 是 customers.email 上的唯一約束。建立的資料違反唯一約束時，GORM 回傳的錯誤裡包著 pgx 的 *pgconn.PgError，用 errors.As 取出之後讀約束名稱：

1err := db.Create(&Customer{Name: "重複", Email: "jiaying@example.com"}).Error
2
3var pgErr *pgconn.PgError
4if errors.As(err, &pgErr) && pgErr.ConstraintName == "customers_email_key" {
5	// email 已被使用
6}

gorm.Config{TranslateError: true} 讓 GORM 把資料庫錯誤轉成自己的錯誤值，唯一約束違反變成 gorm.ErrDuplicatedKey。實測轉換之後 errors.As 仍然取得到 *pgconn.PgError：

1TranslateError: duplicated key not allowed: ERROR: duplicate key value violates unique constraint "customers_email_key" (SQLSTATE 23505) true true

ErrDuplicatedKey 讓程式不必認得 PostgreSQL 的錯誤代碼，換資料庫時判斷式不用改；它只說「有唯一約束被違反」，一張表有好幾個唯一約束時，要回報是哪一個，仍然要讀約束名稱。

AutoMigrate 在正式環境的限制

db.AutoMigrate(&Customer{}) 依 model 建表、補上缺少的欄位與索引。它方便在開發初期快速建表，而它只往「讓資料表容得下這個 struct」的方向改。下面先用一版 model 建表，再把欄位 Rate 改名成 Discount、Code 加上長度限制：

 1type Coupon struct {
 2	ID   int64
 3	Code string
 4	Rate int
 5}
 6
 7type CouponV2 struct {
 8	ID       int64
 9	Code     string `gorm:"size:20"`
10	Discount int
11}
12
13func (CouponV2) TableName() string { return "coupons" }
14
15db.AutoMigrate(&Coupon{})
16db.AutoMigrate(&CouponV2{})

以 SELECT column_name, data_type, character_maximum_length FROM information_schema.columns WHERE table_name = 'coupons' 讀出欄位，整理成一行：

1[id bigint code character varying(20) rate bigint discount bigint]

改名被當成新增一個欄位 discount，舊的 rate 和它的資料都留著；code 的型別直接被改成 varchar(20)。GORM 送出的是 ALTER ... TYPE varchar(20) USING code::varchar(20)，PostgreSQL 的明確轉型會把超過 20 個字元的值直接截斷，所以表裡已經有較長的資料時，這一步照樣成功、不報錯，被截掉的資料就此遺失。整個過程沒有一份檔案記錄它做了什麼，也沒有退回的方法。

所以正式環境的 schema 交給版本化的 migration 工具（golang-migrate、goose、Atlas）：每一次改動是一份可以審查的檔案，依序套用，可以在測試環境先跑過。GORM 只負責讀寫，model 跟著 migration 改。版本化 migration 的流程與相容性規則見 資料庫 transaction 與 schema migration。

GORM 的慣例：主鍵、零值、CreatedAt 與預設交易

主鍵條件、零值更新、CreatedAt 與預設交易這幾節的現象有同一個來源：程式碼寫的是方法呼叫，實際行為由 GORM 的慣例決定——傳入物件上的主鍵、零值的含義、CreatedAt 這個欄位名稱、寫入時的交易。慣例讓常見的增刪查改很短，而每一條慣例都要先知道它存在，才知道程式碼底下發生了什麼。其中三條在 GORM 的 SQL 記錄裡看得到：主鍵條件多出來、零值欄位沒有出現在 UPDATE 裡、INSERT 帶著應用程式填的建立時間；預設交易的 begin 與 commit 要開資料庫的語句記錄（log_statement）才看得到。

gorm.Model 帶進來的 UpdatedAt 與 DeletedAt、軟刪除替每個查詢加的條件，以及 Save 寫回全部欄位的行為，是同一類由欄位名稱與型別決定的慣例，見 10.6 GORM 的 gorm.Model、軟刪除與 Save：慣例欄位加上的查詢條件與整列寫回。

需要報表、多表聚合這類固定而複雜的查詢時，GORM 的 Raw 可以直接寫 SQL 並對映回 struct；這類查詢多的專案，也常把它們交給 10.4 sqlc：從 SQL 產生型別安全的 Go 程式碼，兩者怎麼並存見 10.7 Go 專案的資料庫存取工具選型：GORM、sqlc 與 pgx 的組合。

範例沿用 10.1 database/sql：連線池、查詢結果的讀取與交易 的 customers 與 orders 兩張表：顧客佳穎（id 1，有兩張訂單）、宗翰（id 2，有一張訂單）、雅文（id 3，沒有訂單）。每一節開始時，資料都重置成剛執行完 10.1 的建表 SQL、再套用〈gorm.Model 的欄位：ID、CreatedAt、UpdatedAt 與 DeletedAt〉那一節的 migration 之後的狀態；同一節裡的程式片段接續前一段的結果往下執行。程式裡的 db 是 10.5 用 gorm.Open 開好的 *gorm.DB，記錄器設成 logger.Info；Customer 是〈gorm.Model 的欄位：ID、CreatedAt、UpdatedAt 與 DeletedAt〉那一節嵌入 gorm.Model 的 struct。軟刪除本身是不分語言的做法，Laravel 等框架的對應寫法與共通的風險見 Soft Delete 知識卡。

gorm.Model 的欄位：ID、CreatedAt、UpdatedAt 與 DeletedAt

gorm.Model 是 GORM 提供的一個 struct，原始碼只有四個欄位：

1type Model struct {
2	ID        uint `gorm:"primarykey"`
3	CreatedAt time.Time
4	UpdatedAt time.Time
5	DeletedAt DeletedAt `gorm:"index"`
6}

把它嵌入自己的 model，四個欄位與它們的行為就一起帶進來：

1type Customer struct {
2	gorm.Model // id、created_at、updated_at、deleted_at
3	Name   string
4	Email  string
5	Orders []Order
6}

ID 是主鍵，CreatedAt 在建立時由 GORM 用應用程式的時鐘填入（見 10.5 GORM：model、關聯載入與 ORM 送出的 SQL〈model 與命名慣例〉），UpdatedAt 在每次更新時填入，DeletedAt 讓這個 model 改用軟刪除。範例資料表原本沒有 updated_at 與 deleted_at，用 migration 補上：

1ALTER TABLE customers ADD COLUMN updated_at timestamptz, ADD COLUMN deleted_at timestamptz;
2CREATE INDEX customers_deleted_at_idx ON customers (deleted_at);

deleted_at 上的索引對應 gorm.Model 裡的 gorm:"index"：每個查詢都會帶 deleted_at IS NULL，而 AutoMigrate 建表時也會建這個索引；schema 交給 migration 管理時（理由見 10.5 GORM：model、關聯載入與 ORM 送出的 SQL〈AutoMigrate 在正式環境的限制〉），migration 裡要自己建這個索引。

ID 的型別是 uint，對到資料表的 bigint 讀寫都正常；需要 int64（例如和其他程式共用的型別）時，不嵌入 gorm.Model，把需要的欄位自己寫進 struct，行為由欄位名稱與型別決定，一樣會生效。

UpdatedAt 的更新時機

Update、Updates 與 Save 都會把 updated_at 設成現在時間並放進 UPDATE；UpdateColumn 與 UpdateColumns 只寫指定的欄位，不更新 updated_at，也不執行 model 上的 hook（BeforeUpdate 這類 GORM 在寫入前後自動呼叫的方法）：

1db.Model(&Customer{Model: gorm.Model{ID: 2}}).UpdateColumn("name", "宗翰 C")
2db.Model(&Customer{Model: gorm.Model{ID: 2}}).Update("name", "宗翰 D")

1UPDATE "customers" SET "name"='宗翰 C' WHERE "customers"."deleted_at" IS NULL AND "id" = 2
2UPDATE "customers" SET "name"='宗翰 D',"updated_at"='2026-10-06 14:27:15.524' WHERE "customers"."deleted_at" IS NULL AND "id" = 2

兩個 UPDATE 都帶著 deleted_at IS NULL，那是〈軟刪除：Delete 變成 UPDATE〉那一節的 DeletedAt 加上的。updated_at 常被拿來當增量同步的依據（「拿出上次同步之後改過的列」），用 UpdateColumn 改的資料不會被這種同步取出。GORM 的軟刪除也一樣：Delete 送出的是 UPDATE "customers" SET "deleted_at"=... WHERE ...，只寫 deleted_at、不寫 updated_at，所以依 updated_at 的同步收不到刪除，要另外用 Unscoped 取出 deleted_at 晚於上次同步的列（Laravel 的軟刪除會一併更新 updated_at，對照見 Soft Delete 知識卡）。

軟刪除：Delete 變成 UPDATE

model 有 gorm.DeletedAt 型別的欄位時，Delete 送出的是 UPDATE：

1db.Delete(&Customer{}, 3)

1UPDATE "customers" SET "deleted_at"='2026-10-06 14:26:48.627' WHERE "customers"."id" = 3 AND "customers"."deleted_at" IS NULL

雅文那一列還在表裡，只是 deleted_at 有了值。之後這個 model 的每一個查詢都多一個條件，查不到雅文：

1var c Customer
2err := db.First(&c, 3).Error // record not found
3
4var n, nAll int64
5db.Model(&Customer{}).Count(&n)
6db.Unscoped().Model(&Customer{}).Count(&nAll) // n = 2, nAll = 3

1SELECT * FROM "customers" WHERE "customers"."id" = 3 AND "customers"."deleted_at" IS NULL ORDER BY "customers"."id" LIMIT 1
2SELECT count(*) FROM "customers" WHERE "customers"."deleted_at" IS NULL
3SELECT count(*) FROM "customers"

Unscoped() 取消這個條件，用在要看到已刪除資料的地方（後台的回收區、稽核）；db.Unscoped().Delete(&Customer{}, 3) 送出 DELETE，把那一列從表中移除。

對已刪除的列再刪一次、或更新它，條件裡的 deleted_at IS NULL 讓 UPDATE 影響零列，GORM 不回報錯誤：

1db.Delete(&Customer{}, 3)                                       // 雅文已經刪除，再刪一次
2db.Model(&Customer{Model: gorm.Model{ID: 3}}).Update("name", "x") // 更新已刪除的列

1UPDATE "customers" SET "deleted_at"='2026-10-06 14:26:48.747' WHERE "customers"."id" = 3 AND "customers"."deleted_at" IS NULL
2UPDATE "customers" SET "name"='x',"updated_at"='2026-10-06 14:26:48.749' WHERE "customers"."deleted_at" IS NULL AND "id" = 3

兩個呼叫的 Error 都是 nil、RowsAffected 都是 0。「改一筆不存在或已刪除的資料」要回報給呼叫端時，程式要自己檢查 RowsAffected。

不經過軟刪除條件的路徑

這個條件是 GORM 組 SQL 時加上的，所以 GORM 沒有參與組 SQL 的地方都看得到已刪除的列。Raw 送出的是程式寫的那一段 SQL，原樣執行：

1db.Delete(&Customer{}, 3) // 軟刪除雅文
2
3var names []string
4db.Raw("SELECT name FROM customers ORDER BY id").Scan(&names)
5// [佳穎 宗翰 雅文]

已經軟刪除的雅文仍在結果裡。同樣的情形出現在用 sqlc 寫的報表查詢（混用方式見 10.7 Go 專案的資料庫存取工具選型：GORM、sqlc 與 pgx 的組合）、共用這個資料庫的其他服務，以及直接連進資料庫查問題的人。專案決定用軟刪除時，這些路徑的每一段 SQL 都要自己寫 deleted_at IS NULL，或由資料庫端提供只含未刪除列的 view 給報表與其他服務使用（做法見 Soft Delete 知識卡）；頁面上的數字由 GORM 算、報表由手寫 SQL 算，兩邊差的就是已刪除的列。

軟刪除與關聯：關聯載入的結果與外鍵檢查

軟刪除佳穎（佳穎有兩張訂單）之後，從訂單載入顧客：

訂單的 model 多一個 Customer 欄位，GORM 依它與 CustomerID 知道每張訂單屬於哪位顧客：

 1type Order struct {
 2	ID         int64
 3	CustomerID int64
 4	Customer   Customer // 所屬的顧客
 5	Amount     int
 6	Note       *string
 7	OrderedAt  time.Time
 8}
 9
10db.Delete(&Customer{}, 1)
11
12var orders []Order
13db.Joins("Customer").Order("orders.id").Find(&orders)

1SELECT "orders"."id", ... ,"Customer"."name" AS "Customer__name", ... FROM "orders" LEFT JOIN "customers" "Customer" ON "orders"."customer_id" = "Customer"."id" AND "Customer"."deleted_at" IS NULL ORDER BY orders.id
2order 101 customer_id=1 Customer.ID=0 Name=""
3order 102 customer_id=1 Customer.ID=0 Name=""
4order 103 customer_id=2 Customer.ID=2 Name="宗翰"

GORM 把條件加在 LEFT JOIN 的 ON 上，所以訂單照樣查得到，關聯的顧客則是零值；Preload("Customer") 的結果相同：它另外送出一個查顧客的查詢（WHERE id IN (1,2)），在那個查詢上加同一個條件。畫面上會出現「訂單的顧客名稱是空白」，而 customer_id 仍然是 1。這筆資料的處理方式要由業務決定：訂單顯示「已刪除的顧客」、改用 Unscoped 載入顧客，或刪除顧客時一併處理訂單，三者可以擇一，也可以並用（例如畫面用 Unscoped 載入、再標示已刪除）。

orders.customer_id 上的外鍵檢查只在 customers 的列被 DELETE 或主鍵被改時動作，而軟刪除是 UPDATE，所以佳穎的軟刪除成功了，外鍵沒有替程式做這個決定；之後要永久刪除這位顧客，外鍵才擋下來：

1err := db.Unscoped().Delete(&Customer{}, 1).Error

1DELETE FROM "customers" WHERE "customers"."id" = 1
2ERROR: update or delete on table "customers" violates foreign key constraint "orders_customer_id_fkey" on table "orders" (SQLSTATE 23503)

軟刪除與唯一約束：刪掉再建立同一個 email

雅文被軟刪除之後，用同一個 email 重新建立顧客：

1db.Delete(&Customer{}, 3)
2err := db.Create(&Customer{Name: "雅文", Email: "yawen@example.com"}).Error

1ERROR: duplicate key value violates unique constraint "customers_email_key" (SQLSTATE 23505)

customers_email_key 這個唯一約束涵蓋表裡的每一列，包括已刪除的那一列。PostgreSQL 的做法是刪掉這個約束，另外建一個只涵蓋未刪除的列的唯一索引（部分索引，partial index；索引本身的取捨見 PostgreSQL Index Selection：B-tree / GIN / GiST / BRIN / Hash 對應 workload 的決策樹〈Partial Index：條件式 index 救 storage〉）：

1ALTER TABLE customers DROP CONSTRAINT customers_email_key;
2CREATE UNIQUE INDEX customers_email_active_key ON customers (email) WHERE deleted_at IS NULL;

換上之後，刪掉再建立同一個 email 成功；兩個未刪除的顧客用同一個 email 時仍然報錯，*pgconn.PgError 的 ConstraintName 是索引的名字 customers_email_active_key，依約束名稱回報錯誤的程式要跟著改名（判讀方式見 10.5 GORM：model、關聯載入與 ORM 送出的 SQL〈錯誤判讀：唯一約束〉）。

部分索引會影響 upsert（INSERT 遇到唯一衝突時改成更新既有那一列的寫法，PostgreSQL 寫成 INSERT ... ON CONFLICT）。GORM 的 clause.OnConflict 只寫衝突欄位時，PostgreSQL 找不到與它相符的唯一約束：

1db.Clauses(clause.OnConflict{
2	Columns:   []clause.Column{{Name: "email"}},
3	DoUpdates: clause.AssignmentColumns([]string{"name"}),
4}).Create(&Customer{Name: "佳穎2", Email: "jiaying@example.com"})

1INSERT INTO "customers" (...) VALUES (...) ON CONFLICT ("email") DO UPDATE SET "name"="excluded"."name" RETURNING "id"
2ERROR: there is no unique or exclusion constraint matching the ON CONFLICT specification (SQLSTATE 42P10)

ON CONFLICT 的目標要寫出和部分索引相同的條件，PostgreSQL 才認得它；clause.OnConflict 的 TargetWhere 就是那個條件：

1db.Clauses(clause.OnConflict{
2	Columns:     []clause.Column{{Name: "email"}},
3	TargetWhere: clause.Where{Exprs: []clause.Expression{clause.Expr{SQL: "deleted_at IS NULL"}}},
4	DoUpdates:   clause.AssignmentColumns([]string{"name"}),
5}).Create(&Customer{Name: "佳穎2", Email: "jiaying@example.com"})

1INSERT INTO "customers" (...) VALUES (...) ON CONFLICT ("email")  WHERE deleted_at IS NULL DO UPDATE SET "name"="excluded"."name" RETURNING "id"

MySQL 沒有部分索引，「只對未刪除的列要求 email 唯一」要改用產生欄位（generated column）或複合唯一索引，兩種做法見 Soft Delete 知識卡。

沒有條件的 Delete 與 Update

Delete 或 Update 沒有任何條件時，GORM 拒絕執行並回傳 gorm.ErrMissingWhereClause：

1err := db.Delete(&Customer{}).Error // WHERE conditions required

GORM 的記錄器（logger）印出了它組好的 UPDATE "customers" SET "deleted_at"=... WHERE "customers"."deleted_at" IS NULL，而 PostgreSQL 的語句記錄（log_statement，見 Query Log 知識卡）裡沒有這一句：檢查發生在送出之前。

這個檢查看的是「有沒有條件」，不是「條件會挑出幾列」。條件寫成永遠成立的式子，檢查就通過：

1db.Where("1 = 1").Delete(&Customer{})

1UPDATE "customers" SET "deleted_at"='2026-10-06 14:42:48.947' WHERE 1 = 1 AND "customers"."deleted_at" IS NULL

影響三列，表裡的顧客全部被軟刪除。依使用者輸入組條件的程式常先放一個 1 = 1 再逐一串接 AND，篩選條件全部留空時組出的就是這一句，GORM 的檢查照樣放行；確實要對整張表操作時，GORM 的做法是 Session(&gorm.Session{AllowGlobalUpdate: true})，讓這個意圖寫在程式碼上。

Save：寫回全部欄位

Save 把 struct 的每一個欄位都寫回去，包括沒有改的：

1var a Customer
2db.First(&a, 2)
3a.Name = "宗翰（改）"
4db.Save(&a)

1UPDATE "customers" SET "created_at"='2026-10-06 14:27:11.427',"updated_at"='2026-10-06 14:27:15.442',"deleted_at"=NULL,"name"='宗翰（改）',"email"='zonghan@example.com' WHERE "customers"."deleted_at" IS NULL AND "id" = 2

created_at、email 都用讀出時的值再寫一次。兩個請求同時讀出同一位顧客、各改一個欄位、各自 Save，後寫的那一個會用它讀出時的舊值蓋掉前一個的修改。下面的 p 與 q 代表兩個請求各自讀出的宗翰，讀出時的名字是上一個示範寫進去的「宗翰（改）」：

1var p, q Customer
2db.First(&p, 2)
3db.First(&q, 2)
4p.Name = "宗翰 A"
5db.Save(&p)
6q.Email = "zonghan.b@example.com"
7db.Save(&q)

1UPDATE "customers" SET ...,"name"='宗翰 A',"email"='zonghan@example.com' WHERE "customers"."deleted_at" IS NULL AND "id" = 2
2UPDATE "customers" SET ...,"name"='宗翰（改）',"email"='zonghan.b@example.com' WHERE "customers"."deleted_at" IS NULL AND "id" = 2

再讀一次這位顧客，名字是「宗翰（改）」：p 改的名字被 q 帶著的舊名字蓋掉了，兩個呼叫都沒有錯誤。這種情形叫遺失更新（lost update），Django 的 save() 預設也是寫回全部欄位（對照見 1.17 應用程式存取資料庫的工具分層〈ORM 寫回哪些欄位：變更追蹤、全部欄位與零值〉）。只改幾個欄位時，用 Updates 傳 map，或 Select 指定欄位，讓 UPDATE 只寫那幾個欄位；同一個欄位也可能被兩個請求同時改時，要另外加樂觀鎖（optimistic locking：UPDATE 的條件多帶一個讀出時的版本值，影響零列就代表被別人改過；它和悲觀鎖的取捨見 1.3 Transaction 與一致性邊界〈Optimistic vs Pessimistic Locking〉）。另一個做法是把讀出與寫回放進 repeatable read 的交易：兩個交易時間重疊、改到同一列時，後寫入的那一個在它的 UPDATE 上失敗（could not serialize access due to concurrent update，SQLSTATE 40001），程式重試，而不是默默蓋掉。

找不到主鍵時改成 upsert

Save 的 UPDATE 影響零列時，GORM 接著送出一個 INSERT ... ON CONFLICT ("id") DO UPDATE。GORM Save 原始碼裡改用 upsert 的條件是「更新沒有錯誤、影響零列、沒有用 Select 指定欄位」。拿一個不存在的主鍵 999 去 Save：

1g := Customer{Model: gorm.Model{ID: 999}, Name: "幽靈", Email: "ghost@example.com"}
2db.Save(&g)

1UPDATE "customers" SET "created_at"='0000-00-00 00:00:00',...,"name"='幽靈',"email"='ghost@example.com' WHERE "customers"."deleted_at" IS NULL AND "id" = 999
2INSERT INTO "customers" ("created_at","updated_at","deleted_at","name","email","id") VALUES (...,999) ON CONFLICT ("id") DO UPDATE SET "updated_at"=...,"deleted_at"="excluded"."deleted_at","name"="excluded"."name","email"="excluded"."email" RETURNING "id"

表裡多了一位 id 999 的顧客。主鍵來自請求內容的程式（例如 PUT /customers/999 直接把 body 解成 struct 再 Save），會因此建立一筆新資料。

同一個機制碰上軟刪除時，UPDATE 的 deleted_at IS NULL 讓已刪除的列影響零列，接下來的 upsert 用主鍵衝突寫進去，那個條件不在 upsert 裡。實測用 Unscoped 讀出已刪除的雅文、改名字、Save：

1db.Delete(&Customer{}, 3)
2var d Customer
3db.Unscoped().First(&d, 3)
4d.Name = "雅文（改）"
5db.Save(&d)

1UPDATE "customers" SET ...,"deleted_at"='2026-10-06 14:27:15.513',"name"='雅文（改）',... WHERE "customers"."deleted_at" IS NULL AND "id" = 3
2INSERT INTO "customers" (...,"id") VALUES (...,3) ON CONFLICT ("id") DO UPDATE SET ...,"name"="excluded"."name",... RETURNING "id"

雅文那一列仍然是已刪除的狀態，名字卻被改掉了。upsert 寫入的 deleted_at 是 struct 上帶的值，這裡的 struct 是從資料庫讀出來的，所以帶著原本的刪除時間。struct 若是從請求內容組出來的，DeletedAt 是零值，upsert 就把 deleted_at 寫成 NULL，已刪除的列被恢復：

1// 雅文仍是上一段的已刪除狀態
2in := Customer{Model: gorm.Model{ID: 3}, Name: "雅文", Email: "yawen@example.com"} // 從請求內容組出的 struct
3db.Save(&in)

1INSERT INTO "customers" ("created_at","updated_at","deleted_at","name","email","id") VALUES (...,NULL,'雅文','yawen@example.com',3) ON CONFLICT ("id") DO UPDATE SET ...,"deleted_at"="excluded"."deleted_at",... RETURNING "id"
2SELECT * FROM "customers" WHERE "customers"."id" = 3 AND "customers"."deleted_at" IS NULL ORDER BY "customers"."id" LIMIT 1

之後的 First(&c, 3) 查得到雅文，使用者刪掉的資料被一次編輯請求恢復成未刪除。

Save 適合的情形是 struct 本身就是那一列的完整內容、而且確定這一列存在且沒有被刪除（例如在交易裡用 SELECT ... FOR UPDATE 鎖住那一列再讀出、修改、寫回；只是放進交易而沒有鎖，PostgreSQL 預設的 read committed 照樣擋不住 p 與 q 互相蓋掉的遺失更新）；其他情形用 Create 建立、用 Updates 或 Update 修改，兩者都不會在找不到時建立資料。依主鍵同步外部資料的匯入工作，要的正是「有就更新、沒有就建立」，這時與其依賴 Save 的隱含行為，明寫 clause.OnConflict 讓意圖留在程式碼上。

Go 資料庫存取工具的生態現況

Go 沒有一個像 Laravel 或 Django 那樣把 ORM、驗證、後台整合在一起的主導框架，資料庫存取是各專案自己挑的。從 GitHub 的星數（2026 年 10 月查詢）看各工具受到的關注：GORM 約四萬，sqlc、sqlx、ent 各約一萬七千到一萬八千多，pgx 約一萬四千。星數量的是關注度，不是採用率；ent 是另一種 ORM，schema 寫成 Go 程式碼、再產生型別安全的查詢 API，同時帶有 ORM 與產生程式碼的性質，本模組不示範。pgx 也是 GORM 的 PostgreSQL 方言套件底下用的驅動，所以用 GORM 的專案同時也在用 pgx。

本模組示範兩種常見的做法：用 GORM 這個關注度最高的 ORM，或用 sqlc 加 pgx 這組「SQL 手寫、工具產生程式碼」的組合。團隊選哪一種，比較的是驅動入口、查詢的形狀、審查要看到什麼、團隊背景與錯誤被發現的時間點。

驅動入口：pgx 原生介面還是 database/sql

這個決定先做，因為它決定後面哪些函式庫用得上：

只要共用連線池、不必共用交易時，主程式可以用 pgxpool，再用 stdlib.OpenDBFromPool(pool) 做出一個共用同一個池的 *sql.DB，交給 GORM（postgres.New(postgres.Config{Conn: sqlDB})）或 sqlx；實測兩者共用之後池裡只開一條連線。migration 工具多半在部署步驟或啟動時另開一個 *sql.DB、跑完就關，不影響主程式選哪個入口。應用程式和 PostgreSQL 之間有一層交易模式的 PgBouncer 時，兩個入口都要另外處理：pgx 不論走哪個入口，預設都會在連線上快取預先解析的查詢，實測會出現 prepared statement "stmtcache_…" already exists (SQLSTATE 42P05)，處理方式見 10.2 pgx：PostgreSQL 驅動的原生介面、連線池與 COPY 大量寫入〈pgx 的語句快取與 PgBouncer 交易模式〉。兩個入口可以在同一個程式裡並存；分別用 sql.Open 與 pgxpool.New 建立時各有一個連線池（連線數要合起來算），而不論池是否共用，交易都不能互通：pgx.Tx 與 *sql.Tx 是兩個不相容的型別，一段要在同一個交易裡完成的寫入，必須全部走同一個入口。

主力工具：GORM 還是 sqlc

1.17 應用程式存取資料庫的工具分層 的選型軸套到這兩個工具上：

團隊背景這一軸的理由在於改 SQL 的位置：用 sqlc 時，送出的 SQL 就是 .sql 檔裡那一段，調執行計畫就是改那一段；用 GORM 時要先把那個查詢改寫成 Raw。熟 SQL 的團隊在前一種位置上工作，習慣 ORM 的團隊在後一種。

表裡沒有 sqlx，因為它和 sqlc 處在同一側（SQL 手寫、審查看得到），差別在檢查的時間點與步驟：sqlx 不需要產生步驟，欄位錯誤到執行時才出現；只連 PostgreSQL 時，pgx 原生介面的 RowToStructByName 提供同樣的對映而不必多一個函式庫。所以 sqlx 的落點是：要走 database/sql（例如和 GORM 共用連線池，或要支援 PostgreSQL 以外的資料庫）、想手寫 SQL、又不想加產生步驟。

不同的軸給出相反的傾向時（例如團隊的背景傾向 GORM、查詢的形狀傾向 sqlc），不必二選一，看下面的混用組合。判錯的代價各軸不同：後台列表有十幾個篩選條件卻全交給 sqlc，每加一個條件就多一組 sqlc.narg ... IS NULL OR，查詢越來越長、執行計畫也可能變差；以報表為主的服務選了 GORM，多數查詢最後寫進 Raw，SQL 回到字串，產生時的檢查與 ORM 的對映兩邊都沒拿到；習慣 ORM 的團隊被要求全用 sqlc，初期每一段增刪查改都要寫 SQL 加註記，交付速度明顯變慢。

Go 專案裡 schema 的權威：migration 檔、GORM model 與 Atlas

1.17 應用程式存取資料庫的工具分層 把「schema 的權威放哪裡」列為選型軸：schema 由 model 定義時傾向 ORM，由 migration 的 SQL 定義時傾向從 SQL 產生程式碼。GORM 本身的 AutoMigrate 不適合正式環境（改名變成新增欄位、沒有變更記錄與退回方法，見 10.5 GORM：model、關聯載入與 ORM 送出的 SQL），所以用 GORM 的專案有兩種做法。一種是同樣用版本化 migration 工具、由手寫的 migration 檔當 schema 的權威，這時這個軸分不開 GORM 與 sqlc。另一種是用 Atlas 的 GORM provider（ariga/atlas-provider-gorm）從 model 算出版本化的 migration 檔，model 仍然是 schema 的權威，產生出來的每一份檔案照樣要審查；這時軸又分得開：model 是權威選 GORM 加 Atlas，migration 的 SQL 是權威選 sqlc。golang-migrate 與 goose 都是依序執行手寫的 SQL 檔；Atlas 另外能比對資料庫現況與期望的 schema、產生差異的 migration，三者在這個用途上擇一即可。

以 migration 檔當權威時，用 GORM 與用 sqlc 的差別落在「model 怎麼跟上 schema」：

• sqlc：讀 migration 目錄產生 struct，schema 改了重新產生，對不上的地方在產生或編譯時報錯。
• GORM：model 是手寫的 struct，schema 改了要手動同步 model，對不上的地方在執行時才出現，而且不一定報錯：欄位從資料表移除之後，讀取送出的是 SELECT *，不會報錯，那個欄位保持零值，寫入時才報錯；資料表多出來的欄位則一律被忽略。

用 GORM 的專案通常靠整合測試補上「model 與 schema 不一致要到執行時才發現」這個缺口：在測試環境依序套用全部 migration，再讓每個 model 實際讀寫一次。

以上都假設 schema 由這個 Go 服務擁有。資料庫被多個服務共用、schema 由另一個服務（例如 Laravel 的 migration）管理時，Go 這一側不跑 migration、也不用 AutoMigrate：sqlc 的 schema 改指向 pg_dump --schema-only 匯出的檔案，GORM 的 model 則靠整合測試對著擁有方建出的 schema 驗證；約束名稱也要照擁有方的命名判讀（Laravel 預設把唯一約束命名成 customers_email_unique）。

常見的混用組合

多數 Go 專案不只用一個工具。三種組合最常見：

混用時共用同一個交易

GORM 與 sqlc 寫在同一個交易裡的前提，是兩者都走 database/sql。sqlc 的設定檔不寫 sql_package（或寫 database/sql）時，產生的 DBTX 介面用的是 ExecContext、QueryContext 這組 database/sql 的方法，*sql.Tx 符合它。GORM 的交易函式裡，tx.Statement.ConnPool 就是那個 *sql.Tx（gorm.Config 開了 PrepareStmt 時不是，下面的型別斷言會 panic）。sqlc 這一側的查詢檔裡有這一段：

1-- name: AddNote :exec
2UPDATE orders SET note = $2 WHERE id = $1;

兩者寫在同一個交易裡：

 1err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 2	if err := tx.Model(&Order{ID: 103}).Update("amount", 999).Error; err != nil {
 3		return err
 4	}
 5
 6	sqlTx := tx.Statement.ConnPool.(*sql.Tx) // GORM 這個交易底下的 *sql.Tx
 7	q := store.New(sqlTx)                     // sqlc 產生的程式碼跑在同一個交易裡
 8	if err := q.AddNote(ctx, store.AddNoteParams{
 9		ID:   103,
10		Note: sql.NullString{String: "同一個交易", Valid: true},
11	}); err != nil {
12		return err
13	}
14	return errors.New("撤銷") // 回傳錯誤：GORM 與 sqlc 的兩筆修改一起撤銷
15})

1ConnPool is *sql.Tx: true
2tx err: 撤銷 amount: 250 note nil: true

金額仍是原來的 250、備註仍是 NULL，兩邊的修改都被撤銷了。sqlc 改成產生 pgx 原生版本（sql_package: "pgx/v5"）的話，它要的是 pgx.Tx，和 GORM 的 *sql.Tx 接不起來；這時有兩個做法：GORM 與 sqlc 各自開交易，接受它們不在同一個交易裡；或把需要一起成功的寫入全部交給 GORM，或全部交給 sqlc。

讀寫分離：GORM 的 dbresolver 與程式自己持有兩個池

讀取量大到要把查詢分給唯讀副本（replica）時，用 GORM 的專案可以用 GORM 官方維護的 dbresolver 外掛；主力是 sqlc 或 pgx 時沒有這樣的外掛，由程式自己持有兩個池。dbresolver 的路由規則在外掛裡，自己持有兩個池時寫在程式碼上，語言無關的比較見 1.17 應用程式存取資料庫的工具分層〈讀寫分離與多個資料庫：連線的路由由哪一層決定〉。

dbresolver 註冊之後，程式照常呼叫 GORM，外掛依查詢的種類選連線。db 原本用主庫的連線字串開啟；dbresolver 的設定裡另有一個 Sources 欄位可以列主庫，沒有列時主庫就是 db 本身的連線；replicaDSN 換成副本的連線字串，有多個副本就列多個：

1db.Use(dbresolver.Register(dbresolver.Config{
2	Replicas: []gorm.Dialector{postgres.Open(replicaDSN)},
3}))

下面的實測用兩個內容不同的資料庫當主庫與副本（取得套件：go get gorm.io/plugin/dbresolver@v1.6.2）：副本裡每位顧客的名字後面多了「（副本）」，查詢讀到哪一個名字，就知道它被送到哪一邊。

 1var c Customer
 2var name string
 3n := Customer{Name: "新顧客", Email: "new@example.com"}
 4
 5db.First(&c, 1)                                // 一般查詢
 6db.Clauses(dbresolver.Write).First(&c, 1)      // 指定主庫
 7db.Create(&n); db.First(&c, n.ID)              // 剛建立就讀
 8db.Transaction(func(tx *gorm.DB) error { tx.First(&c, 1); return nil })
 9db.Raw("SELECT name FROM customers WHERE id = 1").Scan(&name)
10db.Raw("WITH x AS (SELECT 1) SELECT name FROM customers WHERE id = 1").Scan(&name)

1First                                    "佳穎（副本）"
2Clauses(dbresolver.Write).First          "佳穎"
3Create then First(new id)                id=4 err=record not found
4First inside Transaction                 "佳穎"
5Raw SELECT                               "佳穎（副本）"
6Raw WITH ... SELECT                      "佳穎"

一般查詢送副本、寫入與交易裡的查詢送主庫。剛建立的顧客馬上用 First 讀，查詢送到副本而查不到；真實的副本在複製追上之後就讀得到，所以這種錯誤只在寫入後立刻讀、而且複製剛好落後的時候出現。同一個請求裡寫完就讀的查詢要寫 Clauses(dbresolver.Write)，或整段放進交易；寫完之後由下一個請求讀的路徑（建立後導向詳情頁、改完設定馬上重新載入），dbresolver 不知道上一個請求寫過，要程式自己記住這個使用者剛寫過（例如在 session 記下寫入時間，幾秒內的讀取都加 Clauses(dbresolver.Write)）。Raw 的路由看 SQL 文字：外掛的原始碼只在 SQL 以 SELECT 開頭、結尾不是 FOR UPDATE 時送副本，所以 WITH 開頭的查詢送主庫。

程式自己持有兩個池時，這些規則都寫在程式碼上：sqlc 產生的 New 收一個連線介面（DBTX），連線池與交易都符合它，呼叫端決定傳哪一個。

1primary, _ := pgxpool.New(ctx, primaryDSN) // 主庫
2replica, _ := pgxpool.New(ctx, replicaDSN) // 副本
3
4orders, _ := store.New(replica).ListOrdersByCustomer(ctx, 1) // 可以接受落後的訂單列表
5c, _ := store.New(primary).GetCustomer(ctx, 1)               // 剛寫完就讀的那一筆

store 是 10.4 sqlc：從 SQL 產生型別安全的 Go 程式碼 以 sql_package: "pgx/v5" 產生的套件，ListOrdersByCustomer 與 GetCustomer 是那一篇定義的查詢。每一個查詢送到哪裡都在呼叫的那一行看得到，代價是每個呼叫端都要做這個選擇。主庫與副本各有一個池，連線數要分開算上限；dbresolver 的情形也一樣，db.DB() 只回傳主庫的 *sql.DB，副本的池要用 dbresolver 的 SetMaxOpenConns 這組方法設定。這組方法對主庫與每一個副本設同一個值（設定裡沒有列 Sources 時主庫也包含在內），主庫要另一個上限時，在呼叫 dbresolver 的 SetMaxOpenConns 之後，用 db.DB() 取得的 *sql.DB 重設。

選型結果裡要統一的項目：連線池、例外路徑、migration 工具、錯誤值、NULL、交易傳遞、唯讀副本與記錄

選型的結果不只是一個工具名稱，因為同一個工具兩個開發者各自決定細節時，會在下面這幾處分岔：

• 連線池由哪一段程式建立、上限多少：兩處各建一個池，連線數加倍、各自的上限也就失效（池的設定見 10.1 database/sql：連線池、查詢結果的讀取與交易）。
• 主力工具與例外：一人把報表寫成 GORM 的 Raw、另一人寫成 sqlc，同一類查詢有兩種檢查時間點，例外要寫成規則（例如「報表類查詢放 query/ 用 sqlc」）。
• schema 由哪個 migration 工具管理：一人用 AutoMigrate、另一人寫 migration 檔，schema 會漂移，改名還會留下舊欄（見 10.5 GORM：model、關聯載入與 ORM 送出的 SQL〈AutoMigrate 在正式環境的限制〉）。
• 唯一約束的錯誤怎麼判讀：一人讀錯誤代碼、另一人讀約束名稱，回報給使用者的訊息就不一致（見 10.2 pgx：PostgreSQL 驅動的原生介面、連線池與 COPY 大量寫入〈錯誤：*pgconn.PgError〉）。
• 前面有沒有交易模式的連線池代理，以及驅動的查詢執行模式：一人在本機直連 PostgreSQL、另一人在正式環境經過 PgBouncer，預先解析查詢的錯誤只在經過 PgBouncer 的正式環境出現（見 10.2 pgx：PostgreSQL 驅動的原生介面、連線池與 COPY 大量寫入）。
• 主力是 GORM 時，開發與測試環境的兩種記錄：GORM 的 SQL 記錄看得到送出的語句，零值更新被略過時那裡會少一行 UPDATE；預設交易的 begin 與 commit 只在資料庫的語句記錄（log_statement）裡看得到。
• NULL 的表示：sql.NullString、*string 與 sqlc 預設的 pgtype.Text 混在同一個專案裡，轉成 domain 型別的程式就要寫三套（見 10.1 database/sql：連線池、查詢結果的讀取與交易〈Scan 與 NULL〉）。
• 「找不到」的錯誤值：sql.ErrNoRows、pgx.ErrNoRows、gorm.ErrRecordNotFound，以及 GORM 的 Find 不回錯誤；混用的專案三種都會出現，repository 要在邊界把它們轉成同一個錯誤。
• 交易物件怎麼傳進各個 repository：一人用參數傳 *sql.Tx、另一人放進 context，混用時就接不起來（傳遞方式見 1.4 Repository Adapter 實作〈Transaction 傳遞〉，誤用時的徵兆見 Transaction Propagation）。
• 要不要用 gorm.Model 的軟刪除、Save 用在哪裡：一人用軟刪除、另一人寫的報表 SQL 不加 deleted_at IS NULL，或一人用 Save 寫回整列、另一人只改欄位，同一張表上就會出現已刪除的資料被算進報表、別人的修改被蓋掉（見 10.6 GORM 的 gorm.Model、軟刪除與 Save：慣例欄位加上的查詢條件與整列寫回）。
• 有唯讀副本時，哪些路徑強制讀主庫：寫入後立刻讀的路徑一人加了 Clauses(dbresolver.Write)、另一人沒加，同一類畫面時好時壞，只在複製落後時出錯（見〈讀寫分離：GORM 的 dbresolver 與程式自己持有兩個池〉）。
• gorm.Config 的旗標由同一處設定：PrepareStmt、SkipDefaultTransaction、TranslateError 都會改變行為；開了 PrepareStmt，〈混用時共用同一個交易〉的 ConnPool.(*sql.Tx) 型別斷言會 panic。

這幾條決定了 repository 背後的 adapter 長什麼樣；adapter 對上層暴露的 port 怎麼切，見 6.6 如何新增 repository port。