資料庫端：DB-API、查詢建構器與 ORM 的寫法

程式送出的是一段描述要算什麼的文字，資料庫收下之後自己完成篩選、合併與彙總，把結果送回來。原始資料從頭到尾沒有進入程式。

Python 這一側有三種寫法，差別只在那段 SQL 由誰組出來。

自己寫 SQL 字串：sqlite3、psycopg2 這類套件遵循 DB-API 這個標準介面，程式把 SQL 交給它，它負責送出與取回。

用方法串出 SQL：SQLAlchemy Core 這類查詢建構器提供 Python 的方法對應 SQL 的子句，組出來的仍然是一段 SQL。

用類別描述表：ORM 這一類工具（SQLAlchemy、Django ORM）把資料表對應成類別、把資料列對應成物件，篩選條件寫成屬性比較，框架據此組出 SQL，並把回來的每一列包成物件。

三者的共同點比差異重要：運算在資料庫那一端發生，程式收到的是算完的結果。編譯出來的 SQL 可以直接印出來看：

1from sqlalchemy import select
2stmt = select(Customer).where(Customer.age > 18)
3print(stmt.compile(engine))
4# SELECT customer.id, customer.name, customer.age FROM customer WHERE customer.age > ?

記憶體端：pandas 與 DataFrame

搬進記憶體端的做法是把資料整批載進程式，運算由程式自己完成。pandas 屬於這一側，它的容器是 DataFrame。

1df[df["age"] > 18]

這一行沒有連線、沒有查詢語句、沒有資料庫。df 是一張已經在記憶體裡的表格，這一行做的是對一個布林陣列取值。資料的來源可以是資料庫，也可以是 CSV、日誌檔或某個 API 回傳的內容——載進來之後，接下來的每一步運算都寫成一樣的形式，來源是哪一種不再影響寫法。

兩端分工的條件：資料量、SQL 的表達能力、算完之後的用途

資料量。 記憶體端要把資料整批放進來，所以容量是硬上限；資料庫端沒有這個限制，它一次只需要把符合條件的部分送回來。

要算的運算 SQL 表達得出來嗎。 篩選、合併、分組彙總、排名，SQL 都寫得出來。統計檢定、時間序列的滑動窗口、把資料餵給模型，SQL 寫起來吃力或根本沒有對應語法，這些落在記憶體端。

算完之後還要做什麼。 結果如果只是要回傳給使用者或寫回另一張表，留在資料庫端的路徑最短——資料不必先進記憶體再送出去；如果後面還要接繪圖、統計或模型訓練，資料終究要進記憶體，那就沒有理由分兩段做。

實務上的常見形態是兩端接力：用 SQL 把資料量先壓下來，再把壓縮過的結果搬進記憶體做後面的部分。

1df = pd.read_sql("SELECT * FROM orders WHERE year = 2024", conn)
2# 這一行之後全部在記憶體裡，與資料庫無關

DuckDB：在同一個程序裡用 SQL 查 DataFrame 與檔案

DuckDB 兩邊都站：它接受 SQL，而查詢的對象可以是記憶體裡的 DataFrame，也可以是磁碟上的檔案。

1duckdb.sql("SELECT dept, count(*) c FROM emp GROUP BY dept")  # emp 是一個 DataFrame

它把「資料庫」這個角色從一台獨立的伺服器換成同一個程序裡的運算引擎，而軸本身仍在——差別只在資料要不要複製一份進 Python 的記憶體。

延伸閱讀：ORM 與 DataFrame 的分辨、SQL 與 pandas 的寫法對應、pandas 的記憶體邊界、資料庫端的工程議題

從回傳值認出手上是哪一類：資料庫端的工具回傳的是物件或資料列，記憶體端的工具回傳的是一張新的表。8.3 ORM 與 DataFrame 的分辨：回傳值的形狀、連線物件與查詢送出的時機 寫兩者各自產出什麼，以及外觀相似的方法串接底下差了什麼。

兩端共用的那套抽象：篩選、合併、分組彙總在兩端都有，而且對應得起來。8.4 SQL 子句與 pandas 方法的對應：篩選、連接、分組彙總、視窗函數，以及空值、索引與順序的語意差異 給篩選、連接、分組彙總與視窗函數在兩邊的實測比對，以及空值、索引與順序這幾處對應斷掉的位置。

記憶體端的容量上限：8.5 pandas 的記憶體邊界：資料與運算過程的佔用估算，推回資料庫、換引擎與分散式的代價 給資料量的估算方法、運算過程額外要的空間，以及越過之後三個方向各自付什麼代價。

資料庫端那一側的工程議題：連線池、交易邊界、一次請求該打幾次資料庫，在 backend 模組一。那個模組從 N+1 與延遲載入這些形態進去，並給出每請求查詢次數預算當判讀基準。

ORM 的產出與運算發生的位置

ORM 把資料表對應成類別、把資料列對應成物件。篩選條件寫成屬性的比較式，框架把它翻譯成 SQL 的 WHERE 子句。

 1from sqlalchemy import select
 2from sqlalchemy.orm import Session
 3
 4stmt = select(Customer).where(Customer.age > 18)
 5print(stmt.compile(engine))
 6# SELECT customer.id, customer.name, customer.age FROM customer WHERE customer.age > ?
 7
 8with Session(engine) as s:
 9    rows = s.scalars(stmt).all()
10    print([type(r).__name__ for r in rows], [r.name for r in rows])
11    # ['Customer'] ['A']

stmt 本身還沒有做任何運算，它是一段待送出的查詢。運算在資料庫那一端完成，回來的每一列被包成一個 Customer 實例——所以拿到的是物件，可以呼叫它的方法、走訪它關聯到的其他物件。

DataFrame 的產出與運算發生的位置

