client

package
v1.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 19, 2018 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package client and its KV API have been deprecated for external usage. Please use a postgres-compatible SQL driver (e.g. github.com/lib/pq). For more details, see http://www.cockroachlabs.com/blog/sql-in-cockroachdb-mapping-table-data-to-key-value-storage/.

Package client provides clients for accessing the various externally-facing Cockroach database endpoints.

DB Client

The DB client is a fully-featured client of Cockroach's key-value database. It provides a simple, synchronous interface well-suited to parallel updates and queries.

The simplest way to use the client is through the Run method. Run synchronously invokes the call, fills in the reply and returns an error. The example below shows a get and a put. 

db, err := client.Open("rpcs://root@localhost:26257")
if err != nil {
	log.Fatal(err)
}
if err := db.Put("a", "hello"); err != nil {
	log.Fatal(err)
}
if gr, err := db.Get("a"); err != nil {
	log.Fatal(err)
} else {
	log.Printf("%s", gr.ValueBytes())  // "hello"
}

The API is synchronous, but accommodates efficient parallel updates and queries using Batch objects. An arbitrary number of calls may be added to a Batch which is executed using DB.Run. Note however that the individual calls within a batch are not guaranteed to have atomic semantics. A transaction must be used to guarantee atomicity. A simple example of using a Batch which does two scans in parallel and then sends a sequence of puts in parallel: 

db, err := client.Open("rpcs://root@localhost:26257")
if err != nil {
	log.Fatal(err)
}

b1 := &client.Batch{}
b1.Scan("a", "c\x00", 1000)
b1.Scan("x", "z\x00", 1000)

// Run sends both scans in parallel and returns the first error or nil.
if err := db.Run(b1); err != nil {
	log.Fatal(err)
}

acResult := b1.Results[0]
xzResult := b1.Results[1]

// Append maximum value from "a"-"c" to all values from "x"-"z".
max := []byte(nil)
for _, row := range acResult.Rows {
	if bytes.Compare(max, row.ValueBytes()) < 0 {
		max = row.ValueBytes()
	}
}

b2 := &client.Batch{}
for _, row := range xzResult.Rows {
	b2.Put(row.Key, bytes.Join([][]byte{row.ValueBytes(), max}, []byte(nil)))
}

// Run all puts for parallel execution.
if err := db.Run(b2); err != nil {
	log.Fatal(err)
}

Transactions are supported through the DB.Txn() method, which takes a retryable function, itself composed of the same simple mix of API calls typical of a non-transactional operation. Within the context of the Txn() call, all method invocations are transparently given necessary transactional details, and conflicts are handled with backoff/retry loops and transaction restarts as necessary. An example of using transactions with parallel writes: 

db, err := client.Open("rpcs://root@localhost:26257")
if err != nil {
	log.Fatal(err)
}

err := db.Txn(func(ctx context.Context, txn *client.Txn) error {
	b := txn.NewBatch()
	for i := 0; i < 100; i++ {
		key := fmt.Sprintf("testkey-%02d", i)
		b.Put(key, "test value")
	}

	// Note that the Txn client is flushed automatically when this function
	// returns success (i.e. nil). Calling CommitInBatch explicitly can
	// sometimes reduce the number of RPCs.
	return txn.CommitInBatch(ctx, b)
})
if err != nil {
	log.Fatal(err)
}

Note that with Cockroach's lock-free transactions, clients should expect retries as a matter of course. This is why the transaction functionality is exposed through a retryable function. The retryable function should have no side effects which are not idempotent.

Transactions should endeavor to use batches to perform multiple operations in a single RPC. In addition to the reduced number of RPCs to the server, this allows writes to the same range to be batched together. In cases where the entire transaction affects only a single range, transactions can commit in a single round trip. 

Package client is a generated protocol buffer package.

It is generated from these files:
	cockroach/pkg/internal/client/lease.proto

It has these top-level messages:
	LeaseVal

Index

Constants

View Source 
const DefaultLeaseDuration = 1 * time.Minute

DefaultLeaseDuration is the duration a lease will be acquired for if no duration was specified in a LeaseManager's options. Exported for testing purposes.

Variables

View Source 
var (
	ErrInvalidLengthLease = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowLease   = fmt.Errorf("proto: integer overflow")
)

Functions

func IncrementValRetryable added in v1.1.0 

func IncrementValRetryable(ctx context.Context, db *DB, key roachpb.Key, inc int64) (int64, error)

IncrementValRetryable increments a key's value by a specified amount and returns the new value.

It performs the increment as a retryable non-transactional increment. The key might be incremented multiple times because of the retries.

func SendWrapped 

func SendWrapped(
	ctx context.Context, sender Sender, args roachpb.Request,
) (roachpb.Response, *roachpb.Error)

SendWrapped is identical to SendWrappedWith with a zero header. TODO(tschottdorf): should move this to testutils and merge with other helpers which are used, for example, in `storage`.

func SendWrappedWith 

func SendWrappedWith(
	ctx context.Context, sender Sender, h roachpb.Header, args roachpb.Request,
) (roachpb.Response, *roachpb.Error)

