or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/cloud.google.com/go/spanner@v1.87.0
tile.json

tessl/golang-cloud-google-com--go--spanner

tessl install tessl/golang-cloud-google-com--go--spanner@1.87.2

Official Google Cloud Spanner client library for Go providing comprehensive database operations, transactions, and admin functionality

index.mddocs/

Cloud Spanner Go Client

Official Google Cloud Spanner client library for Go. Provides comprehensive functionality for reading and writing data to Cloud Spanner databases with support for transactions, queries, mutations, DML statements, session pool management, and database administration.

Package Information

Import Path: cloud.google.com/go/spanner Version: 1.87.0 License: Apache-2.0

Installation

go get cloud.google.com/go/spanner

Core Imports

import (
    "context"
    "cloud.google.com/go/spanner"
    "google.golang.org/api/option"
)

For admin operations:

import (
    database "cloud.google.com/go/spanner/admin/database/apiv1"
    instance "cloud.google.com/go/spanner/admin/instance/apiv1"
)

Quick Start

Creating a Client

ctx := context.Background()
client, err := spanner.NewClient(ctx, "projects/P/instances/I/databases/D")
if err != nil {
    // Handle error
}
defer client.Close()

Simple Write and Read

// Write a row
_, err := client.Apply(ctx, []*spanner.Mutation{
    spanner.Insert("Users",
        []string{"name", "email"},
        []interface{}{"alice", "a@example.com"}),
})
if err != nil {
    // Handle error
}

// Read a row
row, err := client.Single().ReadRow(ctx, "Users",
    spanner.Key{"alice"}, []string{"email"})
if err != nil {
    // Handle error
}

Key Capabilities

Client Management

Create and configure Spanner clients with customizable session pools, connection settings, and retry policies.

Key APIs:

func NewClient(ctx context.Context, database string, opts ...option.ClientOption) (*Client, error)
func NewClientWithConfig(ctx context.Context, database string, config ClientConfig, opts ...option.ClientOption) (*Client, error)

ClientConfig Structure:

type ClientConfig struct {
    SessionPoolConfig SessionPoolConfig
    SessionLabels     map[string]string
    QueryOptions      QueryOptions
    ReadOptions       ReadOptions
    ApplyOptions      []ApplyOption
    TransactionOptions TransactionOptions
    BatchWriteOptions BatchWriteOptions
    CallOptions       *vkit.CallOptions
    UserAgent         string
    DatabaseRole      string
    DisableRouteToLeader bool
    Logger            *log.Logger
    Compression       string
    BatchTimeout      time.Duration
    DirectedReadOptions *sppb.DirectedReadOptions
    OpenTelemetryMeterProvider metric.MeterProvider
    EnableEndToEndTracing bool
    DisableNativeMetrics bool
}

SessionPoolConfig Structure:

type SessionPoolConfig struct {
    MaxOpened         uint64
    MinOpened         uint64
    MaxIdle           uint64
    MaxBurst          uint64
    WriteSessions     float64
    HealthCheckWorkers int
    HealthCheckInterval time.Duration
    MultiplexSessionCheckInterval time.Duration
    TrackSessionHandles bool
    InactiveTransactionRemovalOptions InactiveTransactionRemovalOptions
}

See Client Management for complete details.

Read Operations

Perform single reads, batch reads, and SQL queries with various timestamp bounds and read options.

Key APIs:

// Single read optimized for one-shot operations
func (c *Client) Single() *ReadOnlyTransaction

// Read a single row
func (t *ReadOnlyTransaction) ReadRow(ctx context.Context, table string, key Key, columns []string) (*Row, error)

// Read multiple rows
func (t *ReadOnlyTransaction) Read(ctx context.Context, table string, keys KeySet, columns []string) *RowIterator

// Execute SQL query
func (t *ReadOnlyTransaction) Query(ctx context.Context, statement Statement) *RowIterator

Statement Structure:

type Statement struct {
    SQL    string
    Params map[string]interface{}
}

func NewStatement(sql string) Statement

RowIterator Methods:

