data.proto

// Copyright 2014 The Cockroach Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
// implied. See the License for the specific language governing
// permissions and limitations under the License.
//
// Author: Jiajia Han (hanjia18@gmail.com)
// Author: Spencer Kimball (spencer.kimball@gmail.com)

syntax = "proto2";
package cockroach.roachpb;
option go_package = "roachpb";

import "cockroach/roachpb/metadata.proto";
import weak "gogoproto/gogo.proto";

// Span is supplied with every storage node request.
message Span {
  option (gogoproto.populate) = true;

  // The key for request. If the request operates on a range, this
  // represents the starting key for the range.
  optional bytes key = 3 [(gogoproto.casttype) = "Key"];
  // The end key is empty if the request spans only a single key. Otherwise,
  // it must order strictly after Key. In such a case, the header indicates
  // that the operation takes place on the key range from Key to EndKey,
  // including Key and excluding EndKey.
  optional bytes end_key = 4 [(gogoproto.casttype) = "Key"];
}

// Timestamp represents a state of the hybrid logical clock.
message Timestamp {
  option (gogoproto.goproto_stringer) = false;
  option (gogoproto.populate) = true;

  // Holds a wall time, typically a unix epoch time
  // expressed in nanoseconds.
  optional int64 wall_time = 1 [(gogoproto.nullable) = false];
  // The logical component captures causality for events whose wall
  // times are equal. It is effectively bounded by (maximum clock
  // skew)/(minimal ns between events) and nearly impossible to
  // overflow.
  optional int32 logical = 2 [(gogoproto.nullable) = false];
}

// ValueType defines a set of type constants placed in the "tag" field of Value
// messages. These are defined as a protocol buffer enumeration so that they
// can be used portably between our Go and C code. The tags are used by the
// RocksDB Merge Operator to perform specialized merges.
enum ValueType {
  // This is a subset of the SQL column type values, representing the
  // underlying storage for various types.
  UNKNOWN = 0;
  INT = 1;
  FLOAT = 2;
  BYTES = 3;
  TIME = 4;
  DECIMAL = 5;
  DURATION = 6;

  // TIMESERIES is applied to values which contain InternalTimeSeriesData.
  TIMESERIES = 100;
}

// Value specifies the value at a key. Multiple values at the same key are
// supported based on timestamp. The data stored within a value is typed
// (ValueType) and custom encoded into the raw_bytes field. A custom encoding
// is used instead of separate proto fields to avoid proto overhead and to
// avoid unnecessary encoding and decoding as the value gets read from disk and
// passed through the network. The format is:
//
//   <4-byte-checksum><1-byte-tag><encoded-data>
//
// A CRC-32-IEEE checksum is computed from the associated key, tag and encoded
// data, in that order.
//
// TODO(peter): Is a 4-byte checksum overkill when most (all?) values
// will be less than 64KB?
message Value {
  // raw_bytes contains the encoded value and checksum.
  optional bytes raw_bytes = 1;
  // Timestamp of value.
  optional Timestamp timestamp = 2 [(gogoproto.nullable) = false];
}

// KeyValue is a pair of Key and Value for returned Key/Value pairs
// from ScanRequest/ScanResponse. It embeds a Key and a Value.
message KeyValue {
  optional bytes key = 1 [(gogoproto.casttype) = "Key"];
  optional Value value = 2 [(gogoproto.nullable) = false];
}

// A StoreIdent uniquely identifies a store in the cluster. The
// StoreIdent is written to the underlying storage engine at a
// store-reserved system key (KeyLocalIdent).
message StoreIdent {
  optional bytes cluster_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ClusterID",
      (gogoproto.customtype) = "github.com/cockroachdb/cockroach/util/uuid.UUID"];
  optional int32 node_id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "NodeID", (gogoproto.casttype) = "NodeID"];
  optional int32 store_id = 3 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "StoreID", (gogoproto.casttype) = "StoreID"];
}

// A SplitTrigger is run after a successful commit of an AdminSplit
// command. It provides the updated range descriptor covering the
// first half of the split and the new range descriptor covering the
// second half. This information allows the final bookkeeping for
// the split to be completed and the new range put into operation.
message SplitTrigger {
  optional RangeDescriptor updated_desc = 1 [(gogoproto.nullable) = false];
  optional RangeDescriptor new_desc = 2 [(gogoproto.nullable) = false];

  // initial_leader_store_id designates the replica which should start
  // a raft election upon processing this split.
  optional int32 initial_leader_store_id = 3 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "InitialLeaderStoreID",
      (gogoproto.casttype) = "StoreID"];
}

// A MergeTrigger is run after a successful commit of an AdminMerge
// command. It provides the updated range descriptor that now encompasses
// what was originally both ranges and the soon to be invalid range
// descriptor that used to cover the subsumed half of the merge. This
// information allows the final bookkeeping for the merge to be completed
// and put into operation.
message MergeTrigger {
  // The updated range descriptor that now encompasses what was originally
  // both ranges.
  optional RangeDescriptor updated_desc = 1 [(gogoproto.nullable) = false];
  // The soon to be invalid range descriptor that used to cover the subsumed
  // half of the merge.
  optional RangeDescriptor subsumed_desc = 2 [(gogoproto.nullable) = false];
}