SendWrappedWith is a convenience function which wraps the request in a batch and sends it via the provided Sender and headers. It returns the unwrapped response or an error. It's valid to pass a `nil` context; an empty one is used in that case.

Types

type AutoCommitError 

type AutoCommitError struct {
	// contains filtered or unexported fields
}

AutoCommitError wraps a non-retryable error coming from auto-commit.

func (*AutoCommitError) Error 

func (e *AutoCommitError) Error() string

type Batch 

type Batch struct {

	// Results contains an entry for each operation added to the batch. The order
	// of the results matches the order the operations were added to the
	// batch. For example:
	//
	//   b := db.NewBatch()
	//   b.Put("a", "1")
	//   b.Put("b", "2")
	//   _ = db.Run(b)
	//   // string(b.Results[0].Rows[0].Key) == "a"
	//   // string(b.Results[1].Rows[0].Key) == "b"
	Results []Result
	// The Header which will be used to send the resulting BatchRequest.
	// To be modified directly.
	Header roachpb.Header
	// contains filtered or unexported fields
}

Batch provides for the parallel execution of a number of database operations. Operations are added to the Batch and then the Batch is executed via either DB.Run, Txn.Run or Txn.Commit.

TODO(pmattis): Allow a timestamp to be specified which is applied to all operations within the batch.

func (*Batch) AddRawRequest 

func (b *Batch) AddRawRequest(reqs ...roachpb.Request)

AddRawRequest adds the specified requests to the batch. No responses will be allocated for them, and using any of the non-raw operations will result in an error when running the batch.

func (*Batch) CPut 

func (b *Batch) CPut(key, value, expValue interface{})

CPut conditionally sets the value for a key if the existing value is equal to expValue. To conditionally set a value only if there is no existing entry pass nil for expValue. Note that this must be an interface{}(nil), not a typed nil value (e.g. []byte(nil)).

A new result will be appended to the batch which will contain a single row and Result.Err will indicate success or failure.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*Batch) CheckConsistency 

func (b *Batch) CheckConsistency(s, e interface{}, withDiff bool)

CheckConsistency creates a batch request to check the consistency of the ranges holding the span of keys from s to e. It logs a diff of all the keys that are inconsistent when withDiff is set to true.

func (*Batch) Del 

func (b *Batch) Del(keys ...interface{})

Del deletes one or more keys.

A new result will be appended to the batch and each key will have a corresponding row in the returned Result.

key can be either a byte slice or a string.

func (*Batch) DelRange 

func (b *Batch) DelRange(s, e interface{}, returnKeys bool)

DelRange deletes the rows between begin (inclusive) and end (exclusive).

A new result will be appended to the batch which will contain 0 rows and Result.Err will indicate success or failure.

key can be either a byte slice or a string.

func (*Batch) Get 

func (b *Batch) Get(key interface{})

Get retrieves the value for a key. A new result will be appended to the batch which will contain a single row. 

r, err := db.Get("a")
// string(r.Rows[0].Key) == "a"

key can be either a byte slice or a string.

func (*Batch) Inc 

func (b *Batch) Inc(key interface{}, value int64)

Inc increments the integer value at key. If the key does not exist it will be created with an initial value of 0 which will then be incremented. If the key exists but was set using Put or CPut an error will be returned.

A new result will be appended to the batch which will contain a single row and Result.Err will indicate success or failure.

key can be either a byte slice or a string.

func (*Batch) InitPut 

func (b *Batch) InitPut(key, value interface{}, failOnTombstones bool)

InitPut sets the first value for a key to value. An ConditionFailedError is reported if a value already exists for the key and it's not equal to the value passed in. If failOnTombstones is set to true, tombstones will return a ConditionFailedError just like a mismatched value.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc). It is illegal to set value to nil.

func (*Batch) MustPErr 

func (b *Batch) MustPErr() *roachpb.Error

MustPErr returns the structured error resulting from a failed execution of the batch, asserting that that error is non-nil.

func (*Batch) Put 

func (b *Batch) Put(key, value interface{})

Put sets the value for a key.

A new result will be appended to the batch which will contain a single row and Result.Err will indicate success or failure.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*Batch) PutInline 

func (b *Batch) PutInline(key, value interface{})

PutInline sets the value for a key, but does not maintain multi-version values. The most recent value is always overwritten. Inline values cannot be mutated transactionally and should be used with caution.

A new result will be appended to the batch which will contain a single row and Result.Err will indicate success or failure.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*Batch) RawResponse 

func (b *Batch) RawResponse() *roachpb.BatchResponse

RawResponse returns the BatchResponse which was the result of a successful execution of the batch, and nil otherwise.

func (*Batch) ReverseScan 

func (b *Batch) ReverseScan(s, e interface{})

ReverseScan retrieves the rows between begin (inclusive) and end (exclusive) in descending order.

A new result will be appended to the batch which will contain "rows" (each "row" is a key/value pair) and Result.Err will indicate success or failure.

key can be either a byte slice or a string.

func (*Batch) Scan 

func (b *Batch) Scan(s, e interface{})

Scan retrieves the key/values between begin (inclusive) and end (exclusive) in ascending order.