func (r *RowIterator) Next() (*Row, error)
func (r *RowIterator) Do(f func(r *Row) error) error
func (r *RowIterator) Stop()

See Read Operations for complete details including timestamp bounds, read options, and index usage.

Write Operations

Apply mutations to insert, update, or delete rows with support for various input formats (columns/values, maps, structs).

Key APIs:

// Apply mutations atomically
func (c *Client) Apply(ctx context.Context, ms []*Mutation, opts ...ApplyOption) (commitTimestamp time.Time, err error)

// Create mutations from columns and values
func Insert(table string, cols []string, vals []interface{}) *Mutation
func Update(table string, cols []string, vals []interface{}) *Mutation
func InsertOrUpdate(table string, cols []string, vals []interface{}) *Mutation
func Replace(table string, cols []string, vals []interface{}) *Mutation
func Delete(table string, ks KeySet) *Mutation

// Create mutations from maps
func InsertMap(table string, in map[string]interface{}) *Mutation
func UpdateMap(table string, in map[string]interface{}) *Mutation
func InsertOrUpdateMap(table string, in map[string]interface{}) *Mutation
func ReplaceMap(table string, in map[string]interface{}) *Mutation

// Create mutations from structs
func InsertStruct(table string, in interface{}) (*Mutation, error)
func UpdateStruct(table string, in interface{}) (*Mutation, error)
func InsertOrUpdateStruct(table string, in interface{}) (*Mutation, error)
func ReplaceStruct(table string, in interface{}) (*Mutation, error)

Apply Options:

type ApplyOption func(*applyOption)

func ApplyAtLeastOnce() ApplyOption
func ApplyCommitOptions(co CommitOptions) ApplyOption
func Priority(priority sppb.RequestOptions_Priority) ApplyOption
func TransactionTag(tag string) ApplyOption
func ExcludeTxnFromChangeStreams() ApplyOption

See Write Operations for complete details including batch writes and mutation groups.

Transactions

Execute read-only, read-write, and batch transactions with automatic retry handling and strong consistency guarantees.

Key APIs:

// Read-only transaction for multiple reads
func (c *Client) ReadOnlyTransaction() *ReadOnlyTransaction

// Read-write transaction with automatic retry
func (c *Client) ReadWriteTransaction(ctx context.Context, f func(context.Context, *ReadWriteTransaction) error) (commitTimestamp time.Time, err error)

// Batch read-only transaction for partitioned operations
func (c *Client) BatchReadOnlyTransaction(ctx context.Context, tb TimestampBound) (*BatchReadOnlyTransaction, error)

// Statement-based read-write transaction
func NewReadWriteStmtBasedTransaction(ctx context.Context, c *Client) (*ReadWriteStmtBasedTransaction, error)

ReadWriteTransaction Methods:

func (t *ReadWriteTransaction) BufferWrite(ms []*Mutation) error
func (t *ReadWriteTransaction) Update(ctx context.Context, stmt Statement) (rowCount int64, err error)
func (t *ReadWriteTransaction) BatchUpdate(ctx context.Context, stmts []Statement) ([]int64, error)

See Transactions for complete details including timestamp bounds, partition operations, and transaction options.

DML Operations

Execute Data Manipulation Language (DML) statements including INSERT, UPDATE, DELETE, and partitioned DML for large-scale operations.

Key APIs:

// Execute DML in a read-write transaction
func (t *ReadWriteTransaction) Update(ctx context.Context, stmt Statement) (rowCount int64, err error)

// Batch DML statements
func (t *ReadWriteTransaction) BatchUpdate(ctx context.Context, stmts []Statement) ([]int64, error)

// Partitioned DML for large-scale updates
func (c *Client) PartitionedUpdate(ctx context.Context, statement Statement) (count int64, err error)

See DML Operations for complete details including query options and execution modes.

Type System

Handle Spanner data types including NullXXX types for nullable columns, custom encoders/decoders, and row decoding.

Key Types:

// Nullable types
type NullString struct {
    StringVal string
    Valid     bool
}

type NullInt64 struct {
    Int64 int64
    Valid bool
}

type NullFloat64 struct {
    Float64 float64
    Valid   bool
}