pandas 這一側的同一件事：

1df = pd.DataFrame({"id": [1, 2], "name": ["A", "B"], "age": [20, 10]})
2df[df["age"] > 18]
3#    id name  age
4# 0   1    A   20

df["age"] > 18 先算出一個布林陣列 [True, False]，外層的取值用這個陣列挑出要留下的列。整段運算發生在這個程序的記憶體裡，沒有連線、沒有 SQL、沒有另一個系統參與。

回來的是一張新的表格，不是一組物件。它可以繼續被篩選、被合併、被彙總，因為表格正是這些操作接受的輸入。

分辨 ORM 與 DataFrame 的訊號：回傳值的形狀、連線物件、查詢送出的時機

外觀相似的方法串接底下，有三個分得開的訊號。

回傳值的形狀。 一組各自獨立、可以呼叫方法的實例，是 ORM 那一側；一張有欄有列、可以繼續被篩選與彙總的表格，是 DataFrame 那一側。

有沒有連線物件。 資料庫端的工具一定要先有一個連線或 session，因為運算要送去別的地方。pandas 的操作不需要：資料一旦載進 DataFrame，之後每一步都在這份記憶體裡的副本上進行，原本那個資料庫或檔案後來有沒有變動都不影響它。

查詢送出的時機。 ORM 允許先把查詢組好、之後才送出，所以「描述」與「執行」是兩個時刻。pandas 的每一行敘述當場就算完，中間沒有待送出的狀態。

各語言生態的資料庫存取分層：手寫 SQL、查詢建構器、ORM

自己寫 SQL、用建構器組 SQL、用 ORM 對應物件，這三層在多數語言生態裡都找得到對應的套件，名字不同而分層一致。各語言的代表工具，以及手寫 SQL 再細分成驅動、結果對映、從 SQL 產生程式碼的方式，見 1.17 應用程式存取資料庫的工具分層。

DataFrame 這一層則是額外的第四種，它不在上面那條線上——它處理的是已經在記憶體裡的表格，與資料庫的存取方式無關。一般的增刪改查應用不使用它，那是 ORM 的位置。

延伸閱讀：SQL 與 pandas 的寫法對應、運算發生的位置、pandas 的記憶體邊界、ORM 的查詢反模式

這兩側共用的抽象：ORM 產生的 SQL 與 DataFrame 的方法，做的是同一組操作。8.4 SQL 子句與 pandas 方法的對應：篩選、連接、分組彙總、視窗函數，以及空值、索引與順序的語意差異 給篩選、連接、分組彙總與視窗函數在兩邊的實測比對，以及空值、索引與順序這幾處對應斷掉的位置。

分界本身：兩側的差異全部從「運算發生在哪一端」推出來。8.2 運算發生的位置 寫這條軸怎麼決定容量上限與失敗形態，以及選邊時要問的三個條件。

選了記憶體端之後的上限：8.5 pandas 的記憶體邊界：資料與運算過程的佔用估算，推回資料庫、換引擎與分散式的代價 給資料量的估算方法與越過之後的三個方向。

ORM 那一側的失敗形態：延遲載入什麼時候把一次請求變成一百次查詢，在 backend 模組一的查詢反模式。那一篇把 N+1 與長交易列成可診斷的清單，並給出每請求的查詢次數預算。

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 讓意圖留在程式碼上。

1.4 Repository Adapter 實作 把工具分成 Raw SQL、查詢建構器（Query Builder）、ORM 三類；這篇沿用那三類，再把 Raw SQL 細分成驅動、結果對映與從 SQL 產生程式碼，因為這三種工具都由程式寫 SQL，差別在取得連線並執行、把查詢結果對映成程式的值這兩項工作由誰做。

存取資料庫的工作：寫 SQL、取得連線與交易、對映結果

不論用哪一種語言、哪一個函式庫，程式從資料庫取資料都要完成三件事：

• 寫出要送出的 SQL：查詢的文字與參數。
• 取得連線並執行：從連線池取一條連線、送出查詢、需要時開始與結束交易、用完把連線放回去。
• 把查詢結果對映成程式的值：每一列的每一欄放進程式語言的變數或物件，包括 NULL 要放成什麼。

每一類工具接手這三件事裡的幾件。接手的那幾件程式就不必寫，代價是那幾件工作的實際行為——送出了哪些 SQL、什麼時候佔用與歸還連線、NULL 被放成什麼——從程式碼上讀不出來了。這三件事說明了工具接手之後看不見什麼；選型時另外還要看 schema 的權威、查詢的形狀、錯誤被發現的時間點與部署環境，見〈選型：從要交出的資料存取層往回看〉。

各類工具與各語言的代表工具

表上的「多數附帶連線池」在不同語言的意思不同，見〈各語言執行模型下的連線模型〉。

「產生程式碼」本身是另一條軸，不只出現在第三類。從 schema 產生有型別 API 的工具分兩種：讀資料庫現有 schema 的（Go 的 SQLBoiler、go-jet，Java 的 jOOQ，Rust 的 Diesel），以及從自己的 schema 定義檔產生程式碼、並由它產生 migration 的（Go 的 ent 寫在 Go 程式碼裡，TypeScript 的 Prisma 寫在 schema.prisma），ent 與 Prisma 的 schema 權威在那份定義檔上。兩種的查詢都由方法呼叫組出，所以歸在 Query Builder 或 ORM，而欄位改名同樣在編譯時失敗。表上第三類特指從手寫的 SQL 產生程式碼的工具。

每一類接手之後看不見的行為

驅動與標準介面

用驅動直接寫 SQL 時三件事大多看得見，看不見的是驅動自己的預設行為：