A new result will be appended to the batch which will contain "rows" (each row is a key/value pair) and Result.Err will indicate success or failure.

key can be either a byte slice or a string.

type DB 

type DB struct {
	// contains filtered or unexported fields
}

DB is a database handle to a single cockroach cluster. A DB is safe for concurrent use by multiple goroutines.

func NewDB 

func NewDB(sender Sender, clock *hlc.Clock) *DB

NewDB returns a new DB.

func NewDBWithContext 

func NewDBWithContext(sender Sender, clock *hlc.Clock, ctx DBContext) *DB

NewDBWithContext returns a new DB with the given parameters.

func (*DB) AddSSTable added in v1.1.0 

func (db *DB) AddSSTable(ctx context.Context, begin, end interface{}, data []byte) error

AddSSTable links a file into the RocksDB log-structured merge-tree. Existing data in the range is cleared.

func (*DB) AdminChangeReplicas 

func (db *DB) AdminChangeReplicas(
	ctx context.Context,
	key interface{},
	changeType roachpb.ReplicaChangeType,
	targets []roachpb.ReplicationTarget,
) error

AdminChangeReplicas adds or removes a set of replicas for a range.

func (*DB) AdminMerge 

func (db *DB) AdminMerge(ctx context.Context, key interface{}) error

AdminMerge merges the range containing key and the subsequent range. After the merge operation is complete, the range containing key will contain all of the key/value pairs of the subsequent range and the subsequent range will no longer exist.

key can be either a byte slice or a string.

func (*DB) AdminSplit 

func (db *DB) AdminSplit(ctx context.Context, spanKey, splitKey interface{}) error

AdminSplit splits the range at splitkey.

spanKey is a key within the range that should be split, and splitKey is the key at which that range should be split. splitKey is not used exactly as provided--it is first mutated by keys.EnsureSafeSplitKey. Accounting for this mutation sometimes requires constructing a key that falls in a different range, hence the separation between spanKey and splitKey. See #16008 for details, and #16344 for the tracking issue to clean this mess up properly.

keys can be either a byte slice or a string.

func (*DB) AdminTransferLease 

func (db *DB) AdminTransferLease(
	ctx context.Context, key interface{}, target roachpb.StoreID,
) error

AdminTransferLease transfers the lease for the range containing key to the specified target. The target replica for the lease transfer must be one of the existing replicas of the range.

key can be either a byte slice or a string.

When this method returns, it's guaranteed that the old lease holder has applied the new lease, but that's about it. It's not guaranteed that the new lease holder has applied it (so it might not know immediately that it is the new lease holder).

func (*DB) CPut 

func (db *DB) CPut(ctx context.Context, key, value, expValue interface{}) error

CPut conditionally sets the value for a key if the existing value is equal to expValue. To conditionally set a value only if there is no existing entry pass nil for expValue. Note that this must be an interface{}(nil), not a typed nil value (e.g. []byte(nil)).

Returns an error if the existing value is not equal to expValue.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*DB) CheckConsistency 

func (db *DB) CheckConsistency(ctx context.Context, begin, end interface{}, withDiff bool) error

CheckConsistency runs a consistency check on all the ranges containing the key span. It logs a diff of all the keys that are inconsistent when withDiff is set to true.

func (*DB) Del 

func (db *DB) Del(ctx context.Context, keys ...interface{}) error

Del deletes one or more keys.

key can be either a byte slice or a string.

func (*DB) DelRange 

func (db *DB) DelRange(ctx context.Context, begin, end interface{}) error

DelRange deletes the rows between begin (inclusive) and end (exclusive).

TODO(pmattis): Perhaps the result should return which rows were deleted.

key can be either a byte slice or a string.

func (*DB) Get 

func (db *DB) Get(ctx context.Context, key interface{}) (KeyValue, error)

Get retrieves the value for a key, returning the retrieved key/value or an error. It is not considered an error for the key not to exist. 

r, err := db.Get("a")
// string(r.Key) == "a"

key can be either a byte slice or a string.

func (*DB) GetProto 

func (db *DB) GetProto(ctx context.Context, key interface{}, msg proto.Message) error

GetProto retrieves the value for a key and decodes the result as a proto message. If the key doesn't exist, the proto will simply be reset.

key can be either a byte slice or a string.

func (*DB) GetSender 

func (db *DB) GetSender() Sender

GetSender returns the underlying Sender. Only exported for tests.

func (*DB) Inc 

func (db *DB) Inc(ctx context.Context, key interface{}, value int64) (KeyValue, error)

Inc increments the integer value at key. If the key does not exist it will be created with an initial value of 0 which will then be incremented. If the key exists but was set using Put or CPut an error will be returned.

key can be either a byte slice or a string.

func (*DB) InitPut 

func (db *DB) InitPut(ctx context.Context, key, value interface{}, failOnTombstones bool) error

InitPut sets the first value for a key to value. A ConditionFailedError is reported if a value already exists for the key and it's not equal to the value passed in. If failOnTombstones is set to true, tombstones count as mismatched values and will cause a ConditionFailedError.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc). It is illegal to set value to nil.

