Consolidate client-side tabular outputs behind a shared helper

[apstndb]

Category

Non-breaking refactor.

Background

PR #648 removes the old buffered formatter registry and keeps regular non-table query output streaming. Result.Rows remains widely used for small client-side or metadata-style tables such as system variables, params, proto/schema statements, query profile output, and EXPLAIN/DESCRIBE helpers.

These are generally small outputs, so this is not a memory-safety issue.

Problem

Ad hoc Result{Rows: ...} construction keeps printTableData as a broad compatibility adapter and makes it harder to reason about which paths are true query streaming paths versus small client-side tables.

Suggested PR scope

• Introduce or consolidate a helper for small client-side tabular outputs.
• Migrate a coherent set of statement handlers in one PR, for example system variables/params/proto listing, while keeping diff size reviewable.
• Preserve all existing display formats and result-line behavior.
• Do not force TABLE rendering or spanvalue writer ownership into this cleanup.
• Leave large query paths and partitioned query paths to separate issues.

Acceptance criteria

• The migrated client-side statements no longer hand-roll Result.Rows construction at each call site.
• Output snapshots/expectations remain unchanged.
• The helper makes it explicit that these are small, already-materialized client-side result tables.
• make check passes.

Related

• Stream non-table output by default #648

[apstndb]

Direction update: the consolidation point this issue asked for now exists — executeStructRows[T] (spanenc_bridge.go, #661), which also brings CSV/JSONL streaming and typed verbose headers for free. Introducing a second, weaker string-row helper would create a parallel abstraction that #660 immediately obsoletes. Suggest narrowing this issue to: migrate the fixed-shape toRow call sites to executeStructRows (that is #660's work list) and document the residual genuinely-dynamic cases (singular SHOW VARIABLE, params, pre-rendered DDL text) that stay on toRow/printTableData — or simply merging this into #660.

[apstndb]

Concrete design input from a full read-through of the output layer (2026-07; symbol references current as of main after #692).

Why this issue should land before #647

Client-side statements hand-build Result{Rows: ...} with pre-formatted []format.Cell, which erases the typed values that the spanvalue writer path needs. A shared helper for "small client-side result table" gives every virtual result set a single entry point; once that exists, migrating the buffered representation to raw values + metadata (#647) becomes mechanical instead of a per-statement hunt. spancodec already feeds client-side rows as real *spanner.Rows via executeStructRows / streamStructRows, so the helper can be typed from day one.

Target shape (shared sink interface)

The table rendering engine is already unified (TableStreamingFormatter serves both buffered and streaming table output). The remaining split is routing and ownership, so the consolidation target is one sink interface shaped like spanvalue's hooks:

• PrepareMetadata(md) / WriteRow(*spanner.Row) / Finish(result), implemented by
  1. spanvalue writers (all export formats),
  2. a table/vertical renderer sink that owns preview buffering, width calculation, and Cell styling internally (Cell becomes a private detail of the renderer),
  3. a Result-materializing sink for THEN RETURN and client-side fallbacks.

Every producer (query, partitioned fan-in, virtual result sets, DUMP) then drives one sink type, and the sink plus screen width are resolved once per statement and passed down explicitly. That last point also fixes real divergence bugs found in the read-through: MCP mode currently captures output via a per-call writer while streaming formats write to the global StreamManager (= the MCP stdio transport), and AutoWrap/FixedWidth width logic is computed differently on the buffered and streaming paths.

Side benefit

New "foreign result" sources fit the same helper: for example a BIGQUERY client-side statement (#689) can produce typed virtual rows instead of stringified cells, keeping JSONL/CSV/SQL export type-faithful for free.

Suggested sequencing: #652 (this helper) -> #647 (single emitter per export format) -> #653 falls out (streaming becomes a routing-table concern), with #644 decided before the TAB emitter is touched.

[apstndb]

Re-scoping after the Result-type decomposition (#738, PRs #741/#744/#746/#749/#751).

The payload split this issue implicitly asked for now exists: buffered client-side result sets are typed (Result.Typed = *sppb.ResultSetMetadata + []*spanner.Row), and executeStructRows (spancodec_bridge.go) is the shared helper that routes struct-shaped rows through the same spanvalue emitters as server query results (streaming) or a typed buffered Result (fallback). SHOW VARIABLES, SHOW PARAMS, SHOW DATABASES, HELP, and SHOW LOCAL/REMOTE PROTO already go through it and are export-faithful.

Remaining scope for this issue: opportunistically migrate the remaining hand-rolled Rows: tables to executeStructRows where the row shape is genuinely data-like (a fixed set of named columns that map cleanly to a struct). Concretely, tables where CSV/JSONL/SQL export of the underlying values is meaningful.

Explicitly out of scope (do not chase): the ~53 presentation tables that are layouts rather than data -- EXPLAIN plan trees (with alignment), SHOW OPERATION, batch DML summaries, formatUpdateDatabaseDdlRows, and the schema/query-profile/llm renderers. These stay as kind (a) display-text Rows and render through the display-text replay (writeDisplayRows), where "CSV of display text" is the honest semantics; forcing them into structs adds code for zero fidelity gain (per #738 section 4, "Do not migrate").