writer: consider explicit SQL INSERT table placeholders for generic exports #146

Summary

Consider explicit placeholder support for SQL INSERT exports when a generic CLI cannot know the target table name.

For example, a generic query CLI may allow:

SELECT col1, col2 FROM SomeView

or joins/subqueries where there is no single source table that can safely become the INSERT target. Users may still want a SQL INSERT-shaped export and fill in the target table later.

Motivation

Downstream feedback proposed accepting an empty table name and falling back to a default such as DUMMY_TABLE, or allowing a deferred/overridable table name. A silent default is risky because SQL INSERT output has a required target identifier. However, an explicit placeholder could be useful and safer than pretending the table is known.

Possible API directions:

• A dedicated constructor/option for an intentionally unresolved placeholder, e.g. WithSQLTablePlaceholder("TABLE_NAME").
• A table-name wrapper type that distinguishes identifiers from raw placeholders.
• Documentation-only guidance that applications should post-process SQL fragments or use their own writer when they need unresolved table names.

Design constraints

• Preserve dialect-aware identifier quoting for real table names.
• Do not treat arbitrary text/template output as a quoted identifier without a clear escaping rule.
• Avoid implicit defaults like DUMMY_TABLE; placeholders should be visibly intentional in output.
• Keep SQLInsertWriter's fixed-table model unless there is a strong reason to support per-row/per-batch table changes.

Open questions

• Should a placeholder be raw SQL text, or should it be delimited so it cannot be confused with an identifier?
• Is text/template actually needed, or is a single placeholder token enough?
• Should this live in SQLInsertWriter, or in future INSERT fragment helpers for custom batching/export layers?

Related

• Empty table validation should be tracked separately: accidental empty string and intentional placeholder are different cases.
• writer: INSERT fragment helpers for custom batching layers #79 tracks INSERT fragment helpers for custom batching layers.