func (*DB) Put 

func (db *DB) Put(ctx context.Context, key, value interface{}) error

Put sets the value for a key.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*DB) PutInline 

func (db *DB) PutInline(ctx context.Context, key, value interface{}) error

PutInline sets the value for a key, but does not maintain multi-version values. The most recent value is always overwritten. Inline values cannot be mutated transactionally and should be used with caution.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*DB) ReverseScan 

func (db *DB) ReverseScan(
	ctx context.Context, begin, end interface{}, maxRows int64,
) ([]KeyValue, error)

ReverseScan retrieves the rows between begin (inclusive) and end (exclusive) in descending order.

The returned []KeyValue will contain up to maxRows elements.

key can be either a byte slice or a string.

func (*DB) Run 

func (db *DB) Run(ctx context.Context, b *Batch) error

Run executes the operations queued up within a batch. Before executing any of the operations the batch is first checked to see if there were any errors during its construction (e.g. failure to marshal a proto message).

The operations within a batch are run in parallel and the order is non-deterministic. It is an unspecified behavior to modify and retrieve the same key within a batch.

Upon completion, Batch.Results will contain the results for each operation. The order of the results matches the order the operations were added to the batch.

func (*DB) Scan 

func (db *DB) Scan(ctx context.Context, begin, end interface{}, maxRows int64) ([]KeyValue, error)

Scan retrieves the rows between begin (inclusive) and end (exclusive) in ascending order.

The returned []KeyValue will contain up to maxRows elements.

key can be either a byte slice or a string.

func (*DB) Txn 

func (db *DB) Txn(ctx context.Context, retryable func(context.Context, *Txn) error) error

Txn executes retryable in the context of a distributed transaction. The transaction is automatically aborted if retryable returns any error aside from recoverable internal errors, and is automatically committed otherwise. The retryable function should have no side effects which could cause problems in the event it must be run more than once.

If you need more control over how the txn is executed, check out txn.Exec().

func (*DB) WriteBatch 

func (db *DB) WriteBatch(ctx context.Context, begin, end interface{}, data []byte) error

WriteBatch applies the operations encoded in a BatchRepr, which is the serialized form of a RocksDB Batch. The command cannot span Ranges and must be run on an empty keyrange.

type DBContext 

type DBContext struct {
	// UserPriority is the default user priority to set on API calls. If
	// userPriority is set to any value except 1 in call arguments, this
	// value is ignored.
	UserPriority roachpb.UserPriority
}

DBContext contains configuration parameters for DB.

func DefaultDBContext 

func DefaultDBContext() DBContext

DefaultDBContext returns (a copy of) the default options for NewDBWithContext.

type KeyValue 

type KeyValue struct {
	Key   roachpb.Key
	Value *roachpb.Value // Timestamp will always be zero
}

KeyValue represents a single key/value pair. This is similar to roachpb.KeyValue except that the value may be nil.

func (*KeyValue) Exists 

func (kv *KeyValue) Exists() bool

Exists returns true iff the value exists.

func (*KeyValue) PrettyValue 

func (kv *KeyValue) PrettyValue() string

PrettyValue returns a human-readable version of the value as a string.

func (*KeyValue) String 

func (kv *KeyValue) String() string

func (*KeyValue) ValueBytes 

func (kv *KeyValue) ValueBytes() []byte

ValueBytes returns the value as a byte slice. This method will panic if the value's type is not a byte slice.

func (*KeyValue) ValueInt 

func (kv *KeyValue) ValueInt() int64

ValueInt returns the value decoded as an int64. This method will panic if the value cannot be decoded as an int64.

func (*KeyValue) ValueProto 

func (kv *KeyValue) ValueProto(msg proto.Message) error

ValueProto parses the byte slice value into msg.

type Lease 

type Lease struct {
	// contains filtered or unexported fields
}

Lease contains the state of a lease on a particular key.

type LeaseManager 

type LeaseManager struct {
	// contains filtered or unexported fields
}

LeaseManager provides functionality for acquiring and managing leases via the kv api.

func NewLeaseManager 

func NewLeaseManager(db *DB, clock *hlc.Clock, options LeaseManagerOptions) *LeaseManager

NewLeaseManager allocates a new LeaseManager.

func (*LeaseManager) AcquireLease 

func (m *LeaseManager) AcquireLease(ctx context.Context, key roachpb.Key) (*Lease, error)

AcquireLease attempts to grab a lease on the provided key. Returns a non-nil lease object if it was successful, or an error if it failed to acquire the lease for any reason.

NB: Acquiring a non-expired lease is allowed if this LeaseManager's clientID matches the lease owner's ID. This behavior allows a process to re-grab leases without having to wait if it restarts and uses the same ID.

func (*LeaseManager) ExtendLease 

func (m *LeaseManager) ExtendLease(ctx context.Context, l *Lease) error

ExtendLease attempts to push the expiration time of the lease farther out into the future.

func (*LeaseManager) ReleaseLease 

func (m *LeaseManager) ReleaseLease(ctx context.Context, l *Lease) error

ReleaseLease attempts to release the given lease so that another process can grab it.