• 連線什麼時候還回池裡：各語言歸還連線的時機不同。Go 的 database/sql 每次查詢向池借一條連線，查詢結果的讀取物件（cursor，本站譯為查詢結果的讀取物件，見 Cursor）關閉時才放回去；讀到最後一列時會自動關閉，讀到一半就離開、又沒有呼叫 Close 時，那條連線就一直被佔著。這種借了不還的情形是連線洩漏（Connection Leak），累積到池的上限時症狀才浮現。Python 的 SQLAlchemy 與 psycopg_pool 由程式明確借出連線，with 區塊結束時歸還，洩漏發生在借出連線的那一段沒有收尾（psycopg 預設的 cursor 在執行時就把結果全部讀進來）。PHP-FPM 在請求結束時一併釋放。
• NULL 的對應：每種語言要有一個能表示「沒有值」（NULL）的型別。Go 的 string 零值是空字串，沒有一個值代表 NULL，所以要用指標或 sql.NullString；PHP 與 Python 的動態型別直接用 null／None。
• 預先解析的查詢：有些驅動會把執行過的查詢在連線上建成預先解析的查詢（prepared statement），下次執行同一段 SQL 只送名字與參數。那個名字只存在於建立它的那一條資料庫連線上，而 PgBouncer 這類連線池代理在交易模式（transaction pooling）下，同一條應用程式連線的下一個交易可能被分到另一條資料庫連線，名字因此對不上。各驅動的預設不同：Go 的 pgx 每條連線都快取；PHP 的 PDO pgsql 驅動預設在伺服器端建立具名的 pdo_stmt_…，Laravel 沒有改掉這個預設；Python 的 psycopg 3 在同一段查詢執行過 5 次之後、第 6 次執行時才建立（prepare_threshold，預設 5）；Django 預設用用戶端綁定，不建立。接上交易模式的代理時，處理方式是讓代理追蹤這些名字（PgBouncer 1.21 起的 max_prepared_statements，1.24 起預設開啟），或關掉驅動的這個行為。
• 參數一律用佔位符傳：值拼進 SQL 字串就是 SQL 注入（SQL injection）的入口，這件事在每一層工具都成立。

結果對映

依欄名對映讓程式不必逐欄讀取，而對映發生在執行時：查詢結果多了一個物件裡沒有的欄位、或欄位改了名字，錯誤在執行那一行時才出現。最常見的情形是查詢寫 SELECT *，資料表後來新增一個欄位：在 sqlx、psycopg 的 class_row 這類嚴格對映裡，所有對映到同一個型別的查詢從 migration 套用的那一刻起同時開始失敗，而程式碼一行都沒改；PDO 的 FETCH_CLASS 則把多出來的欄位塞成物件的動態屬性，只發出 Deprecated 警告。

從 SQL 產生程式碼

從 SQL 產生程式碼的工具讀 schema 與手寫的 SQL，產生呼叫那段 SQL 的函式，以及參數與結果的型別。欄位拼錯、型別不符在產生程式碼時就被擋下，而 SQL 仍然是人寫的、審查時看得到。代價有兩項：產生步驟變成建置流程的一部分（schema 改了要重新產生；產生出來的程式碼二選一：提交進版本控制，或在建置時產生）；以及每一段 SQL 在產生時就固定了，「使用者勾了哪些篩選條件就加哪幾個 WHERE」這種動態組合的查詢寫起來吃力。

Query Builder

Query Builder 用方法呼叫組出 SQL，每個方法大致對應一個子句（where、join、orderBy），所以讀程式碼仍然看得出送出的 SQL 長什麼樣，而且條件可以依執行時的輸入逐步加上去，正好補上從 SQL 產生程式碼的弱項。Query Builder 不負責 model 之間的關聯，也不追蹤物件的變更。

動態組合的條件有兩處容易出錯。排序欄位、排序方向這類識別字沒辦法用佔位符傳，由使用者決定時要用程式裡的白名單對映成欄位名（GORM 的 Order(userInput) 這類寫法會把輸入原樣放進 SQL）。另外，GORM 用 struct 當查詢條件時同樣略過零值欄位，「狀態 = 0」「啟用 = false」這種篩選會被靜默丟掉，條件要用 map 或明確的 Where("col = ?", v)。

ORM

ORM 接手寫 SQL、取得連線與交易、對映結果這三件事，所以看不見的行為最多。四類最常在正式環境造成問題。

ORM 送出的查詢次數：延遲載入與 N+1

延遲載入（lazy loading）在程式每次存取關聯屬性時才發出一次查詢。這個存取寫在迴圈裡，迴圈跑 N 次就多出 N 次查詢，加上取主列表的那一次就是 N+1（見 1.13 應用層查詢反模式與 Query 預算）。各框架都有預先載入（eager loading）的寫法：Laravel 的 with、SQLAlchemy 的 selectinload、Django 的 select_related 與 prefetch_related、GORM 的 Preload。也有在開發時把延遲載入變成錯誤的開關：Laravel 的 Model::preventLazyLoading()、SQLAlchemy 關聯設定的 lazy="raise"。GORM 沒有延遲載入，它的 N+1 來自程式自己在迴圈裡發的查詢（見 10.5 GORM：model、關聯載入與 ORM 送出的 SQL）。

ORM 的交易邊界：GORM、Laravel、Django 與 SQLAlchemy

同一段「先寫 A 再寫 B」的程式碼，在各 ORM 裡的交易邊界不同（交易範圍怎麼劃見 Transaction Boundary）：

• 每一次寫入自動包成一個交易（GORM 的預設行為）：A 與 B 是兩個各自提交的交易。
• 不自動包、要程式明確開始（Laravel 的 DB::transaction；Django 預設也是自動提交，要用 transaction.atomic，或設定 ATOMIC_REQUESTS 讓每個請求包成一個交易）：A 與 B 是兩個各自自動提交的語句。
• 第一次寫入時自動開始交易、到 commit() 才提交（SQLAlchemy 的 Session）：A 與 B 在同一個交易裡，忘了呼叫 commit() 則兩者都不會寫入。