type NullBool struct {
    Bool  bool
    Valid bool
}

type NullTime struct {
    Time  time.Time
    Valid bool
}

type NullDate struct {
    Date  civil.Date
    Valid bool
}

type NullNumeric struct {
    Numeric big.Rat
    Valid   bool
}

type NullJSON struct {
    Value interface{}
    Valid bool
}

Row Decoding:

type Row struct { /* unexported fields */ }

func (r *Row) Column(i int, ptr interface{}) error
func (r *Row) ColumnByName(name string, ptr interface{}) error
func (r *Row) Columns(ptrs ...interface{}) error
func (r *Row) ToStruct(p interface{}) error
func (r *Row) Size() int
func (r *Row) ColumnNames() []string

Custom Encoding/Decoding:

type Encoder interface {
    EncodeSpanner() (interface{}, error)
}

type Decoder interface {
    DecodeSpanner(input interface{}) error
}

See Type System for complete type mappings, encoding rules, and conversion examples.

Keys and KeySets

Work with primary keys, secondary index keys, key ranges, and key sets for read and delete operations.

Key Types:

type Key []interface{}

type KeyRange struct {
    Start, End Key
    Kind       KeyRangeKind
}

type KeyRangeKind int
// Constants: ClosedOpen, ClosedClosed, OpenClosed, OpenOpen

type KeySet interface {
    // unexported methods
}

func AllKeys() KeySet
func KeySets(keySets ...KeySet) KeySet
func KeySetFromKeys(keys ...Key) KeySet

Key Methods:

func (k Key) AsPrefix() KeyRange

See Keys and KeySets for detailed usage patterns and examples.

Database Administration

Create, manage, and administer Spanner databases including DDL operations, backups, and database configurations.

Key APIs:

import database "cloud.google.com/go/spanner/admin/database/apiv1"

func NewDatabaseAdminClient(ctx context.Context, opts ...option.ClientOption) (*DatabaseAdminClient, error)

// Database operations
func (c *DatabaseAdminClient) CreateDatabase(ctx context.Context, req *databasepb.CreateDatabaseRequest, opts ...gax.CallOption) (*CreateDatabaseOperation, error)
func (c *DatabaseAdminClient) UpdateDatabaseDdl(ctx context.Context, req *databasepb.UpdateDatabaseDdlRequest, opts ...gax.CallOption) (*UpdateDatabaseDdlOperation, error)
func (c *DatabaseAdminClient) DropDatabase(ctx context.Context, req *databasepb.DropDatabaseRequest, opts ...gax.CallOption) error

See Database Administration for complete details on database lifecycle, DDL updates, backups, and restore operations.

Instance Administration

Create, manage, and configure Spanner instances including instance configurations, node counts, and processing units.

Key APIs:

import instance "cloud.google.com/go/spanner/admin/instance/apiv1"

func NewInstanceAdminClient(ctx context.Context, opts ...option.ClientOption) (*InstanceAdminClient, error)

// Instance operations
func (c *InstanceAdminClient) CreateInstance(ctx context.Context, req *instancepb.CreateInstanceRequest, opts ...gax.CallOption) (*CreateInstanceOperation, error)
func (c *InstanceAdminClient) UpdateInstance(ctx context.Context, req *instancepb.UpdateInstanceRequest, opts ...gax.CallOption) (*UpdateInstanceOperation, error)
func (c *InstanceAdminClient) DeleteInstance(ctx context.Context, req *instancepb.DeleteInstanceRequest, opts ...gax.CallOption) error

See Instance Administration for complete details on instance management and configurations.

Testing Support

Use in-memory Spanner server for testing and SQL parser for query analysis.

spannertest Package:

import "cloud.google.com/go/spanner/spannertest"

func NewServer() (*Server, error)
func (s *Server) Addr() string

spansql Package:

import "cloud.google.com/go/spanner/spansql"

func ParseDDL(filename, s string) (*DDL, error)
func ParseDDLStmt(s string) (DDLStmt, error)
func ParseQuery(s string) (Query, error)
func ParseDMLStmt(s string) (DMLStmt, error)