func (*LeaseManager) TimeRemaining 

func (m *LeaseManager) TimeRemaining(l *Lease) time.Duration

TimeRemaining returns the amount of time left on the given lease.

type LeaseManagerOptions 

type LeaseManagerOptions struct {
	// ClientID must be unique to this LeaseManager instance.
	ClientID      string
	LeaseDuration time.Duration
}

LeaseManagerOptions are used to configure a new LeaseManager.

type LeaseNotAvailableError 

type LeaseNotAvailableError struct {
	// contains filtered or unexported fields
}

LeaseNotAvailableError indicates that the lease the caller attempted to acquire is currently held by a different client.

func (*LeaseNotAvailableError) Error 

func (e *LeaseNotAvailableError) Error() string

type LeaseVal 

type LeaseVal struct {
	// An opaque string that should be unique per client to identify which client
	// owns the lease.
	Owner string `protobuf:"bytes,1,opt,name=owner" json:"owner"`
	// The expiration time of the lease.
	Expiration cockroach_util_hlc.Timestamp `protobuf:"bytes,2,opt,name=expiration" json:"expiration"`
}

func (*LeaseVal) Descriptor 

func (*LeaseVal) Descriptor() ([]byte, []int)

func (*LeaseVal) Marshal 

func (m *LeaseVal) Marshal() (dAtA []byte, err error)

func (*LeaseVal) MarshalTo 

func (m *LeaseVal) MarshalTo(dAtA []byte) (int, error)

func (*LeaseVal) ProtoMessage 

func (*LeaseVal) ProtoMessage()

func (*LeaseVal) Reset 

func (m *LeaseVal) Reset()

func (*LeaseVal) Size 

func (m *LeaseVal) Size() (n int)

func (*LeaseVal) String 

func (m *LeaseVal) String() string

func (*LeaseVal) Unmarshal 

func (m *LeaseVal) Unmarshal(dAtA []byte) error

type Result 

type Result struct {

	// Err contains any error encountered when performing the operation.
	Err error
	// Rows contains the key/value pairs for the operation. The number of rows
	// returned varies by operation. For Get, Put, CPut, Inc and Del the number
	// of rows returned is the number of keys operated on. For Scan the number of
	// rows returned is the number or rows matching the scan capped by the
	// maxRows parameter. For DelRange Rows is nil.
	Rows []KeyValue

	// Keys is set by some operations instead of returning the rows themselves.
	Keys []roachpb.Key

	// ResumeSpan is the the span to be used on the next operation in a
	// sequence of operations. It is returned whenever an operation over a
	// span of keys is bounded and the operation returns before completely
	// running over the span. It allows the operation to be called again with
	// a new shorter span of keys. An empty span is returned when the
	// operation has successfully completed running through the span.
	ResumeSpan roachpb.Span

	// RangeInfos contains information about the replicas that produced this
	// result.
	// This is only populated if Err == nil and if ReturnRangeInfo has been set on
	// the request.
	RangeInfos []roachpb.RangeInfo
	// contains filtered or unexported fields
}

Result holds the result for a single DB or Txn operation (e.g. Get, Put, etc).

func (Result) String 

func (r Result) String() string

type Sender 

type Sender interface {
	Send(context.Context, roachpb.BatchRequest) (*roachpb.BatchResponse, *roachpb.Error)
}

Sender is the interface used to call into a Cockroach instance. If the returned *roachpb.Error is not nil, no response should be returned.

func NewSender 

func NewSender(conn *grpc.ClientConn) Sender

NewSender returns an implementation of Sender which exposes the Key-Value database provided by a Cockroach cluster by connecting via RPC to a Cockroach node.

This must not be used by server.Server or any of its components, only by clients talking to a Cockroach cluster through the external interface.

func Wrap 

func Wrap(sender Sender, f func(roachpb.BatchRequest) roachpb.BatchRequest) Sender

Wrap returns a Sender which applies the given function before delegating to the supplied Sender.

type SenderFunc 

type SenderFunc func(context.Context, roachpb.BatchRequest) (*roachpb.BatchResponse, *roachpb.Error)

SenderFunc is an adapter to allow the use of ordinary functions as Senders.

func (SenderFunc) Send 

func (f SenderFunc) Send(
	ctx context.Context, ba roachpb.BatchRequest,
) (*roachpb.BatchResponse, *roachpb.Error)

Send calls f(ctx, c).

type SenderWithDistSQLBackdoor 

type SenderWithDistSQLBackdoor interface {
	Sender

	// GetTxnState returns the state that the TxnCoordSender has for a
	// transaction. The bool is false is no state is found.
	GetTxnState(txnID uuid.UUID) (roachpb.Transaction, bool)
}

SenderWithDistSQLBackdoor is implemented by the TxnCoordSender to give DistSQL some hacky powers when handling errors that happened on remote nodes.

type Txn 

type Txn struct {
	// contains filtered or unexported fields
}

Txn is an in-progress distributed database transaction. A Txn is safe for concurrent use by multiple goroutines.

func NewTxn 

func NewTxn(db *DB, gatewayNodeID roachpb.NodeID) *Txn