前兩種情形下，B 失敗時 A 不會撤銷，除非程式自己把兩者包進一個交易。

ORM 寫回哪些欄位：變更追蹤、全部欄位與零值

ORM 要決定 UPDATE 要寫哪幾個欄位，常見的規則有三種：

• 變更追蹤（dirty tracking）：Eloquent 與 SQLAlchemy 追蹤哪些屬性被改過，只寫改過的。
• 寫回全部欄位：Django 的 save() 預設把 model 的每個欄位都寫回（傳 update_fields 才只寫指定的），兩個請求同時改同一列的不同欄位時，後寫的請求會用它讀出時的舊值，蓋掉先寫的請求改過的欄位。
• 跳過零值：GORM 的 Updates 傳入 struct 時不追蹤變更（Save 則寫回全部欄位，找不到那一列時還會改成 upsert，見 10.6 GORM 的 gorm.Model、軟刪除與 Save：慣例欄位加上的查詢條件與整列寫回），而是跳過值為零值的欄位。Go 的 struct 欄位沒有「未設定」這個狀態，沒給值就是 0、空字串或 false（Go 稱為零值），所以 GORM 分不出「沒有設定」與「要改成 0」。

以「把金額從 300 改成 0」為例：變更追蹤看到金額被改過，寫入 0；GORM 看到金額是零值，當成沒有設定而略過金額這一欄，也不回報錯誤；model 沒有其他要寫的欄位時不送出任何 UPDATE，model 有 UpdatedAt（gorm.Model 就帶這個欄位）時仍會送出只更新 updated_at 的 UPDATE，影響列數是 1，看起來像更新成功。

schema 的權威在 model 還是 migration

有的 ORM 從 model 產生 schema（Django 的 makemigrations、GORM 的 AutoMigrate），有的 model 與 schema 分開定義（Laravel 的 migration 與 Eloquent model 是兩份檔案）。從 model 產生時，欄位改名最容易出錯：GORM 的 AutoMigrate 把它當成新增一欄、舊欄留著；Django 的 makemigrations 會詢問是不是改名，回答否就產生刪除舊欄加新增一欄的 migration，舊欄的資料跟著刪掉。產生出來的 migration 要逐份讀過。

這四類看不見的行為各有看得到它的地方：送出幾次查詢與寫回哪些欄位，看 ORM 的 SQL 記錄（應用程式端印出它送出的語句，兩種記錄的開啟方式與差別見 Query Log）；交易邊界看資料庫端的語句記錄（PostgreSQL 的 log_statement），因為有的 ORM（GORM）的 SQL 記錄不印 begin 與 commit；schema 的那一類看的是產生出來的 migration 檔。程式碼審查時看的是 ORM 的 SQL 記錄、資料庫的語句記錄與 migration 檔，而不只是方法呼叫。

各語言執行模型下的連線模型

「工具附帶連線池」這句話在三種語言裡的意思不同，因為池活在程序（process）裡，而三種語言的服務用不同的方式使用程序（池本身的概念見 Connection Pool）：

所以「池的大小設多少」在 Go 是一個設定，在 Python 要乘上 worker 數，而 gunicorn 用多執行緒或 gevent worker 時，一個程序裡的每個執行緒或協程各自取用連線，所以每個程序同時持有的連線不只一條。PHP-FPM 沒有程序內的池，連線數跟著 FPM 的 worker 數走（FPM 的程序模型見 PHP-FPM：常駐 PHP worker 的程序管理與主要的調校旋鈕），每台機器的 pm.max_children 乘上機器數就是可能的連線數。PHP 改成常駐 worker（Laravel Octane、FrankenPHP 的 worker 模式）之後，應用程式跨請求留在記憶體裡，資料庫連線也跟著保留，行為往 Python 那一列靠（常駐 worker 模型本身見 常駐 worker 模型：FrankenPHP worker 模式、Laravel Octane 與跨請求殘留的狀態）。

三種情形都用同一條原則估算上限：全部實例加起來的連線數，要小於資料庫的 max_connections 扣掉維運保留的那幾條（有些託管的資料庫服務另外保留一部分給自己的管理程式）。例如 8 個 Go 實例、每個的池上限設 25，總共 200 條，超過 PostgreSQL 預設的 max_connections = 100；平時流量用不滿池，問題要到流量尖峰，或滾動部署時才出現——滾動部署期間新實例已經啟動、舊實例還沒關閉，實例數短時間變多，新開的連線收到 FATAL: sorry, too many clients already。PostgreSQL 每條連線是一個獨立的程序，上限不能無限調高（成本見 PostgreSQL Connection Scaling：process-per-connection model 跟為什麼 pooler 是必裝）。

這張表描述的是各語言最常見的部署方式。同一種語言部署成 serverless 函式時，每個並行的執行個體各自有池，連線數跟著並行數走，行為接近 PHP-FPM 那一列；Python 用 async worker 時，一個程序內的協程共用同一個池。

超過時在應用程式與資料庫之間加一層連線池代理（Connection Pooler），讓多個實例共用較少的資料庫連線。加了代理之後，上面那條原則的右邊換成代理接受的應用程式連線上限（PgBouncer 的 max_client_conn），實際連到資料庫的連線數改由代理自己的池設定決定（default_pool_size 是每一組使用者與資料庫各自的上限，總數還要乘上組合數）；PgBouncer 的設定與故障演練見 PostgreSQL pgBouncer 配置 + 連線池治理。

各語言讀取約束名稱的位置