// ReplicaChangeType is a parameter of ChangeReplicasTrigger.
enum ReplicaChangeType {
  option (gogoproto.goproto_enum_prefix) = false;

  ADD_REPLICA = 0;
  REMOVE_REPLICA = 1;
}

message ChangeReplicasTrigger {
  optional ReplicaChangeType change_type = 1 [(gogoproto.nullable) = false];
  // The replica being modified.
  optional ReplicaDescriptor replica = 2 [(gogoproto.nullable) = false];
  // The new replica list with this change applied.
  repeated ReplicaDescriptor updated_replicas = 3 [(gogoproto.nullable) = false];
  optional int32 next_replica_id = 4 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "NextReplicaID", (gogoproto.casttype) = "ReplicaID"];
}

// ModifiedSpanTrigger indicates that a specific span has been modified.
// This can be used to trigger scan-and-gossip for the given span.
message ModifiedSpanTrigger {
  optional bool system_config_span = 1 [(gogoproto.nullable) = false];
}

// InternalCommitTrigger encapsulates all of the internal-only commit triggers.
// Only one may be set.
message InternalCommitTrigger {
  // InternalCommitTrigger is always nullable, and these getters are
  // nil-safe, which is often convenient.
  option (gogoproto.goproto_getters) = true;

  optional SplitTrigger split_trigger = 1;
  optional MergeTrigger merge_trigger = 2;
  optional ChangeReplicasTrigger change_replicas_trigger = 3;
  optional ModifiedSpanTrigger modified_span_trigger = 4;
}

// IsolationType TODO(jiajia) Needs documentation.
enum IsolationType {
  option (gogoproto.goproto_enum_prefix) = false;

  // SERIALIZABLE TODO(jiajia) Needs documentation.
  SERIALIZABLE = 0;
  // SNAPSHOT TODO(jiajia) Needs documentation.
  SNAPSHOT = 1;
}

// TransactionStatus specifies possible states for a transaction.
enum TransactionStatus {
  option (gogoproto.goproto_enum_prefix) = false;

  // PENDING is the default state for a new transaction. Transactions
  // move from PENDING to one of COMMITTED or ABORTED. Mutations made
  // as part of a PENDING transactions are recorded as "intents" in
  // the underlying MVCC model.
  PENDING = 0;
  // COMMITTED is the state for a transaction which has been
  // committed. Mutations made as part of a transaction which is moved
  // into COMMITTED state become durable and visible to other
  // transactions, moving from "intents" to permanent versioned
  // values.
  COMMITTED = 1;
  // ABORTED is the state for a transaction which has been aborted.
  // Mutations made as part of a transaction which is moved into
  // ABORTED state are deleted and are never made visible to other
  // transactions.
  ABORTED = 2;
}

// TxnMeta is the metadata of a Transaction record.
message TxnMeta {
  option (gogoproto.populate) = true;

  // id is a unique UUID value which identifies the transaction.
  optional bytes id = 1 [(gogoproto.customname) = "ID",
      (gogoproto.customtype) = "github.com/cockroachdb/cockroach/util/uuid.UUID"];
  optional IsolationType isolation = 2 [(gogoproto.nullable) = false];
  // key is the key which anchors the transaction. This is typically
  // the first key read or written during the transaction and determines which
  // range in the cluster will hold the transaction record.
  optional bytes key = 3 [(gogoproto.casttype) = "Key"];
  // Incremented on txn retry.
  optional uint32 epoch = 4 [(gogoproto.nullable) = false];
  // The proposed timestamp for the transaction. This starts as
  // the current wall time on the txn coordinator.
  optional Timestamp timestamp = 5 [(gogoproto.nullable) = false];
  optional int32 priority = 6 [(gogoproto.nullable) = false];
  // A one-indexed sequence number which is increased on each batch
  // sent as part of the transaction. Used to prevent replay and
  // out-of-order application protection (by means of a transaction
  // retry).
  optional int32 sequence = 7 [(gogoproto.nullable) = false];
  // A zero-indexed sequence number indicating the index of a
  // command within a batch. This disambiguate Raft replays of a batch
  // from multiple commands in a batch which modify the same key.
  optional int32 batch_index = 8 [(gogoproto.nullable) = false];
}