NewTxn returns a new txn.

gatewayNodeID: If != 0, this is the ID of the node on whose behalf this 

transaction is running. Normally this is the current node, but in the case
of Txns created on remote nodes by DistSQL this will be the gateway.
If 0 is passed, then no value is going to be filled in the batches sent
through this txn. This will have the effect that the DistSender will fill
in the batch with the current node's ID.

func NewTxnWithProto 

func NewTxnWithProto(db *DB, gatewayNodeID roachpb.NodeID, proto roachpb.Transaction) *Txn

NewTxnWithProto is like NewTxn, except it returns a new txn with the provided Transaction proto. This allows a client.Txn to be created with an already initialized proto.

func (*Txn) AcceptUnhandledRetryableErrors 

func (txn *Txn) AcceptUnhandledRetryableErrors()

AcceptUnhandledRetryableErrors is used by DistSQL to make the client.Txn not freak out on errors that should be handled by the TxnCoordSender.

func (*Txn) AddCommitTrigger 

func (txn *Txn) AddCommitTrigger(trigger func())

AddCommitTrigger adds a closure to be executed on successful commit of the transaction.

func (*Txn) AnchorKey 

func (txn *Txn) AnchorKey() []byte

AnchorKey returns the transaction's anchor key. The caller should treat the returned byte slice as immutable.

func (*Txn) CPut 

func (txn *Txn) CPut(ctx context.Context, key, value, expValue interface{}) error

CPut conditionally sets the value for a key if the existing value is equal to expValue. To conditionally set a value only if there is no existing entry pass nil for expValue. Note that this must be an interface{}(nil), not a typed nil value (e.g. []byte(nil)).

Returns an error if the existing value is not equal to expValue.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*Txn) CleanupOnError 

func (txn *Txn) CleanupOnError(ctx context.Context, err error)

CleanupOnError cleans up the transaction as a result of an error.

func (*Txn) CommandCount 

func (txn *Txn) CommandCount() int

CommandCount returns the count of commands executed through this txn. Retryable errors on the transaction will reset the count to 0.

func (*Txn) Commit 

func (txn *Txn) Commit(ctx context.Context) error

Commit is the same as CommitOrCleanup but will not attempt to clean up on failure. This can be used when the caller is prepared to do proper cleanup.

func (*Txn) CommitInBatch 

func (txn *Txn) CommitInBatch(ctx context.Context, b *Batch) error

CommitInBatch executes the operations queued up within a batch and commits the transaction. Explicitly committing a transaction is optional, but more efficient than relying on the implicit commit performed when the transaction function returns without error. The batch must be created by this transaction. If the command completes successfully, the txn is considered finalized. On error, no attempt is made to clean up the (possibly still pending) transaction.

func (*Txn) CommitOrCleanup 

func (txn *Txn) CommitOrCleanup(ctx context.Context) error

CommitOrCleanup sends an EndTransactionRequest with Commit=true. If that fails, an attempt to rollback is made. txn should not be used to send any more commands after this call.

func (*Txn) DebugName 

func (txn *Txn) DebugName() string

DebugName returns the debug name associated with the transaction.

func (*Txn) Del 

func (txn *Txn) Del(ctx context.Context, keys ...interface{}) error

Del deletes one or more keys.

key can be either a byte slice or a string.

func (*Txn) DelRange 

func (txn *Txn) DelRange(ctx context.Context, begin, end interface{}) error

DelRange deletes the rows between begin (inclusive) and end (exclusive).

The returned Result will contain 0 rows and Result.Err will indicate success or failure.

key can be either a byte slice or a string.

func (*Txn) Exec 

func (txn *Txn) Exec(
	ctx context.Context, opt TxnExecOptions, fn func(context.Context, *Txn, *TxnExecOptions) error,
) (err error)

Exec executes fn in the context of a distributed transaction. Execution is controlled by opt (see comments in TxnExecOptions).

opt is passed to fn, and it's valid for fn to modify opt as it sees fit during each execution attempt.

It's valid for txn to be nil (meaning the txn has already aborted) if fn can handle that. This is useful for continuing transactions that have been aborted because of an error in a previous batch of statements in the hope that a ROLLBACK will reset the state. Neither opt.AutoRetry not opt.AutoCommit can be set in this case.

It is not permitted to call Commit concurrently with any call to Exec. Since Exec with the AutoCommitflag is equivalent to an Exec possibly followed by a Commit, it must not be called concurrently with any other call to Exec or Commit.

When this method returns, txn might be in any state; Exec does not attempt to clean up the transaction before returning an error. In case of TransactionAbortedError, txn is reset to a fresh transaction, ready to be used.

TODO(andrei): The SQL Executor was the most complex user of this interface. It needed fine control by using TxnExecOptions. Now SQL no longer uses this interface, so it's time to see how it can be simplified. TxnExecOptions can probably go away, and so can AutoCommitError. The method should also be documented to not allow calls concurrent with any other txn use, so that the Commit() call inside it is clearly correct (as in, it won't run concurrently with other txn calls).

func (*Txn) GenerateForcedRetryableError added in v1.1.0 