資料庫回報唯一約束違反時，錯誤代碼（PostgreSQL 是 SQLSTATE 23505）只說「有唯一約束被違反」，是哪一個約束要看約束名稱。這個轉換是把資料庫錯誤轉成業務錯誤（error translation）的一部分，約束本身見 Constraint。以下以 PostgreSQL 為例，它的錯誤回報帶有約束名稱欄位，三種語言的驅動都直接暴露；MySQL 的驅動只給錯誤代碼 1062（SQLSTATE 23000）與訊息文字，索引名稱要從訊息解析；SQLite 只回報欄位名稱（UNIQUE constraint failed: customers.email）。

所以建表時替約束取明確的名字（SQL 寫 CONSTRAINT customers_email_key UNIQUE (email)；schema 由 Django model 管理時寫 Meta.constraints 的 UniqueConstraint(fields=["email"], name="customers_email_key")），程式就能依名字回報「email 已被使用」而不是籠統的「資料重複」；讓資料庫自動命名，名字會隨建表工具與版本而不同。

讀寫分離與多個資料庫：連線的路由由哪一層決定

讀寫分離（Read-Write Split）把寫入送到主庫（primary）、把讀取送到一個或多個唯讀副本（replica）。副本的資料由主庫複製過去，會落後一段時間（Replication Lag），所以每一個查詢送到哪一邊，決定了它讀不讀得到剛寫入的資料。〈存取資料庫的工作：寫 SQL、取得連線與交易、對映結果〉裡「取得連線並執行」那件工作因此多了一個問題：這個查詢要用哪一個資料庫的連線。決定的位置有三種：應用程式自己、ORM 或框架、資料庫前面的代理。

應用程式持有多個連線池，程式明確選：主庫一個池、副本一個池，每個 repository 方法自己決定用哪一個，可以預設全部讀主庫、只把能接受落後的查詢指定給副本。驅動、結果對映與從 SQL 產生程式碼這幾類工具沒有路由功能，用的就是這一種（sqlc 產生的程式碼接受一個連線介面，傳主庫的池或副本的池都可以）。每個查詢去哪裡都寫在程式碼上，代價是每個方法都要做這個決定。

ORM 或框架依規則路由：程式照常呼叫，框架依查詢的種類替它選連線。規則各框架不同，而這些規則就是這一層在程式碼上看不見的行為：

SQLAlchemy 沒有內建這個功能，要覆寫 Session.get_bind 自己寫規則。

GORM 那一列是實測結果（dbresolver v1.6.2，用兩個內容不同的資料庫當主庫與副本，看每個查詢讀到哪一邊的資料，程式與輸出見 10.7 Go 專案的資料庫存取工具選型：GORM、sqlc 與 pgx 的組合〈讀寫分離：GORM 的 dbresolver 與程式自己持有兩個池〉）；Laravel 那一列取自它的 Connection::getReadPdo：交易層數大於零、或開了 sticky 而這個連線物件已經寫過資料，就改用寫入的連線；Django 的官方文件明寫它的主從路由範例不處理複製延遲，也不考慮交易與路由的交互作用。表上的差異集中在剛寫入之後的讀取（Read-After-Write Consistency），而這種讀取有兩種形狀。一種在同一個請求裡：建立訂單之後，同一個請求接著讀出訂單內容放進回應；Laravel 的 sticky 處理的是這一種，GORM 的 dbresolver 不處理。另一種跨兩個請求：使用者送出表單，寫入的請求回應之後瀏覽器被導回列表頁，列表是一個新的請求；sticky 記在連線物件上，新請求不知道剛才寫過，三個框架都照常把列表查詢送到副本，複製落後時讀不到剛寫入的那一筆。同一個請求裡的讀取，由程式在那個查詢上指定主庫：GORM 寫 Clauses(dbresolver.Write)，Laravel 的 Query Builder 寫 useWritePdo()、Eloquent 寫 Model::onWriteConnection()，Django 寫 .using("default")（default 是主庫的資料庫別名）。跨請求的讀取要程式自己記住「這個使用者剛寫過」，常見做法是寫入時在 session 記下時間，之後幾秒內這個使用者的讀取都送主庫。

資料庫前面的代理依規則路由：應用程式只連一個位址，由代理判斷每個語句送哪裡（MySQL 的 ProxySQL 用比對 SQL 文字的規則，見 MySQL ProxySQL 配置：connection / query / route / response 四段 lifecycle 跟 query rule 設計；PostgreSQL 有 Pgpool-II 這類代理）。程式碼完全不用改，而代理同樣要判斷交易內的讀取與剛寫入之後的讀取，判斷依據只剩 SQL 文字與連線狀態，比框架知道的更少。

另有兩個機制也決定連線去哪一台機器，但只在建立連線時決定，不逐一判斷查詢。雲端資料庫服務提供一個讀取端點（reader endpoint），用 DNS 在多個副本之間分配連線，它不知道各副本落後多少（見 Aurora Read Replica Scaling：15 replica 上限、lag profile、headroom 預留與 fleet 治理）；PostgreSQL 的用戶端（libpq、pgx）在連線字串裡列多台主機並設 target_session_attrs（primary、prefer-standby 等），在建立連線時挑出主庫或副本，它決定的是每一條連線連到哪一台，不替每一個查詢挑，用途是讓兩個池的連線字串在主庫切換之後仍然指對機器。

服務要不要加唯讀副本，先看讀取慢的原因：查詢次數或缺索引造成的慢（見 1.13 應用層查詢反模式與 Query 預算），加副本只是把同樣的浪費分到更多機器上；同一批資料被反覆讀取的熱讀，先加快取（見 模組二：快取與 Redis）；寫入量大的服務加副本沒有幫助，副本還要重放同樣多的寫入，落後得更多。副本的容量與落後的量測見 1.1 高併發下的 SQL 讀寫邊界〈Read Replica Scaling〉。

