feat(builder): InsertDefaults for INSERT ... DEFAULT VALUES

[klaidliadon]

After #50, InsertRecord rejects records whose Map returns zero columns and points callers at sq.Expr as the escape hatch — bypassing the type-safe builder. Legitimate use cases (sequence tables, audit rows, any all-DB-defaulted insert) deserve a first-class path.

DB.SQL.InsertDefaults("orders").Suffix(`RETURNING "id"`)
// → INSERT INTO orders DEFAULT VALUES RETURNING "id"

Closes #51.

---

Design

DefaultValuesBuilder is a separate small type, not overrides on pgkit.InsertBuilder. The plan went through three Codex review rounds before settling here:

• v1 auto-detect rejected — silently turning bugs (forgot to set fields) into valid SQL is a one-way door we can't walk back.
• v2 embed-and-shadow rejected — pgkit.InsertBuilder embeds sq.InsertBuilder (22 chain methods). Overriding ToSql + Suffix only handles 2; the other 20 inherited methods silently strip pgkit state. Dishonest surface area.
• v3 → v4 separate-type — new type exposes only what it supports: ToSql, Suffix(string), Err. Codex green-light on v4.

Full plan + decision log: tmp/insert-default-values/2026-06-02-plan.md (ignored, branch-only).

Behaviour

Call	Result
InsertDefaults("t").ToSql()	INSERT INTO t DEFAULT VALUES
InsertDefaults("t").Suffix(\RETURNING "id"`)`	INSERT INTO t DEFAULT VALUES RETURNING "id"
chained .Suffix(...)	accumulates left-to-right
InsertDefaults("")	build-time error via Err()
InsertRecord(allDefault) (existing #50 path)	hints at SQL.InsertDefaults("t") instead of sq.Expr

Suffix takes literal SQL only. Placeholder-bearing suffixes (ON CONFLICT ... SET col = ?) fall back to sq.Expr at the call site — placeholder rebinding without sq.StatementBuilderType's PlaceholderFormat getter is non-trivial and defer-able until concrete demand surfaces.

Error from InsertDefaults("") is raw (no pgkit: prefix). Querier.wrapErr at querier.go:23,47,71 adds the prefix at use time — double-wrapping would surface pgkit: pgkit: ....

---

Test plan

• make db-reset test-all against PostgreSQL 18.3 — all 6 packages green.
• 6 unit tests: plain SQL, RETURNING, chained Suffix, EXCLUDED upsert, empty-table rejection, InsertRecord hint update.
• Integration TestInsertDefaultsRoundTrip: exec INSERT INTO default_only DEFAULT VALUES RETURNING id against the new default_only table (every column DB-defaulted, isolates the contract).
• go vet ./... clean.

Out of scope (tracked separately)

Codex's review surfaced two latent state-loss bugs in pgkit.InsertBuilder's embed-and-inherit pattern that pre-date this PR:

1. pgkit.InsertBuilder.Suffix drops err — inherited from sq.InsertBuilder, returns the squirrel type, loses the pgkit wrapper.
2. table.go:93 chain InsertRecord(r).Into(t).Suffix("...") loses pgkit state via .Into(...).

Both are symptoms of the same disease — embedding-and-inheriting chain methods that return the parent type. The fix is to wrap every chain method on pgkit's side. Out of scope here; will land as a follow-up issue titled "pgkit.InsertBuilder loses state through inherited squirrel methods."

[david-littlefarmer]

Code Review

One confirmed correctness bug, three low-severity design notes.

---

🔴 #1 — Unquoted table identifier (builder.go:111)

b.table is concatenated verbatim into SQL with no identifier quoting:

return "INSERT INTO " + b.table + " DEFAULT VALUES" + b.suffix, nil, nil

Every other builder in this repo delegates to squirrel's .Into() which handles quoting. This bypasses that entirely:

• InsertDefaults("user") → INSERT INTO user DEFAULT VALUES — user is a PG reserved word, syntax error at runtime
• InsertDefaults("MyTable") → silently targets mytable (Postgres lowercases unquoted identifiers)

The fix is straightforward — use pq.QuoteIdentifier(table) (or squirrel's quoting) at construction time.

---

🟡 #2 — Pointer receiver on InsertDefaults (builder.go:92)

InsertDefaults uses *StatementBuilder while InsertRecords, UpdateRecord, and UpdateRecordColumns all use value receivers. No mutation justifies the pointer receiver here — a value receiver would be consistent with the majority of the API and avoid a footgun for callers that hold a StatementBuilder by value.

(Note: InsertRecord also uses *StatementBuilder, so this isn't a new pattern — but widening it further without a reason is worth flagging.)

---

🟡 #3 — Exported zero value bypasses the empty-table guard (builder.go:101)

DefaultValuesBuilder is an exported value type. A caller that zero-initialises it directly (var b pgkit.DefaultValuesBuilder) gets err == nil and table == "". ToSql() then returns "INSERT INTO DEFAULT VALUES" — invalid SQL — with no error, so the failure only surfaces as a cryptic Postgres parse error at exec time rather than a build-time message.

---

⚪ #4 — Suffix("") injects a trailing space (builder.go:119)

Calling Suffix("") produces "INSERT INTO t DEFAULT VALUES " (trailing space). Postgres ignores it, but it breaks string-equality assertions in snapshot tests and query-log comparisons. Common pattern where this bites: building suffix conditionally — b.Suffix(returningClause) where returningClause is "" on the non-returning path.

---

Review generated with Claude Code

[klaidliadon]

Pushed 514707f addressing 3 of 4. Pushing back on #1.

#1 — Table identifier quoting: Pushing back. The premise that "every other builder delegates to squirrel's .Into() which handles quoting" is empirically not the case — grep for Quote across pgkit returns zero hits, and squirrel's .Into() just writes the table name verbatim into the SQL (verified: sq.Insert("items").ToSql() returns INSERT INTO items …, no quotes). InsertRecord(rec, "user") would break at runtime just as badly as InsertDefaults("user"). Adding quoting to only InsertDefaults makes the API asymmetric and worse to reason about (InsertRecord and InsertDefaults would treat the same string differently). The right fix is pgkit-wide identifier quoting in a separate PR — probably a major version bump, since some callers may be pre-quoting strings today to work around the current behavior. Happy to file an issue.

#2 — Pointer receiver: Accepted. InsertDefaults now uses a value receiver, matching UpdateRecord / UpdateRecordColumns / InsertRecords. InsertRecord kept on *StatementBuilder for now — widening the inconsistency isn't justified, narrowing it is its own scoped change.

#3 — Zero-value bypass: Accepted. DefaultValuesBuilder.ToSql now re-validates table == "" defensively, so a direct var b pgkit.DefaultValuesBuilder errors cleanly instead of emitting INSERT INTO DEFAULT VALUES at exec time. Test: TestInsertDefaults_ZeroValueErrors.

#4 — Suffix("") trailing space: Accepted. Empty suffix is now a no-op; b.Suffix("") returns the same builder unchanged, no trailing whitespace. Test: TestInsertDefaults_EmptySuffixIsNoop.