func (txn *Txn) GenerateForcedRetryableError(msg string) error

GenerateForcedRetryableError returns a HandledRetryableTxnError that will cause the txn to be retried.

func (*Txn) Get 

func (txn *Txn) Get(ctx context.Context, key interface{}) (KeyValue, error)

Get retrieves the value for a key, returning the retrieved key/value or an error. It is not considered an error for the key to not exist. 

r, err := db.Get("a")
// string(r.Key) == "a"

key can be either a byte slice or a string.

func (*Txn) GetProto 

func (txn *Txn) GetProto(ctx context.Context, key interface{}, msg proto.Message) error

GetProto retrieves the value for a key and decodes the result as a proto message. If the key doesn't exist, the proto will simply be reset.

key can be either a byte slice or a string.

func (*Txn) ID added in v1.1.0 

func (txn *Txn) ID() uuid.UUID

ID returns the current ID of the transaction.

func (*Txn) Inc 

func (txn *Txn) Inc(ctx context.Context, key interface{}, value int64) (KeyValue, error)

Inc increments the integer value at key. If the key does not exist it will be created with an initial value of 0 which will then be incremented. If the key exists but was set using Put or CPut an error will be returned.

The returned Result will contain a single row and Result.Err will indicate success or failure.

key can be either a byte slice or a string.

func (*Txn) InitPut 

func (txn *Txn) InitPut(ctx context.Context, key, value interface{}, failOnTombstones bool) error

InitPut sets the first value for a key to value. An error is reported if a value already exists for the key and it's not equal to the value passed in. If failOnTombstones is set to true, tombstones count as mismatched values and will cause a ConditionFailedError.

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc). It is illegal to set value to nil.

func (*Txn) InternalSetPriority 

func (txn *Txn) InternalSetPriority(priority int32)

InternalSetPriority sets the transaction priority. It is intended for internal (testing) use only.

func (*Txn) IsAborted added in v1.1.0 

func (txn *Txn) IsAborted() bool

IsAborted returns true if the transaction has the aborted status.

func (*Txn) IsCommitted added in v1.1.0 

func (txn *Txn) IsCommitted() bool

IsCommitted returns true if the transaction has the committed status.

func (*Txn) IsFinalized 

func (txn *Txn) IsFinalized() bool

IsFinalized returns true if this Txn has been finalized and should therefore not be used for any more KV operations. A Txn is considered finalized if it successfully committed or if a rollback was attempted (successful or not). Note that Commit() always leaves the transaction finalized, since it attempts to rollback on error.

func (*Txn) IsRetryableErrMeantForTxn 

func (txn *Txn) IsRetryableErrMeantForTxn(retryErr roachpb.HandledRetryableTxnError) bool

IsRetryableErrMeantForTxn returns true if err is a retryable error meant to restart this client transaction.

func (*Txn) IsSerializableRestart added in v1.1.0 

func (txn *Txn) IsSerializableRestart() bool

IsSerializableRestart returns true if the transaction is serializable and its timestamp has been pushed. Used to detect whether the txn will be allowed to commit.

Note that this method allows for false negatives: sometimes the client only figures out that it's been pushed when it sends an EndTransaction - i.e. it's possible for the txn to have been pushed asynchoronously by some other operation (usually, but not exclusively, by a high-priority txn with conflicting writes).

func (*Txn) Isolation 

func (txn *Txn) Isolation() enginepb.IsolationType

Isolation returns the transaction's isolation type.

func (*Txn) NewBatch 

func (txn *Txn) NewBatch() *Batch

NewBatch creates and returns a new empty batch object for use with the Txn.

func (*Txn) OrigTimestamp 

func (txn *Txn) OrigTimestamp() hlc.Timestamp

OrigTimestamp returns the transaction's starting timestamp.

func (*Txn) PrepareForRetry added in v1.1.0 

func (txn *Txn) PrepareForRetry(ctx context.Context, err error)

PrepareForRetry needs to be called before an retry to perform some book-keeping.

TODO(andrei): I think this is called in the wrong place. See #18170.

func (*Txn) Proto 

func (txn *Txn) Proto() *roachpb.Transaction

Proto returns the transactions underlying protocol buffer. It is not thread-safe, only use if you know that no requests are executing concurrently.

A thread-safe alternative would be to clone the Proto under lock and return this clone, but we currently have no situations where this is needed.

func (*Txn) Put 

func (txn *Txn) Put(ctx context.Context, key, value interface{}) error

Put sets the value for a key

key can be either a byte slice or a string. value can be any key type, a proto.Message or any Go primitive type (bool, int, etc).

func (*Txn) ResetDeadline 

func (txn *Txn) ResetDeadline()

ResetDeadline resets the deadline.

func (*Txn) ReverseScan 

func (txn *Txn) ReverseScan(
	ctx context.Context, begin, end interface{}, maxRows int64,
) ([]KeyValue, error)

ReverseScan retrieves the rows between begin (inclusive) and end (exclusive) in descending order.

The returned []KeyValue will contain up to maxRows elements (or all results when zero is supplied).

key can be either a byte slice or a string.

func (*Txn) Rollback 

