README
¶
gospanner
Optional nested Go module — reference integration for
go-sql-spanner + core
dbsqlrows.
import "github.com/apstndb/spanvalue/dbsqlrows/gospanner"
The root github.com/apstndb/spanvalue module still has no
go-sql-spanner dependency.
Why this module exists
| Audience | Use |
|---|---|
| One-shot CLIs / scripts | QueryExport → csv/jsonl without boilerplate |
| New adopters | DefaultExecOptions documents proto decode + metadata pseudo-row |
| Interactive shells (e.g. spannersh) | Do not use — app-owned ExecOptions + core dbsqlrows primitives |
spannersh validated that metadata-first REPLs need QueryMode, multi-statement batches,
and stats-after-render; those stay in the application with Option A (core cookbook).
gospanner is intentionally narrow — not a gap when shells skip it.
Module
go get github.com/apstndb/spanvalue/dbsqlrows/gospanner@v0.6.0
Local development in this repository uses replace github.com/apstndb/spanvalue => ../.. in go.mod. That directive is dev-only (ignored by downstream go get); consumers need a published github.com/apstndb/spanvalue v0.6.0 or newer—the first release that includes dbsqlrows.
This nested module targets Go 1.25 (required by go-sql-spanner v1.25.1). The root spanvalue module requires Go 1.25+ per README.md and go.mod.
API
| Function | Role |
|---|---|
DefaultExecOptions |
Proto decode + metadata pseudo-row; stats left for caller |
QueryExport |
QueryContext + dbsqlrows.WriteRows. Prepends ExecOptions as the first query argument |
QueryExportWithOptions |
Same with explicit ExecOptions |
Example
import (
"context"
"database/sql"
"os"
"github.com/apstndb/spanvalue/dbsqlrows"
"github.com/apstndb/spanvalue/dbsqlrows/gospanner"
"github.com/apstndb/spanvalue/writer"
)
w, err := writer.NewCSVWriter(os.Stdout, writer.WithHeader(true))
if err != nil {
return err
}
result, err := gospanner.QueryExport(
ctx, db, "SELECT id, name FROM Users", nil, w, dbsqlrows.SQLRowsConfig{},
)
if err != nil {
return err
}
_ = result.Metadata
For metadata-first, table, EXPLAIN, or multi-statement flows, use
dbsqlrows directly
and configure ExecOptions in app code (see package documentation). Typical REPL
pattern: driver ReturnResultSetStats: true, export ReadResultSetStats: false,
read stats pseudo-row after render.
Development
cd dbsqlrows/gospanner && go test ./...
Root make check does not run this nested module. CI runs go test ./... here
with Go 1.25 (see .github/workflows/go.yml).
Related
Documentation
¶
Overview ¶
Package gospanner wires github.com/googleapis/go-sql-spanner query execution to github.com/apstndb/spanvalue/dbsqlrows export helpers.
Import this nested module only when the application already depends on go-sql-spanner and wants a one-shot QueryContext + dbsqlrows.WriteRows helper. The root github.com/apstndb/spanvalue module does not require go-sql-spanner.
When to use gospanner ¶
- Small tools or scripts: single SELECT → CSV/JSONL via QueryExport.
- Reference integration: shows recommended ExecOptions for proto-decoded GCV export with a metadata pseudo-row (DefaultExecOptions).
When to use core dbsqlrows instead ¶
- Metadata-first or multi-statement batches (dbsqlrows.ReadMetadataAndAdvanceToData).
- Table or custom sinks (dbsqlrows.RunRowsAtData + dbsqlrows.SQLRowsHooks).
- Per-query driver options (QueryMode PLAN/PROFILE, DirectExecuteQuery).
- Stats read after render with driver ReturnResultSetStats true and export ReadResultSetStats false (REPL pattern; see dbsqlrows package documentation).
DefaultExecOptions sets ReturnResultSetStats false — appropriate for simple export CLIs, not for shells that render first then show execution summaries.
See README.md in this directory.
Index ¶
- Variables
- func DefaultExecOptions() spannerdriver.ExecOptions
- func QueryExport(ctx context.Context, db *sql.DB, query string, args []any, ...) (*dbsqlrows.SQLRowsResult, error)
- func QueryExportWithOptions(ctx context.Context, db *sql.DB, query string, args []any, ...) (*dbsqlrows.SQLRowsResult, error)
Constants ¶
This section is empty.
Variables ¶
var ErrNilDB = errors.New("nil *sql.DB")
ErrNilDB reports that QueryExport or QueryExportWithOptions was called with a nil *sql.DB.
Functions ¶
func DefaultExecOptions ¶
func DefaultExecOptions() spannerdriver.ExecOptions
DefaultExecOptions returns the recommended go-sql-spanner configuration for proto-decoded GCV export with a leading metadata pseudo result set (spannerdriver.ExecOptions.ReturnResultSetMetadata). ReturnResultSetStats is false so callers can read stats after export (for example spannersh execution summaries) or set dbsqlrows.SQLRowsConfig.ReadResultSetStats.
func QueryExport ¶
func QueryExport( ctx context.Context, db *sql.DB, query string, args []any, w dbsqlrows.GCVStreamWriter, cfg dbsqlrows.SQLRowsConfig, ) (*dbsqlrows.SQLRowsResult, error)
QueryExport runs db.QueryContext with DefaultExecOptions and exports the result via dbsqlrows.WriteRows. It closes rows before returning.
The driver spannerdriver.ExecOptions value is prepended as the first query argument, before args. That is the go-sql-spanner convention; an argument-count error often means that leading value was forgotten or duplicated.
func QueryExportWithOptions ¶
func QueryExportWithOptions( ctx context.Context, db *sql.DB, query string, args []any, w dbsqlrows.GCVStreamWriter, cfg dbsqlrows.SQLRowsConfig, opts spannerdriver.ExecOptions, ) (*dbsqlrows.SQLRowsResult, error)
QueryExportWithOptions is QueryExport with explicit driver spannerdriver.ExecOptions.
Types ¶
This section is empty.
Source Files