決定加副本之後，先選預設方向。框架的路由規則是「預設送副本，例外送主庫」，每一條不能讀舊資料的路徑都要被找出來列為例外；程式自己持有兩個池時可以反過來，「預設送主庫，只把報表、搜尋、統計這類能接受落後的查詢送副本」，要找出來的只剩送副本的那幾條，漏掉的路徑讀的是主庫，不會讀到舊資料。

選了「預設送副本」時，逐條列出三類路徑，再對照所用框架或代理的規則，決定每一條由誰把讀取送到主庫：

• 寫入之後馬上讀：分成同一個請求裡與跨請求兩種。同一個請求裡的，在那個查詢上指定主庫；跨請求的，由程式記住這個使用者剛寫過。跨請求的那一種用「寫入後幾秒內送主庫」時，落後超過那幾秒就失效；需要確定讀到的時候，改成比對複製位置：寫入時記下主庫的位置（PostgreSQL 的 pg_current_wal_lsn()，或 MySQL 那筆交易的 GTID），讀取前確認副本已經重放到那個位置（PostgreSQL 的 pg_last_wal_replay_lsn()，MySQL 的 WAIT_FOR_EXECUTED_GTID_SET），或在副本查不到時回主庫再查一次（剛建立的短網址被別人點開這種情形，點的人沒有建立者的 session，只能用這個做法）。Django 的路由器拿不到請求物件，記在 session 的寫入時間要另外經由 middleware 放進 context 變數，路由器才讀得到；不用 session 的 API（JWT 驗證的行動 App）把寫入時間放在客戶端帶回的標頭或 cookie 裡。
• 讀出的結果決定接下來的寫入：檢查庫存再扣、檢查 email 有沒有被用過再建立。這類讀取讀到舊值就會寫錯，一律送主庫，需要鎖住那一列時用 SELECT ... FOR UPDATE（Laravel 的 lockForUpdate()、Django 的 select_for_update()）；Django 的路由器在 transaction.atomic 裡照樣把一般讀取送副本，這一類要明確指定主庫。
• 背景工作讀剛寫入的資料：寫入之後派送的佇列工作（Laravel 的 job、Celery 的 task）在另一個程序裡執行，既不在同一個請求裡，也沒有 session 可記。工作要在交易提交之後才派送（Laravel 的 afterCommit、Django 的 transaction.on_commit），並由工作自己指定讀主庫，或帶著要處理的資料內容出發。

分出唯讀副本之後，每個應用程式實例對資料庫開的連線總數也跟著變：每個實例對主庫與每一個副本各開一個池，所以「實例數 × 池的上限」要對主庫與每一個副本各算一次，各自小於那個資料庫的 max_connections（Python 的多 worker 部署再乘上 worker 數）。ORM 提供的「取得底層連線池」方法多半只回傳主庫那一個，副本的池要另外設上限與監控（GORM 的情形見 10.7 Go 專案的資料庫存取工具選型：GORM、sqlc 與 pgx 的組合）。

多個資料庫是另一種情形：資料依業務拆在不同的資料庫裡（例如訂單一個、會員一個），而不是同一份資料的副本。各框架都支援一個程式連多個資料庫（Laravel 的 DB::connection('name')、Django 的 using()、GORM dbresolver 依 model 指定資料庫），而三件事跨不過資料庫的邊界：一個交易、外鍵與 JOIN。Django 的文件明寫不支援跨資料庫的外鍵與多對多關聯。需要一起成功的寫入落在兩個資料庫時，交易邊界要重新設計（見 Transaction Boundary）。

選型：從要交出的資料存取層往回看

選型要交出的是專案的資料存取層：各個 repository 用哪一類工具寫、哪些例外。比較的軸取自那一層要承擔的事，而不是工具本身的特性清單；其中「schema 的擁有者」「應用程式與資料庫之間的基礎設施」與「讀取流量與資料庫拓撲」三列是部署與擁有權的環境，其餘是程式碼庫自己的性質：

多數專案不只用一類。三種語言都常見同一個組合：一般的增刪查改用框架或專案選定的 ORM，報表與效能敏感的查詢直接寫 SQL（Laravel 的 DB::select、Django 的 raw()、GORM 的 Raw），或在 Go 裡改用從 SQL 產生程式碼的 sqlc。組合本身不是問題，要留意的是兩條路徑共用同一個連線池與交易：ORM 開的交易裡，直接寫的 SQL 也要走同一個交易物件，否則它會從池裡另取一條連線、跑在交易之外；交易物件怎麼一路傳進各個 repository，以及 Laravel、Django 為什麼不必傳，見 Transaction Propagation。

各語言的實作

• Go：Go 的資料庫存取模組 依本篇的分層，逐一示範 database/sql、pgx、sqlx、sqlc 與 GORM，每一篇的輸出都在 PostgreSQL 上實際跑過。
• Python：ORM 與 DataFrame 在回傳值與查詢送出時機上的差別見 8.3 ORM 與 DataFrame 的分辨：回傳值的形狀、連線物件與查詢送出的時機。
• PHP：PHP-FPM 的程序模型見 PHP-FPM：常駐 PHP worker 的程序管理與主要的調校旋鈕，連線跨請求保留的常駐 worker 模型見 常駐 worker 模型：FrankenPHP worker 模式、Laravel Octane 與跨請求殘留的狀態。

它買到什麼

型別與工具：欄位變成類別的屬性，屬性名稱由編輯器補全、由編譯器或型別檢查確認，而字串拼出來的 SQL 兩者都沒有；model 與資料表的 schema 一不一致，仍要到執行時才知道。

組合性：篩選條件可以分段加上去再一次送出，不必自己拼字串。