See Testing Support for in-memory server setup and SQL parsing details.

Low-Level gRPC Access

Direct access to low-level Spanner gRPC APIs for advanced use cases.

Key APIs:

import spannerapi "cloud.google.com/go/spanner/apiv1"

func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error)

See Low-Level gRPC Access for direct gRPC API usage.

Protobuf Types

Protobuf definitions for Spanner APIs including request/response types and metadata structures.

Key packages:

  • cloud.google.com/go/spanner/apiv1/spannerpb - Core Spanner API types
  • cloud.google.com/go/spanner/admin/database/apiv1/databasepb - Database admin types
  • cloud.google.com/go/spanner/admin/instance/apiv1/instancepb - Instance admin types

See Protobuf Types for complete protobuf type definitions.

Environment Configuration

Emulator Support

To use the Spanner emulator:

import "os"

err := os.Setenv("SPANNER_EMULATOR_HOST", "localhost:9010")
if err != nil {
    // Handle error
}

// Client automatically connects to emulator
client, err := spanner.NewClient(ctx, "projects/P/instances/I/databases/D")

Authentication Scopes

const (
    // Scope for Cloud Spanner Data API
    Scope = "https://www.googleapis.com/auth/spanner.data"

    // AdminScope for Cloud Spanner Admin APIs
    AdminScope = "https://www.googleapis.com/auth/spanner.admin"
)

Observability

OpenTelemetry Metrics

func EnableOpenTelemetryMetrics()
func IsOpenTelemetryMetricsEnabled() bool

const OtInstrumentationScope = "cloud.google.com/go"

OpenCensus Views (Deprecated)

The package includes deprecated OpenCensus metrics. Use OpenTelemetry for new applications:

func EnableStatViews() error  // Deprecated
func EnableGfeLatencyView() error  // Deprecated

Error Handling

Error Functions:

func ErrCode(err error) codes.Code
func ErrDesc(err error) string
func ToSpannerError(err error) error
func ExtractRetryDelay(err error) (time.Duration, bool)

Error Type:

type Error struct {
    Code      codes.Code  // Deprecated: use ErrCode(err)
    Desc      string
    RequestID string
}

func (e *Error) Error() string
func (e *Error) GRPCStatus() *status.Status
func (e *Error) Unwrap() error

Common Error Handling:

import (
    "google.golang.org/grpc/codes"
    "cloud.google.com/go/spanner"
)

if err != nil {
    if spanner.ErrCode(err) == codes.NotFound {
        // Handle row not found
    }
    // Handle other errors
}

Constants and Variables

Numeric Type Constants:

const (
    NumericPrecisionDigits = 38  // Maximum digits in NUMERIC
    NumericScaleDigits     = 9   // Maximum digits after decimal
)

Special Values:

var CommitTimestamp = commitTimestamp  // Placeholder for commit timestamp

var ErrRowNotFound = errors.New("row not found")

Default Configurations:

var DefaultRetryBackoff = gax.Backoff{
    Initial:    20 * time.Millisecond,
    Max:        32 * time.Second,
    Multiplier: 1.3,
}

var DefaultSessionPoolConfig = SessionPoolConfig{
    MinOpened:           100,
    MaxOpened:           numChannels * 100,
    MaxBurst:            10,
    WriteSessions:       0.2,
    HealthCheckWorkers:  10,
    HealthCheckInterval: 50 * time.Minute,
}

Best Practices

  1. Always close clients: Use defer client.Close() to release sessions
  2. Use read-only transactions: For multiple consistent reads
  3. Prefer ReadWriteTransaction: Over manual transaction management
  4. Handle aborts: Use automatic retry with ReadWriteTransaction
  5. Set appropriate session pool sizes: Based on workload
  6. Use timestamp bounds: For stale reads when appropriate
  7. Monitor session pool: Enable metrics for production systems
  8. Use batching: Group mutations for better performance
  9. Set request tags: For debugging and tracing
  10. Enable OpenTelemetry: For production observability

Related Documentation

  • Official Cloud Spanner Documentation
  • Go Client API Reference
  • Best Practices Guide