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。