跨引擎的方言差異：同一段程式碼在不同資料庫上產生的 SQL 不同，由 ORM 吸收。

它讓什麼變得看不見

程式碼與實際送出的 SQL 之間隔了一層，所以這一段會打幾次資料庫在程式碼上讀不出來。兩種常見的形態：

• 延遲載入：存取一個關聯屬性才去查一次，寫在迴圈裡就變成一次請求打上百次查詢，也就是 N+1；沒有延遲載入的 ORM（例如 Go 的 GORM），N+1 來自程式自己在迴圈裡發的查詢
• 交易邊界不明：一段程式碼是不是在同一個交易裡，由框架的設定與作用域決定而不由這幾行決定（見 transaction boundary）

處置的方向一致：讓實際送出的 SQL 現形。多數 ORM 有印出查詢的開關，開發時開著。

概念位置

ORM 站在應用程式與資料庫之間，運算仍然發生在資料庫那一端——它交出去的是描述，回來的是結果。這一點決定了它的容量上限跟著資料庫走，與把整批資料搬進記憶體再算的工具（DataFrame 那一類）分屬兩側。

連線這一層同樣被它蓋住：每一段查詢佔用的仍然是 connection pool 裡的一條連線，而是哪一條、佔多久由框架的作用域與連線池的設定決定。

它也不是查詢語言的替代品。複雜的分析查詢用 ORM 表達得很吃力，多數專案在那些地方直接寫 SQL。

往下走

ORM 在應用程式存取資料庫的工具裡排在哪一層、和驅動、結果對映、從 SQL 產生程式碼、Query Builder 各接手哪幾件事，以及 Go、PHP（Laravel）、Python 的對應工具，在 1.17 應用程式存取資料庫的工具分層；Go 的 GORM 實際送出的 SQL（預設交易、零值更新、Preload）在 10.5 GORM：model、關聯載入與 ORM 送出的 SQL。它與 DataFrame 各自產出什麼、以及外觀相似的方法串接底下差了什麼，在 8.3 ORM 與 DataFrame 的分辨：回傳值的形狀、連線物件與查詢送出的時機。ORM 送出的 SQL 要開 SQL 記錄才看得到，應用程式端與資料庫端的記錄各記到什麼見 Query Log；ORM 替每個查詢自動加上「未刪除」條件的做法見 Soft Delete。延遲載入與長交易的可診斷清單、以及每請求的查詢次數預算，在 1.13 應用層查詢反模式與 Query 預算。

概念位置

1-- 刪除：把標記寫上去
2UPDATE customers SET deleted_at = now() WHERE id = 3 AND deleted_at IS NULL;
3
4-- 之後的每一個查詢都要帶這個條件
5SELECT * FROM customers WHERE email = 'yawen@example.com' AND deleted_at IS NULL;

各語言的 ORM 用不同的方式加上那個條件：Laravel 的 model 使用 SoftDeletes trait 之後，查詢自動帶 whereNull('deleted_at')，withTrashed() 連同已刪除的一起查、forceDelete() 永久刪除、restore() 復原；GORM 的 model 帶 gorm.DeletedAt 型別的欄位（嵌入 gorm.Model 就有）時同樣自動加條件，Unscoped() 取消它（實測見 10.6 GORM 的 gorm.Model、軟刪除與 Save：慣例欄位加上的查詢條件與整列寫回）；Django ORM 與 SQLAlchemy 沒有內建，要自己加條件（Django 改寫 model 預設的查詢入口 Manager，SQLAlchemy 在查詢上加篩選），或用第三方套件。Django 改寫預設 Manager 之後，ORM 自己仍有一條路徑不經過它：從訂單存取所屬顧客（order.customer）這種正向關聯走的是 _base_manager，讀得到已刪除的顧客。

條件由 ORM 加，所以不經過那個 ORM 的路徑都看得到已刪除的資料：手寫的 SQL（GORM 的 Raw、Laravel 的 DB::select）、報表與資料倉儲的匯出、共用同一個資料庫的其他服務、直接連進資料庫查問題的人。刪除前就存好的讀取結果也一樣：快取裡的那一筆與搜尋索引裡的文件不會因為加了標記就消失，要在刪除時一併清掉（見 Cache Invalidation、Search Index）。

可觀察訊號與例子

• 刪掉再建立同一筆資料撞唯一約束：顧客刪除帳號之後用同一個 email 重新註冊，email 上的唯一約束仍然看得到那一列，回報重複（PostgreSQL 的 SQLSTATE 23505）。PostgreSQL 與 SQLite 的處理方式是只對未刪除的列建唯一索引（部分索引（partial index），CREATE UNIQUE INDEX ... ON customers (email) WHERE deleted_at IS NULL）；MySQL 沒有部分索引，常見做法有兩種：加一個未刪除時等於 email、刪除後為 NULL 的產生欄位（generated column），在它上面建唯一索引，因為唯一索引允許多個 NULL；或讓 deleted_at 用 0 代表未刪除（不用 NULL），再建 (email, deleted_at) 的複合唯一索引。換成部分索引之後，INSERT ... ON CONFLICT (email) 要寫出同樣的 WHERE deleted_at IS NULL 才對得上那個索引，否則 PostgreSQL 回報找不到相符的約束（42P10）。應用程式端的唯一性檢查也要排除已刪除的列（Laravel 的驗證規則寫 Rule::unique('customers')->withoutTrashed()）。
• 外鍵不會因為軟刪除而動作：軟刪除是 UPDATE，外鍵的 ON DELETE CASCADE 與「還有子表資料就不准刪」的檢查都不會被觸發。顧客被軟刪除之後，那位顧客的訂單仍然指著那一列；訂單列表用 ORM 載入顧客時，Laravel 拿到的是 null、GORM 是零值的 struct，Django 的正向關聯則讀到已刪除的顧客。之後要永久刪除那位顧客，外鍵才擋下來（23503）。
• 計數對不上：頁面上的顧客數由 ORM 算（帶條件），報表直接寫 SQL 算（不帶條件），兩個數字差的就是已刪除的那些。
• 刪除請求沒有刪掉個資：使用者依個資法規要求刪除時，軟刪除只加了標記，資料原封不動，要另外做永久刪除或匿名化（見 PII）。
• 增量同步收不到刪除：依 updated_at 取「上次之後改過的列」的同步，要靠軟刪除同時更新 updated_at 才看得到刪除。Laravel 的 SoftDeletes 會一併更新，GORM 的軟刪除只寫 deleted_at，那種同步永遠看不到 GORM 刪掉的列；同步要另外取 deleted_at 晚於上次同步的列，或改用資料庫的變更紀錄（見 Change Data Capture）。

