import "go.chromium.org/luci/server/span"
Package span implements a server module for communicating with Cloud Spanner.
var ModuleName = module.RegisterName("go.chromium.org/luci/server/span")
ModuleName can be used to refer to this module when declaring dependencies.
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.
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.
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(ctx context.Context) *spanner.ReadOnlyTransaction
MustRO is like RO except it panics if `ctx` is not read-only transactional.
func MustRW(ctx context.Context) *spanner.ReadWriteTransaction
MustRW is like RW except it panics if `ctx` is not read-write transactional.
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.
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(...).
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(ctx context.Context) *spanner.ReadOnlyTransaction
RO returns the current read-only transaction in the context of nil if it's not a read-only transactional context.
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(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.
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(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(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(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.
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).
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(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.
UseClient installs a Spanner client into the context.
Primarily used by the module initialization code. May be useful in tests as well.
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.
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 (o *ModuleOptions) Register(f *flag.FlagSet)
Register registers the command line flags.
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(ctx context.Context) Transaction
MustTxn is like Txn except it panics if `ctx` is not transactional.
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.
Package span imports 12 packages (graph) and is imported by 24 packages. Updated 2021-01-24. Refresh now. Tools for package owners.