WIP: SQL INSERT table placeholders (#146)

[apstndb]

Summary

Draft scaffold for #146 — not merge-ready.

• Adds WithSQLTablePlaceholder(token) on SQLInsertWriter.
• Placeholder tokens are emitted verbatim (no dialect identifier quoting); column names remain dialect-quoted.
• Allows NewSQLInsertWriter(out, "") when a placeholder is configured.
• ErrEmptyTablePlaceholder rejects empty placeholder tokens at construction.

Passing scaffold tests

• TABLE_NAME placeholder with GoogleSQL column quoting
• /* unresolved table */ placeholder with PostgreSQL "id" column quoting

Skipped golden sketches

• Batched INSERT with placeholder
• Empty table without placeholder (documents expected interaction with writer: reject empty SQLInsertWriter table name at construction #147)

Dependency on #147

#147 proposes rejecting NewSQLInsertWriter(out, "") at construction when no placeholder is set. This scaffold intentionally allows empty table only when WithSQLTablePlaceholder is present — the two issues must land together with clear error semantics:

Case	Expected behavior (TBD)
table="", no placeholder	ErrEmptyTableName at construction (#147)
table="", with placeholder	OK
table="users", with placeholder	Undecided — skipped test

Open design questions

• Delimiter conventions for placeholder tokens (raw SQL vs bracketed sentinel)?
• text/template support vs single fixed token?
• Should placeholders live on SQLInsertWriter or on INSERT fragment helpers (writer: INSERT fragment helpers for custom batching layers #79)?

Test plan

• make check passes
• Resolve writer: reject empty SQLInsertWriter table name at construction #147 interaction before stabilization
• Golden tests for batched placeholder output

Closes #146 when complete — this PR is design review only.

Made with Cursor

[gemini-code-assist]

Code Review

This pull request introduces support for SQL table placeholders in SQLInsertWriter via the new WithSQLTablePlaceholder option, allowing verbatim INSERT INTO target tokens when the real table name is unknown at export time. It also includes corresponding unit tests and error handling for empty placeholders. A review comment suggests updating the TableName() method to return the configured placeholder when set, ensuring consistency with its documented contract.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

When tablePlaceholder is configured, the actual table name used in the generated INSERT statements will be the placeholder, not table. However, TableName() currently still returns w.table (which may be empty). To ensure consistency with its documented contract ('TableName returns the qualified table name used in INSERT statements'), TableName() should be updated to return w.tablePlaceholder if it is set.