span

Documentation

Overview

Package span implements a server module for communicating with Cloud Spanner.

Index

• Variables
• func Apply(ctx context.Context, ms []*spanner.Mutation, opts ...spanner.ApplyOption) (commitTimestamp time.Time, err error)
• func BufferWrite(ctx context.Context, ms ...*spanner.Mutation)
• func Defer(ctx context.Context, cb func(context.Context))
• func MustRO(ctx context.Context) *spanner.ReadOnlyTransaction
• func MustRW(ctx context.Context) *spanner.ReadWriteTransaction
• func NewModule(opts *ModuleOptions) module.Module
• func NewModuleFromFlags() module.Module
• func Query(ctx context.Context, statement spanner.Statement) *spanner.RowIterator
• func RO(ctx context.Context) *spanner.ReadOnlyTransaction
• func RW(ctx context.Context) *spanner.ReadWriteTransaction
• func Read(ctx context.Context, table string, keys spanner.KeySet, columns []string) *spanner.RowIterator
• func ReadOnlyTransaction(ctx context.Context) (context.Context, context.CancelFunc)
• func ReadRow(ctx context.Context, table string, key spanner.Key, columns []string) (*spanner.Row, error)
• func ReadWithOptions(ctx context.Context, table string, keys spanner.KeySet, columns []string, ...) *spanner.RowIterator
• func ReadWriteTransaction(ctx context.Context, f func(ctx context.Context) error) (commitTimestamp time.Time, err error)
• func Single(ctx context.Context) context.Context
• func Update(ctx context.Context, stmt spanner.Statement) (rowCount int64, err error)
• func UpdateWithOptions(ctx context.Context, stmt spanner.Statement, opts spanner.QueryOptions) (rowCount int64, err error)
• func UseClient(ctx context.Context, client *spanner.Client) context.Context
• func WithoutTxn(ctx context.Context) context.Context
• type ModuleOptions
  • func (o *ModuleOptions) Register(f *flag.FlagSet)
• type Transaction
  • func MustTxn(ctx context.Context) Transaction
  • func Txn(ctx context.Context) Transaction

Variables

var ModuleName = module.RegisterName("go.chromium.org/luci/server/span")

ModuleName can be used to refer to this module when declaring dependencies.

Functions

func Apply

func Apply(ctx context.Context, ms []*spanner.Mutation, opts ...spanner.ApplyOption) (commitTimestamp time.Time, err error)

Apply applies a list of mutations atomically to the database.

Panics if called from inside a read-write transaction. Use BufferWrite to apply mutations there.

func BufferWrite

func BufferWrite(ctx context.Context, ms ...*spanner.Mutation)

BufferWrite adds a list of mutations to the set of updates that will be applied when the transaction is committed.

It does not actually apply the write until the transaction is committed, so the operation does not block. The effects of the write won't be visible to any reads (including reads done in the same transaction) until the transaction commits.

It is a wrapper over MustRW(ctx).BufferWrite(...). Panics if the context is not read-write transactional.

func Defer

func Defer(ctx context.Context, cb func(context.Context))

Defer schedules `cb` for execution when the current read-write transaction successfully lands.

Intended for a best-effort non-transactional follow up to a successful transaction. Note that in presence of failures there's no guarantee the callback will be called. For example, the callback won't ever be called if the process crashes right after landing the transaction. Or if the transaction really landed, but ReadWriteTransaction finished with "deadline exceeded" (or some similar) error.

Callbacks are executed sequentially in the reverse order they were deferred. They receive the non-transactional version of the context initially passed to ReadWriteTransaction.

Panics if the given context is not transactional.

func MustRO

func MustRO(ctx context.Context) *spanner.ReadOnlyTransaction

MustRO is like RO except it panics if `ctx` is not read-only transactional.

func MustRW

func MustRW(ctx context.Context) *spanner.ReadWriteTransaction

MustRW is like RW except it panics if `ctx` is not read-write transactional.

func NewModule

func NewModule(opts *ModuleOptions) module.Module

NewModule returns a server module that sets up a Spanner client connected to some single Cloud Spanner database.

Client's functionality is exposed via Single(ctx), ReadOnlyTransaction(ctx), ReadWriteTransaction(ctx), etc.

The underlying *spanner.Client is intentionally not exposed to make sure all callers use the functions mentioned above since they generally add additional functionality on top of the raw Spanner client that other LUCI packages assume to be present. Using the Spanner client directly may violate such assumptions leading to undefined behavior when multiple packages are used together.

func NewModuleFromFlags

func NewModuleFromFlags() module.Module

NewModuleFromFlags is a variant of NewModule that initializes options through command line flags.

Calling this function registers flags in flag.CommandLine. They are usually parsed in server.Main(...).

func Query

func Query(ctx context.Context, statement spanner.Statement) *spanner.RowIterator

Query reads multiple rows returned by SQL statement.

It is a shortcut for MustTxn(ctx).Query(ctx, ...). Panics if the context is not transactional.

func RO

func RO(ctx context.Context) *spanner.ReadOnlyTransaction

RO returns the current read-only transaction in the context or nil if it's not a read-only transactional context.

func RW

func RW(ctx context.Context) *spanner.ReadWriteTransaction

RW returns the current read-write transaction in the context or nil if it's not a read-write transactional context.

func Read

func Read(ctx context.Context, table string, keys spanner.KeySet, columns []string) *spanner.RowIterator

Read reads multiple rows from the database.