func (txn *Txn) Rollback(ctx context.Context) error

Rollback sends an EndTransactionRequest with Commit=false. txn is considered finalized and cannot be used to send any more commands.

func (*Txn) Run 

func (txn *Txn) Run(ctx context.Context, b *Batch) error

Run executes the operations queued up within a batch. Before executing any of the operations the batch is first checked to see if there were any errors during its construction (e.g. failure to marshal a proto message).

The operations within a batch are run in parallel and the order is non-deterministic. It is an unspecified behavior to modify and retrieve the same key within a batch.

Upon completion, Batch.Results will contain the results for each operation. The order of the results matches the order the operations were added to the batch.

func (*Txn) Scan 

func (txn *Txn) Scan(
	ctx context.Context, begin, end interface{}, maxRows int64,
) ([]KeyValue, error)

Scan retrieves the rows between begin (inclusive) and end (exclusive) in ascending order.

The returned []KeyValue will contain up to maxRows elements (or all results when zero is supplied).

key can be either a byte slice or a string.

func (*Txn) Send added in v1.1.0 

func (txn *Txn) Send(
	ctx context.Context, ba roachpb.BatchRequest,
) (*roachpb.BatchResponse, *roachpb.Error)

Send runs the specified calls synchronously in a single batch and returns any errors. If the transaction is read-only or has already been successfully committed or aborted, a potential trailing EndTransaction call is silently dropped, allowing the caller to always commit or clean-up explicitly even when that may not be required (or even erroneous). Returns (nil, nil) for an empty batch.

func (*Txn) SetDebugName 

func (txn *Txn) SetDebugName(name string)

SetDebugName sets the debug name associated with the transaction which will appear in log files and the web UI.

func (*Txn) SetFixedTimestamp added in v1.1.0 

func (txn *Txn) SetFixedTimestamp(ctx context.Context, ts hlc.Timestamp)

SetFixedTimestamp makes the transaction run in an unusual way, at a "fixed timestamp": Timestamp and OrigTimestamp are set to ts, there's no clock uncertainty, and the txn's deadline is set to ts such that the transaction can't be pushed to a different timestamp.

This is used to support historical queries (AS OF SYSTEM TIME queries and backups). This method must be called on every transaction retry (but note that retries should be rare for read-only queries with no clock uncertainty).

func (*Txn) SetIsolation 

func (txn *Txn) SetIsolation(isolation enginepb.IsolationType) error

SetIsolation sets the transaction's isolation type. Transactions default to serializable isolation. The isolation must be set before any operations are performed on the transaction.

func (*Txn) SetSystemConfigTrigger 

func (txn *Txn) SetSystemConfigTrigger() error

SetSystemConfigTrigger sets the system db trigger to true on this transaction. This will impact the EndTransactionRequest.

NOTE: The system db trigger will only execute correctly if the transaction record is located on the range that contains the system span. If a transaction is created which modifies both system *and* non-system data, it should be ensured that the transaction record itself is on the system span. This can be done by making sure a system key is the first key touched in the transaction.

func (*Txn) SetTxnAnchorKey 

func (txn *Txn) SetTxnAnchorKey(key roachpb.Key) error

SetTxnAnchorKey sets the key at which to anchor the transaction record. The transaction anchor key defaults to the first key written in a transaction.

func (*Txn) SetUserPriority 

func (txn *Txn) SetUserPriority(userPriority roachpb.UserPriority) error

SetUserPriority sets the transaction's user priority. Transactions default to normal user priority. The user priority must be set before any operations are performed on the transaction.

func (*Txn) UpdateDeadlineMaybe 

func (txn *Txn) UpdateDeadlineMaybe(ctx context.Context, deadline hlc.Timestamp) bool

UpdateDeadlineMaybe sets the transactions deadline to the lower of the current one (if any) and the passed value.

The deadline cannot be lower than txn.OrigTimestamp.

func (*Txn) UpdateStateOnRemoteRetryableErr 

func (txn *Txn) UpdateStateOnRemoteRetryableErr(ctx context.Context, pErr roachpb.Error)

UpdateStateOnRemoteRetryableErr updates the Txn, and the Transaction proto inside it, in response to an error encountered when running a request through the txn. If the error is not a RetryableTxnError, then this is a no-op. For a retryable error, the Transaction proto is either initialized with the updated proto from the error, or a new Transaction proto is initialized.

func (*Txn) UserPriority 

func (txn *Txn) UserPriority() roachpb.UserPriority

UserPriority returns the transaction's user priority.

type TxnExecOptions 

type TxnExecOptions struct {
	// If set, the transaction is automatically aborted if the closure returns any
	// error aside from recoverable internal errors, in which case the closure is
	// retried. The retryable function should have no side effects which could
	// cause problems in the event it must be run more than once.
	// If not set, all errors cause the txn to be aborted.
	AutoRetry bool
	// If set, then the txn is automatically committed if no errors are
	// encountered. If not set, committing or leaving open the txn is the
	// responsibility of the client.
	AutoCommit bool
}

TxnExecOptions controls how Exec() runs a transaction and the corresponding closure.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.