// A Transaction is a unit of work performed on the database.
// Cockroach transactions support two isolation levels: snapshot
// isolation and serializable snapshot isolation. Each Cockroach
// transaction is assigned a random priority. This priority will be
// used to decide whether a transaction will be aborted during
// contention.
//
// If you add fields to Transaction you'll need to update
// Transaction.Clone. Failure to do so will result in test failures.
message Transaction {
  option (gogoproto.goproto_stringer) = false;
  option (gogoproto.populate) = true;

  // The transaction metadata. These are persisted with every intent.
  optional TxnMeta meta = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // A free-text identifier for debug purposes.
  optional string name = 2 [(gogoproto.nullable) = false];
  optional TransactionStatus status = 4 [(gogoproto.nullable) = false];
  // The last heartbeat timestamp.
  optional Timestamp last_heartbeat = 5;
  // The original timestamp at which the transaction started. For serializable
  // transactions, if the timestamp drifts from the original timestamp, the
  // transaction will retry.
  optional Timestamp orig_timestamp = 6 [(gogoproto.nullable) = false];
  // Initial Timestamp + clock skew. Reads which encounter values with
  // timestamps between timestamp and max_timestamp trigger a txn
  // retry error, unless the node being read is listed in observed_timestamps
  // (in which case no more read uncertainty can occur).
  // The case max_timestamp < timestamp is possible for transactions which have
  // been pushed; in this case, max_timestamp should be ignored.
  optional Timestamp max_timestamp = 7 [(gogoproto.nullable) = false];
  // A map of NodeID to timestamps as observed from their local clock during
  // this transaction. The purpose of this map is to avoid uncertainty related
  // restarts which normally occur when reading a value in the near future as
  // per the max_timestamp field.
  // When this map holds a corresponding entry for the node the current request
  // is executing on, we can run the command with the map's timestamp as the
  // top boundary of our uncertainty interval, limiting (and often avoiding)
  // uncertainty restarts.
  map<int32, Timestamp> observed_timestamps = 8 [(gogoproto.nullable) = false, (gogoproto.castkey) = "NodeID"];
  // Writing is true if the transaction has previously executed a successful
  // write request, i.e. a request that may have left intents (across retries).
  optional bool writing = 9 [(gogoproto.nullable) = false];
  // If this is true, the transaction must retry. Relevant only for
  // SNAPSHOT transactions: a SERIALIZABLE transaction would have to
  // retry anyway due to its commit timestamp having moved forward.
  // This bool is set instead of immediately returning a txn retry
  // error so that intents can continue to be laid down, minimizing
  // work required on txn restart.
  optional bool write_too_old = 12 [(gogoproto.nullable) = false];
  // If retry_on_push is true, the transaction must retry in the event
  // that the commit timestamp is pushed forward. This flag is set if
  // the transaction contains any calls to DeleteRange, in order to
  // prevent the LostDeleteRange anomaly. This flag is relevant only
  // for SNAPSHOT transactions.
  optional bool retry_on_push = 13 [(gogoproto.nullable) = false];
  repeated Span intents = 11 [(gogoproto.nullable) = false];
}

// A Intent is a Span together with a Transaction metadata and its status.
message Intent {
  optional Span span = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  optional TxnMeta txn = 2 [(gogoproto.nullable) = false];
  optional TransactionStatus status = 3 [(gogoproto.nullable) = false];
}

// Lease contains information about leader leases including the
// expiration and lease holder. It defines the two intervals
// [start, start_stasis) and [start_stasis, expiration). The
// former encompasses those timestamps for which the lease is
// active, while the latter is a cooldown period which avoids
// inconsistencies during leadership changes as explained below.
message Lease {
  option (gogoproto.goproto_stringer) = false;
  option (gogoproto.populate) = true;

  // The start is a timestamp at which the lease begins. This value
  // must be greater than the last lease expiration or the lease request
  // is considered invalid.
  optional Timestamp start = 1 [(gogoproto.nullable) = false];
  // Before the lease expires, it enters a "stasis period" the length of which
  // is usually determined by the lease holder's maximum allowed clock offset.
  // During this stasis period, the lease must not be used (but can be extended
  // by the owner instead). This prevents a failure of linearizability on a
  // single register during lease changes. Without that stasis period, the
  // following could occur:
  // * a leader lease gets committed on the new leader (but not the old).
  // * client proposes and commits a write on new leader (with a timestamp
  //   just greater than the expiration of the old lease).
  // * client tries to read what it wrote, but hits a slow coordinator
  //   (which assigns a timestamp covered by the old lease).
  // * the read is served by the old leader (which has not processed the
  //   change in leadership).
  // * the client fails to read their own write.
  //
  // Instead, the old leader must refuse to serve the client's command on the
  // basis that its timestamp falls within the stasis period.
  optional Timestamp start_stasis = 4 [(gogoproto.nullable) = false];

  // The expiration is a timestamp at which the lease expires. This means that
  // a new lease can be granted for a later timestamp.
  optional Timestamp expiration = 2 [(gogoproto.nullable) = false];

  // The address of the would-be lease holder.
  optional ReplicaDescriptor replica = 3 [(gogoproto.nullable) = false];
}

// AbortCacheEntry contains information about a transaction which has
// been aborted. It's written to a range's abort cache if the range
// may have contained intents of the aborted txn. In the event that
// the same transaction attempts to read keys it may have written
// previously, this entry informs the transaction that it has aborted
// and must start fresh with an updated priority.
message AbortCacheEntry {
  option (gogoproto.populate) = true;

  // The key of the associated transaction.
  optional bytes key = 1 [(gogoproto.casttype) = "Key"];
  // The candidate commit timestamp the transaction record held at the time
  // it was aborted.
  optional Timestamp timestamp = 2 [(gogoproto.nullable) = false];
  // The priority of the transaction.
  optional int32 priority = 3 [(gogoproto.nullable) = false];
}