spanutil

Documentation

Overview

Package span contains utility functions to interact with the underlying Spanner storage. It does not attempt to encapsulate Spanner.

Index

• Variables
• func Compress(data []byte) []byte
• func Decompress(src, dest []byte) ([]byte, error)
• func FromSpanner(row *spanner.Row, ptrs ...any) error
• func GenerateStatement(tmpl *template.Template, input any) (spanner.Statement, error)
• func IncRowCount(ctx context.Context, count int, table Table, rowStatus RowStatus, realm string)
• func InsertMap(table string, in map[string]any) *spanner.Mutation
• func InsertOrUpdateMap(table string, in map[string]any) *spanner.Mutation
• func Query(ctx context.Context, st spanner.Statement, fn func(row *spanner.Row) error) error
• func QueryFirstRow(ctx context.Context, st spanner.Statement, ptrs ...any) error
• func ReadRow(ctx context.Context, table string, key spanner.Key, ptrMap map[string]any) error
• func SpannerDefaultsInterceptor(pri sppb.RequestOptions_Priority) grpc.UnaryServerInterceptor
• func ToSpanner(v any) any
• func ToSpannerMap(values map[string]any) map[string]any
• func ToSpannerSlice(values ...any) []any
• func UpdateMap(table string, in map[string]any) *spanner.Mutation
• type Buffer
  • func (b *Buffer) FromSpanner(row *spanner.Row, ptrs ...any) error
• type Compressed
  • func (c *Compressed) FromSpanner(b *Buffer) error
  • func (c *Compressed) SpannerPtr(b *Buffer) any
  • func (c Compressed) ToSpanner() any
• type Ptr
• type RowStatus
• type Table
• type Value

Variables

var ErrNoResults = iterator.Done

ErrNoResults is an error returned when a query unexpectedly has no results.

var RowCounter = metric.NewCounter(
	"resultdb/spanner/rows",
	"Number of Spanner row operations",
	nil,
	field.String("table"),
	field.String("status"),
	field.String("realm"),
)

RowCounter is a metric, tracking the number of row operations in Spanner tables.

Functions

func Compress

func Compress(data []byte) []byte

Compress compresses data using zstd.

func Decompress

func Decompress(src, dest []byte) ([]byte, error)

Decompress decompresses the src compressed with Compress to dest. dest is the buffer for decompressed content, it will be reset to 0 length before taking the content.

func FromSpanner

func FromSpanner(row *spanner.Row, ptrs ...any) error

FromSpanner is a shortcut for (&Buffer{}).FromSpanner. Appropriate when FromSpanner is called only once, whereas Buffer is reusable throughout function.

func GenerateStatement

func GenerateStatement(tmpl *template.Template, input any) (spanner.Statement, error)

GenerateStatement generates a spanner statement from a text template.

func IncRowCount

func IncRowCount(ctx context.Context, count int, table Table, rowStatus RowStatus, realm string)

IncRowCount increments the row counter.

func InsertMap

func InsertMap(table string, in map[string]any) *spanner.Mutation

InsertMap is a shortcut for spanner.InsertMap with ToSpannerMap applied to in.

func InsertOrUpdateMap

func InsertOrUpdateMap(table string, in map[string]any) *spanner.Mutation

InsertOrUpdateMap is a shortcut for spanner.InsertOrUpdateMap with ToSpannerMap applied to in.

func Query

func Query(ctx context.Context, st spanner.Statement, fn func(row *spanner.Row) error) error

Query executes a query. Ensures st.Params are Spanner-compatible by modifying st.Params in place.

func QueryFirstRow

func QueryFirstRow(ctx context.Context, st spanner.Statement, ptrs ...any) error

QueryFirstRow executes a query, reads the first row into ptrs and stops the iterator. Returns ErrNoResults if the query does not return at least one row.

func ReadRow

func ReadRow(ctx context.Context, table string, key spanner.Key, ptrMap map[string]any) error

ReadRow reads a single row from the database and reads its values. ptrMap must map from column names to pointers where the values will be written.

func SpannerDefaultsInterceptor

func SpannerDefaultsInterceptor(pri sppb.RequestOptions_Priority) grpc.UnaryServerInterceptor

SpannerDefaultsInterceptor returns a gRPC interceptor that adds default Spanner request options to the context.

The spanner request priority will be set according to pri (e.g. PRIORITY_MEDIUM or PRIORITY_HIGH). The request tag will be set the to RPC method name.

See also ModifyRequestOptions in luci/server/span.

func ToSpanner

func ToSpanner(v any) any

ToSpanner converts values from Go types to Spanner types. In addition to supported types in FromSpanner, also supports []any and map[string]any.

func ToSpannerMap

func ToSpannerMap(values map[string]any) map[string]any

ToSpannerMap converts a map of Go values to a map of Spanner values. See also ToSpanner.

func ToSpannerSlice

func ToSpannerSlice(values ...any) []any

ToSpannerSlice converts a slice of Go values to a slice of Spanner values. See also ToSpanner.

func UpdateMap

func UpdateMap(table string, in map[string]any) *spanner.Mutation

UpdateMap is a shortcut for spanner.UpdateMap with ToSpannerMap applied to in.

Types

type Buffer

type Buffer struct {
	NullString  spanner.NullString
	NullTime    spanner.NullTime
	Int64       int64
	StringSlice []string
	ByteSlice   []byte
	ByteSlice2  [][]byte
}

Buffer can convert a value from a Spanner type to a Go type. Supported types:

• Value and Ptr
• string
• timestamppb.Timestamp
• pb.BigQueryExport
• pb.ExonerationReason
• pb.InvocationState
• pb.TestStatus
• pb.Variant
• pb.StringPair
• proto.Message

TODO(nodir): move to buffer.go

func (*Buffer) FromSpanner

func (b *Buffer) FromSpanner(row *spanner.Row, ptrs ...any) error

FromSpanner reads values from row to ptrs, converting types from Spanner to Go along the way.

type Compressed

type Compressed []byte

Compressed instructs ToSpanner and FromSpanner functions to compress the content with https://godoc.org/github.com/klauspost/compress/zstd encoding.

func (*Compressed) FromSpanner

func (c *Compressed) FromSpanner(b *Buffer) error

FromSpanner implements Ptr.

func (*Compressed) SpannerPtr

func (c *Compressed) SpannerPtr(b *Buffer) any

SpannerPtr implements Ptr.

func (Compressed) ToSpanner

func (c Compressed) ToSpanner() any

ToSpanner implements Value.

type Ptr

type Ptr interface {
	// SpannerPtr returns to a pointer of a type supported by Spanner client.
	// SpannerPtr must use one of typed buffers in b.
	SpannerPtr(b *Buffer) any
	// FromSpanner replaces Ptr value with the value in the typed buffer returned
	// by SpannerPtr.
	FromSpanner(b *Buffer) error
}

Ptr can be used a destination of reading a Spanner cell. Typically if type *T implements Ptr, then T implements Value.

type RowStatus

type RowStatus string

RowStatus is a status of a row. Used in metrics.

const (
	Inserted RowStatus = "INSERTED"
	Deleted  RowStatus = "DELETED"
)

Values of RowStatus type.

type Table

type Table string

Table identifies a Spanner table. Used in metrics.

const (
	TestResults Table = "TestResults"
	Invocations Table = "Invocations"
	Artifacts   Table = "Artifacts"
)

Values of Table type.

type Value

type Value interface {
	// ToSpanner returns a value of a type supported by Spanner client.
	ToSpanner() any
}

Value can be converted to a Spanner value. Typically if type T implements Value, then *T implements Ptr.