It is a shortcut for MustTxn(ctx).Read(ctx, ...). Panics if the context is not transactional.

func ReadOnlyTransaction

func ReadOnlyTransaction(ctx context.Context) (context.Context, context.CancelFunc)

ReadOnlyTransaction returns a derived context with a read-only transaction.

It can be used for multiple reads from the database. To avoid leaking resources on the server this context *must* be canceled as soon as all reads are done.

The transaction object can be obtained through RO(ctx) or Txn(ctx). It is also transparently used by ReadRow, Read, Query, etc. wrappers.

Panics if `ctx` already holds a transaction (either read-write or read-only).

func ReadRow

func ReadRow(ctx context.Context, table string, key spanner.Key, columns []string) (*spanner.Row, error)

ReadRow reads a single row from the database.

It is a shortcut for MustTxn(ctx).ReadRow(ctx, ...). Panics if the context is not transactional.

func ReadWithOptions

func ReadWithOptions(ctx context.Context, table string, keys spanner.KeySet, columns []string, opts *spanner.ReadOptions) *spanner.RowIterator

ReadWithOptions reads multiple rows from the database, and allows customizing options.

It is a shortcut for MustTxn(ctx).ReadWithOptions(ctx, ...). Panics if the context is not transactional.

func ReadWriteTransaction

func ReadWriteTransaction(ctx context.Context, f func(ctx context.Context) error) (commitTimestamp time.Time, err error)

ReadWriteTransaction executes a read-write transaction, with retries as necessary.

The callback may be called multiple times if Spanner client decides to retry the transaction. In particular this happens if the callback returns (perhaps wrapped) ABORTED error. This error is returned by Spanner client methods if they encounter a stale transaction.

See https://godoc.org/cloud.google.com/go/spanner#ReadWriteTransaction for more details.

The callback can access the transaction object via RW(ctx) or Txn(ctx). It is also transparently used by ReadRow, Read, Query, BufferWrite, etc. wrappers.

Panics if `ctx` already holds a read-write transaction. Starting a read-write transaction from a read-only transaction is OK though, but beware that they are completely separate unrelated transactions.

func Single

func Single(ctx context.Context) context.Context

Single returns a derived context with a single-use read-only transaction.

It provides a read-only snapshot transaction optimized for the case where only a single read or query is needed. This is more efficient than using ReadOnlyTransaction() for a single read or query.

The transaction object can be obtained through RO(ctx) or Txn(ctx). It is also transparently used by ReadRow, Read, Query, etc. wrappers.

Panics if `ctx` already holds a transaction (either read-write or read-only).

func Update

func Update(ctx context.Context, stmt spanner.Statement) (rowCount int64, err error)

Update executes a DML statement against the database. It returns the number of affected rows. Update returns an error if the statement is a query. However, the query is executed, and any data read will be validated upon commit.

It is a shortcut for MustRW(ctx).Update(...). Panics if the context is not read-write transactional.

func UpdateWithOptions

func UpdateWithOptions(ctx context.Context, stmt spanner.Statement, opts spanner.QueryOptions) (rowCount int64, err error)

UpdateWithOptions executes a DML statement against the database. It returns the number of affected rows. The sql query execution will be optimized based on the given query options.

It is a shortcut for MustRW(ctx).Update(...). Panics if the context is not read-write transactional.

func UseClient

func UseClient(ctx context.Context, client *spanner.Client) context.Context

UseClient installs a Spanner client into the context.

Primarily used by the module initialization code. May be useful in tests as well.

func WithoutTxn

func WithoutTxn(ctx context.Context) context.Context

WithoutTxn returns a copy of the context without the transaction in it.

This can be used to spawn separate independent transactions from within a transaction.

Types

type ModuleOptions

type ModuleOptions struct {
	SpannerEndpoint string // the Spanner endpoint to connect to
	SpannerDatabase string // identifier of Cloud Spanner database to connect to
}

ModuleOptions contain configuration of the Cloud Spanner server module.

func (*ModuleOptions) Register

func (o *ModuleOptions) Register(f *flag.FlagSet)

Register registers the command line flags.

type Transaction

type Transaction interface {
	// ReadRow reads a single row from the database.
	ReadRow(ctx context.Context, table string, key spanner.Key, columns []string) (*spanner.Row, error)

	// Read reads multiple rows from the database.
	Read(ctx context.Context, table string, keys spanner.KeySet, columns []string) *spanner.RowIterator

	// ReadWithOptions reads multiple rows from the database, and allows
	// customizing options.
	ReadWithOptions(ctx context.Context, table string, keys spanner.KeySet, columns []string, opts *spanner.ReadOptions) *spanner.RowIterator

	// Query reads multiple rows returned by SQL statement.
	Query(ctx context.Context, statement spanner.Statement) *spanner.RowIterator

	// QueryWithOptions reads multiple rows returned by SQL statement, and allows
	// customizing options.
	QueryWithOptions(ctx context.Context, statement spanner.Statement, opts spanner.QueryOptions) *spanner.RowIterator
}

Transaction is a common interface of spanner.ReadOnlyTransaction and spanner.ReadWriteTransaction.

func MustTxn

func MustTxn(ctx context.Context) Transaction

MustTxn is like Txn except it panics if `ctx` is not transactional.

func Txn

func Txn(ctx context.Context) Transaction

Txn returns an interface that can be used to read data in the current read-only or read-write transaction.

Returns nil if `ctx` is not a transactional context.