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 BatchWrite(ctx context.Context, mgs []*spanner.MutationGroup) *spanner.BatchWriteResponseIterator
- func BatchWriteWithOptions(ctx context.Context, mgs []*spanner.MutationGroup, ...) *spanner.BatchWriteResponseIterator
- func BufferWrite(ctx context.Context, ms ...*spanner.Mutation)
- func Defer(ctx context.Context, cb func(context.Context))
- func ModifyRequestOptions(ctx context.Context, cb func(*RequestOptions)) context.Context
- func MustRO(ctx context.Context) *spanner.ReadOnlyTransaction
- func MustRW(ctx context.Context) *spanner.ReadWriteTransaction
- func NewModule(opts *ModuleOptions) module.Module
- func NewModuleFromFlags(cfg ClientConfigProvider) module.Module
- func PartitionedUpdate(ctx context.Context, st spanner.Statement) (count int64, err error)
- 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 ReadRowWithOptions(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 ClientConfigProvider
- type ModuleOptions
- type RequestOptions
- type Transaction
Constants ¶
This section is empty.
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 BatchWrite ¶
func BatchWrite(ctx context.Context, mgs []*spanner.MutationGroup) *spanner.BatchWriteResponseIterator
BatchWrite applies a list of mutation groups in a collection of efficient transactions.
See https://pkg.go.dev/cloud.google.com/go/spanner#Client.BatchWrite for details.
Must be used outside of any transactions since it launches transactions itself and nested transactions are not supported. Panics if the context is transactional.
func BatchWriteWithOptions ¶
func BatchWriteWithOptions(ctx context.Context, mgs []*spanner.MutationGroup, opts spanner.BatchWriteOptions) *spanner.BatchWriteResponseIterator
BatchWriteWithOptions applies a list of mutation groups in a collection of efficient transactions.
See https://pkg.go.dev/cloud.google.com/go/spanner#Client.BatchWrite for details.
Must be used outside of any transactions since it launches transactions itself and nested transactions are not supported. Panics if the context is transactional.
func BufferWrite ¶
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 ¶
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 ModifyRequestOptions ¶
func ModifyRequestOptions(ctx context.Context, cb func(*RequestOptions)) context.Context
ModifyRequestOptions returns a new Context that carries default Spanner request options.
These request options will be used by all Spanner operations in this module if the underlying operation supports it, except the *WithOptions functions (where the caller provides options explicitly).
The cb function will be called with the current defaults from the context, to allow for incremental updates.
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(cfg ClientConfigProvider) module.Module
NewModuleFromFlags is a variant of NewModule that initializes applicable options through command line flags.
Calling this function registers flags in flag.CommandLine. They are usually parsed in server.Main(...).
If given a non-nil ClientConfigProvider callback, it will be called when creating the Cloud Spanner client to get a custom spanner.ClientConfig. This can be used to set custom retry policies and timeouts, see https://cloud.google.com/spanner/docs/custom-timeout-and-retry.
func PartitionedUpdate ¶
PartitionedUpdate executes a DML statement in parallel across the database, using separate, internal transactions that commit independently.
Panics if called from inside a read-write transaction.
func Query ¶
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 ¶
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 ReadRowWithOptions ¶
func ReadRowWithOptions(ctx context.Context, table string, key spanner.Key, columns []string, opts *spanner.ReadOptions) (*spanner.Row, error)
ReadRowWithOptions reads a single row from the database, and allows customizing options.
It is a shortcut for MustTxn(ctx).ReadRowWithOptions(ctx, ...). Panics if the context is not transactional.
It does not use the default RequestOptions from the ctx. Use opts to pass these explicitly.
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.
It does not use the default RequestOptions from the ctx. Use opts to pass these explicitly.
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 ¶
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 ¶
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.
It does not use the default RequestOptions from the ctx. Use opts to pass these explicitly.
Types ¶
type ClientConfigProvider ¶
type ClientConfigProvider func(ctx context.Context, opts module.HostOptions) (spanner.ClientConfig, error)
ClientConfigProvider supplies custom Cloud Spanner client config.
This callback is called right before constructing the spanner client.
type ModuleOptions ¶
type ModuleOptions struct { SpannerEndpoint string // the Spanner endpoint to connect to SpannerDatabase string // identifier of Cloud Spanner database to connect to ClientConfig ClientConfigProvider // if set, use the provided client config }
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 RequestOptions ¶
type RequestOptions struct { Tag string Priority sppb.RequestOptions_Priority }
RequestOptions holds options common to many Spanner requests.
Used for setting default request options in the context via ModifyRequestOptions. See also spanner.ReadOptions also spanner.QueryOptions.
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) // ReadRowWithOptions reads a single row from the database, and allows customizing options. ReadRowWithOptions(ctx context.Context, table string, key spanner.Key, columns []string, opts *spanner.ReadOptions) (*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.