設計責任

用軟刪除之前先決定它要解決的是哪一件事。保留稽核紀錄、誤刪後能復原、表示業務狀態這三個目的各有替代做法，不會帶來唯一約束衝突、手寫 SQL 讀到已刪除列、計數不一致與增量同步收不到刪除這些問題；讓識別碼不被重用則是軟刪除本身要解的問題：

• 保留稽核紀錄：把刪除事件寫進稽核表、原資料照常刪除（見 Audit Log），或整個領域改用事件記錄狀態（見 Event Sourcing）。
• 誤刪後能復原：刪除時把那一列搬到封存表（例如 customers_archive），復原時搬回來；主表上沒有已刪除的列，唯一約束、手寫 SQL 與計數都不受影響，代價是子表的資料要一起處理。
• 帳號停用、訂單取消這類業務狀態：它們本來就是業務上的一個狀態，用狀態欄位表示，查詢條件寫在業務邏輯裡，不必套用刪除的慣例。
• 讓識別碼不被重用、讓關聯資料不失去參照：這是軟刪除最直接的理由，例如短網址被刪除之後，短碼要一直被佔著，不能發給別人（見 0.24 短網址服務的實作：短碼生成、對照表儲存、轉址快取與點擊紀錄〈對照表：儲存選型、欄位與分片〉）。

決定用軟刪除時，同時決定四件事：

• 刪除之後同一個值能不能再用：能的話（顧客刪除帳號後可以用同一個 email 重新註冊），唯一約束改成只涵蓋未刪除的列；不能的話（短碼），保留涵蓋全表的唯一約束。
• 不經過 ORM 的讀取怎麼排除已刪除的列：手寫 SQL 自己加條件，或在資料庫端提供只含未刪除列的 view、對報表帳號設 Row-Level Security 政策；其他服務與直接連進資料庫的人，只有資料庫端的做法擋得到。
• 子表的資料在父列被軟刪除時怎麼處理：一起軟刪除、照常保留並在畫面上標示，或禁止刪除還有子表資料的父列。
• 已刪除的資料保留多久之後永久刪除：到期時子表若因為法規（例如帳務紀錄）要保留，外鍵會擋下永久刪除，這時改成把個資欄位匿名化（清空姓名、email），只留下那一列與它的主鍵。

概念位置

兩種記錄之外，分散式追蹤（tracing）也記得到資料庫呼叫：OpenTelemetry 這類工具在每個資料庫呼叫上記一段 span（Go 的 pgx 透過 QueryTracer 介面接上），同時帶著所屬的請求與耗時，適合回答「這個請求為什麼慢」。

兩種記錄各有記不到的內容。GORM 預設把每個寫入包進一個交易（SkipDefaultTransaction 可以關掉），那個交易的 begin 與 commit 不出現在 GORM 自己的記錄裡，只看得到資料庫端；資料庫端看不到這個語句是從程式的哪一行送出的。Go 的 pgx 預設在連線上快取 Prepared Statement，在 PostgreSQL 的記錄裡顯示成 execute stmtcache_…，參數另外記在 DETAIL 那一行。

可觀察訊號與例子

• ORM 送出的查詢次數：同一個形狀的查詢在應用程式端的記錄裡連續出現 N 次，是 N+1（見 1.13 應用層查詢反模式與 Query 預算）。
• 應該出現卻沒出現的語句：GORM 用 struct 更新時跳過零值欄位，記錄裡的 UPDATE 少了那個欄位，要改的欄位全是零值時整句 UPDATE 都不會出現（model 帶 UpdatedAt 時只剩更新 updated_at 的那一句）；交易邊界不如預期時，資料庫端的 begin 與 commit 位置對不上（各 ORM 的差異見 1.17 應用程式存取資料庫的工具分層〈ORM 的交易邊界：GORM、Laravel、Django 與 SQLAlchemy〉）。
• 正式環境的慢查詢：用 log_min_duration_statement 只記慢的語句；要看哪些查詢加總起來最耗時，PostgreSQL 的 pg_stat_statements 依查詢形狀彙總次數與總耗時，比逐筆記錄省空間。把慢查詢記錄定期彙整、接進審查流程的做法見 1.14 Production Slow Log Closed Loop。

設計責任

開發與測試環境把兩種記錄都打開，審查 ORM 程式碼時對照的是它們，不只是方法呼叫。正式環境的 log_statement = 'all' 與應用程式端的逐筆記錄量都很大，而且參數裡有 email、地址這類個人資料，所以正式環境通常只記慢查詢與 DDL，記錄的保存與遮罩比照其他含個資的記錄處理（見 7.4 資料保護與遮罩治理）。追查「這一筆資料被誰改過」用 Audit Log（PostgreSQL 端可以用 pgaudit 擴充記錄指定的語句類別）；語句記錄保存期短、正式環境不一定開著，靠不住。