structured.proto

// Copyright 2015 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

// Cannot be proto3 because we use nullable primitives.
syntax = "proto2";
package cockroach.sql.sqlbase;
option go_package = "sqlbase";

import "util/hlc/timestamp.proto";
import "sql/sqlbase/privilege.proto";
import "gogoproto/gogo.proto";

enum ConstraintValidity {
  // The constraint is valid for all rows.
  Validated = 0;
  // The constraint has not yet been validated for all rows (and will not be
  // validated until VALIDATE CONSTRAINT is used).
  Unvalidated = 1;
  // The constraint was just added, but the validation for existing rows is not
  // yet complete. If validation fails, the constraint will be dropped.
  Validating = 2;
  // The constraint is being dropped in the schema changer.
  Dropping = 3;
}

message ForeignKeyReference {
  option (gogoproto.equal) = true;
  enum Action {
    option (gogoproto.goproto_enum_stringer) = false;
    NO_ACTION = 0;
    RESTRICT = 1;
    SET_NULL = 2;
    SET_DEFAULT = 3;
    CASCADE = 4;
  }

  // Match is the algorithm used to compare composite keys.
  enum Match {
    option (gogoproto.goproto_enum_stringer) = false;
    SIMPLE = 0;
    FULL = 1;
    PARTIAL = 2; // Note: not actually supported, but we reserve the value for future use.
  }

  optional uint32 table = 1 [(gogoproto.nullable) = false, (gogoproto.casttype) = "ID"];
  optional uint32 index = 2 [(gogoproto.nullable) = false, (gogoproto.casttype) = "IndexID"];
  optional string name = 3 [(gogoproto.nullable) = false];
  optional ConstraintValidity validity = 4 [(gogoproto.nullable) = false];
  // If this FK only uses a prefix of the columns in its index, we record how
  // many to avoid spuriously counting the additional cols as used by this FK.
  optional int32 shared_prefix_len = 5 [(gogoproto.nullable) = false];
  optional Action on_delete = 6 [(gogoproto.nullable) = false];
  optional Action on_update = 7 [(gogoproto.nullable) = false];
  // This is only important for composite keys. For all prior matches before
  // the addition of this value, MATCH SIMPLE will be used.
  optional Match match = 8 [(gogoproto.nullable) = false];
}

// ForeignKeyConstraint is the new (as of 19.2 and VersionTopLevelForeignKeys)
// representation for foreign keys. It's stored on the TableDescriptor and is
// designed to be agnostic to which indexes are available on both the origin
// and referenced tables, so that the optimizer can have full freedom to choose
// the best possible index to satisfy constraint checks at runtime.
message ForeignKeyConstraint {
  option (gogoproto.equal) = true;
  optional uint32 origin_table_id = 1 [(gogoproto.nullable) = false,
                                      (gogoproto.customname) = "OriginTableID",
                                      (gogoproto.casttype) = "ID"];
  repeated uint32 origin_column_ids = 2 [(gogoproto.customname) = "OriginColumnIDs",
                                        (gogoproto.casttype) = "ColumnID"];
  repeated uint32 referenced_column_ids = 3 [(gogoproto.customname) = "ReferencedColumnIDs",
                                            (gogoproto.casttype) = "ColumnID"];
  optional uint32 referenced_table_id = 4 [(gogoproto.nullable) = false,
                                          (gogoproto.customname) = "ReferencedTableID",
                                          (gogoproto.casttype) = "ID"];
  optional string name = 5 [(gogoproto.nullable) = false];
  optional ConstraintValidity validity = 6 [(gogoproto.nullable) = false];
  optional ForeignKeyReference.Action on_delete = 7 [(gogoproto.nullable) = false];
  optional ForeignKeyReference.Action on_update = 8 [(gogoproto.nullable) = false];
  // This is only important for composite keys. For all prior matches before
  // the addition of this value, MATCH SIMPLE will be used.
  optional ForeignKeyReference.Match match = 9 [(gogoproto.nullable) = false];

  // LegacyOriginIndex is the ID of the index used for the FK on the origin
  // table. In versions 19.1 and earlier, foreign keys were represented by
  // fields on the index that they use. In versions 19.2 and later, we preserve
  // the semantics of the older FKs which were tied to indexes by specifying
  // the index as a field on this proto, since the migration process to have
  // top-level FK fields on the table descriptor requires two releases.
  // In 20.1, these fields are no longer read, but must continue to be written
  // to maintain compatibility in mixed 19.2/20.1 clusters. In 20.2 these fields
  // can _finally_ be removed.
  // * When using the foreign key constraint, do not read from these fields! *
  optional uint32 legacy_origin_index = 10
    [(gogoproto.nullable) = false, (gogoproto.casttype) = "IndexID", deprecated = true];
  // LegacyReferencedIndex is the ID of the index used for the FK on the
  // referenced side. See the comment for LegacyOriginIndex.
  optional uint32 legacy_referenced_index = 11
    [(gogoproto.nullable) = false, (gogoproto.casttype) = "IndexID", deprecated = true];
  // These fields were used for the 19.1 -> 19.2 foreign key migration.
  reserved 12, 13;
}

message ColumnDescriptor {
  option (gogoproto.equal) = true;
  optional string name = 1 [(gogoproto.nullable) = false];
  optional uint32 id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ID", (gogoproto.casttype) = "ColumnID"];
  optional bytes type = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/sql/types.T"];
  optional bool nullable = 4 [(gogoproto.nullable) = false];
  reserved 8;
  // Default expression to use to populate the column on insert if no
  // value is provided.
  optional string default_expr = 5;
  reserved 9;
  optional bool hidden = 6 [(gogoproto.nullable) = false];
  reserved 7;
  // Ids of sequences used in this column's DEFAULT expression, in calls to nextval().
  repeated uint32 uses_sequence_ids = 10 [(gogoproto.casttype) = "ID"];
  // Ids of sequences that the column owns.
  repeated uint32 owns_sequence_ids = 12 [(gogoproto.casttype) = "ID"];
  // Expression to use to compute the value of this column if this is a
  // computed column.
  optional string compute_expr = 11;
  // LogicalColumnID is used to order columns visually. This is because
  // ordinal_position in information_schema determines a table's visual column
  // ordering to the user.
  // This only differs from ID when the Column order is swapped or
  // the ColumnDescriptor must be remade while remaining visual ordering.
  // This does not exist in TableDescriptors pre 20.2.
  optional uint32 logical_id = 13 [(gogoproto.nullable) = false,
   (gogoproto.customname) = "LogicalColumnID", (gogoproto.casttype) = "ColumnID"];
}

// ColumnFamilyDescriptor is set of columns stored together in one kv entry.
// For more information, look at `docs/tech-notes/encoding.md#value-encoding`.
message ColumnFamilyDescriptor {
  option (gogoproto.equal) = true;
  optional string name = 1 [(gogoproto.nullable) = false];
  // Column family 0 is *always* included in k/v pairs for a row. This makes
  // sure that rows will all NULL values still have a k/v pair. When performing
  // optimizations involving column families, ensure that column family 0
  // is scanned if the row may have nulls.
  optional uint32 id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ID", (gogoproto.casttype) = "FamilyID"];

  // A list of column names of which the family is comprised. This list
  // parallels the column_ids list. If duplicating the storage of the column
  // names here proves to be prohibitive, we could clear this field before
  // saving and reconstruct it after loading.
  repeated string column_names = 3;
  // A list of column ids of which the family is comprised. This list parallels
  // the column_names list.
  repeated uint32 column_ids = 4 [(gogoproto.customname) = "ColumnIDs",
      (gogoproto.casttype) = "ColumnID"];

  // If nonzero, the column involved in the single column optimization.
  //
  // Families store columns in a ValueType_TUPLE as repeated <columnID><data>
  // entries. As a space optimization and for backward compatibility, a single
  // column is written without the column id prefix. Because more columns could
  // be added, it would be ambiguous which column was stored when read back in,
  // so this field supplies it.
  optional uint32 default_column_id = 5 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "DefaultColumnID", (gogoproto.casttype) = "ColumnID"];
}

// InterleaveDescriptor represents an index (either primary or secondary) that
// is interleaved into another table's data.
//
// Example:
// Table 1 -> /a/b
// Table 2 -> /a/b/c
// Table 3 -> /a/b/c/d
//
// There are two components (table 2 is the parent and table 1 is the
// grandparent) with shared lengths 2 and 1.
message InterleaveDescriptor {
  option (gogoproto.equal) = true;
  message Ancestor {
    option (gogoproto.equal) = true;
    // TableID is the ID of the table being interleaved into.
    optional uint32 table_id = 1 [(gogoproto.nullable) = false,
        (gogoproto.customname) = "TableID", (gogoproto.casttype) = "ID"];
    // IndexID is the ID of the parent index being interleaved into.
    optional uint32 index_id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "IndexID", (gogoproto.casttype) = "IndexID"];
    // SharedPrefixLen is how many fields are shared between a parent and child
    // being interleaved, excluding any fields shared between parent and
    // grandparent. Thus, the sum of SharedPrefixLens in the components of an
    // InterleaveDescriptor is never more than the number of fields in the index
    // being interleaved.
    // In cockroach 1.0, this value did not exist and thus a check for > 0
    // must be performed prior to its use.
    optional uint32 shared_prefix_len = 3 [(gogoproto.nullable) = false,
        (gogoproto.customname) = "SharedPrefixLen"];
  }

  // Ancestors contains the nesting of interleaves in the order they appear in
  // an encoded key. This means they are always in the far-to-near ancestor
  // order (e.g. grand-grand-parent, grand-parent, parent).
  repeated Ancestor ancestors = 1 [(gogoproto.nullable) = false];
}

// ShardedDescriptor represents an index (either primary or secondary) that is hash
// sharded into a user-specified number of buckets.
//
// As as example, sample field values for the following table:
//
// CREATE TABLE abc (
//   a INT PRIMARY KEY USING HASH WITH BUCKET_COUNT=10,  // column id: 1 
//   b BYTES
// );
//
// Sharded descriptor:
//   name:          "a_shard"
//   shard_buckets: 10
//   column_names:  ["a"]
message ShardedDescriptor {
  option (gogoproto.equal) = true;
  
  // IsSharded indicates whether the index in question is a sharded one.
  optional bool is_sharded = 1 [(gogoproto.nullable) = false]; 
  // Name is the name of the shard column.
  optional string name = 2 [(gogoproto.nullable) = false];

  // ShardBuckets indicates the number of shards this index is divided into.
  optional int32 shard_buckets = 3 [(gogoproto.nullable) = false,
    (gogoproto.customname) = "ShardBuckets"];

  // ColumnNames lists the names of the columns used to compute the shard column's
  // values.
  repeated string column_names = 4;
}

// PartitioningDescriptor represents the partitioning of an index into spans
// of keys addressable by a zone config. The key encoding is unchanged. Each
// partition may optionally be itself divided into further partitions, called
// subpartitions.
message PartitioningDescriptor {
  option (gogoproto.equal) = true;
  // List represents a list partitioning, which maps individual tuples to
  // partitions.
  message List {
    option (gogoproto.equal) = true;
    // Name is the partition name.
    optional string name = 1 [(gogoproto.nullable) = false];
    // Values is an unordered set of the tuples included in this partition. Each
    // tuple is encoded with the EncDatum value encoding. DEFAULT is encoded as
    // NOT NULL followed by PartitionDefaultVal encoded as a non-sorting
    // uvarint.
    repeated bytes values = 2;
    // Subpartitioning represents a further partitioning of this list partition.
    optional PartitioningDescriptor subpartitioning = 3 [(gogoproto.nullable) = false];
  }

  // Range represents a range partitioning, which maps ranges of tuples to
  // partitions by specifying exclusive upper bounds. The range partitions in a
  // PartitioningDescriptor are required to be sorted by UpperBound.
  message Range {
    option (gogoproto.equal) = true;
    // Name is the partition name.
    optional string name = 1 [(gogoproto.nullable) = false];
    // FromInclusive is the inclusive lower bound of this range partition. It is
    // encoded with the EncDatum value encoding. MINVALUE and MAXVALUE are
    // encoded as NOT NULL followed by a PartitionSpecialValCode encoded as a
    // non-sorting uvarint.
    optional bytes from_inclusive = 3;
    // ToExclusive is the exclusive upper bound of this range partition. It is
    // encoded in the same way as From.
    optional bytes to_exclusive = 2;
  }

  // NumColumns is how large of a prefix of the columns in an index are used in
  // the function mapping column values to partitions. If this is a
  // subpartition, this is offset to start from the end of the parent
  // partition's columns. If NumColumns is 0, then there is no partitioning.
  optional uint32 num_columns = 1 [(gogoproto.nullable) = false];

  // Exactly one of List or Range is required to be non-empty if NumColumns is
  // non-zero.
  repeated List list = 2 [(gogoproto.nullable) = false];
  repeated Range range = 3 [(gogoproto.nullable) = false];
}

// IndexDescriptor describes an index (primary or secondary).
//
// Sample field values on the following table:
//
//   CREATE TABLE t (
//     k1 INT NOT NULL,   // column ID: 1
//     k2 INT NOT NULL,   // column ID: 2
//     u INT NULL,        // column ID: 3
//     v INT NULL,        // column ID: 4
//     w INT NULL,        // column ID: 5
//     CONSTRAINT "primary" PRIMARY KEY (k1, k2),
//     INDEX k1v (k1, v) STORING (w),
//     FAMILY "primary" (k1, k2, u, v, w)
//   )
//
// Primary index:
//   name:                primary
//   id:                  1
//   unique:              true
//   column_names:        k1, k2
//   column_directions:   ASC, ASC
//   column_ids:          1, 2   // k1, k2
//
// [old STORING encoding] Index k1v (k1, v) STORING (w):
//   name:                k1v
//   id:                  2
//   unique:              false
//   column_names:        k1, v
//   column_directions:   ASC, ASC
//   store_column_names:  w
//   column_ids:          1, 4   // k1, v
//   extra_column_ids:    2, 5   // k2, w
//
// [new STORING encoding] Index k1v (k1, v) STORING (w):
//   name:                k1v
//   id:                  2
//   unique:              false
//   column_names:        k1, v
//   column_directions:   ASC, ASC
//   store_column_names:  w
//   column_ids:          1, 4   // k1, v
//   extra_column_ids:    2      // k2
//   store_column_ids:    5      // w
message IndexDescriptor {
  option (gogoproto.equal) = true;
  // The direction of a column in the index.
  enum Direction {
    ASC = 0;
    DESC = 1;
  }

  // The type of the index.
  enum Type {
    FORWARD = 0;
    INVERTED = 1;
  }

  optional string name = 1 [(gogoproto.nullable) = false];
  optional uint32 id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ID", (gogoproto.casttype) = "IndexID"];
  optional bool unique = 3 [(gogoproto.nullable) = false];

  optional uint32 version = 18 [(gogoproto.nullable) = false, (gogoproto.casttype) = "IndexDescriptorVersion"];

  // An ordered list of column names of which the index is comprised; these
  // columns do not include any additional stored columns (which are in
  // stored_column_names). This list parallels the column_ids list.
  //
  // Note: if duplicating the storage of the column names here proves to be
  // prohibitive, we could clear this field before saving and reconstruct it
  // after loading.
  repeated string column_names = 4;

  // The sort direction of each column in column_names.
  repeated Direction column_directions = 8;

  // An ordered list of column names which the index stores in addition to the
  // columns which are explicitly part of the index (STORING clause). Only used
  // for secondary indexes.
  repeated string store_column_names = 5;

  // An ordered list of column IDs of which the index is comprised. This list
  // parallels the column_names list and does not include any additional stored
  // columns.
  repeated uint32 column_ids = 6 [(gogoproto.customname) = "ColumnIDs",
      (gogoproto.casttype) = "ColumnID"];

  // An ordered list of IDs for the additional columns associated with the
  // index:
  //  - implicit columns, which are all the primary key columns that are not
  //    already part of the index (i.e. PrimaryIndex.column_ids - column_ids).
  //  - stored columns (the columns in store_column_names) if this index uses the
  //    old STORING encoding (key-encoded data).
  //
  // Only used for secondary indexes.
  // For non-unique indexes, these columns are appended to the key.
  // For unique indexes, these columns are stored in the value (unless the key
  // contains a NULL value: then the extra columns are appended to the key to
  // unique-ify it).
  // This distinction exists because we want to be able to insert an entry using
  // a single conditional put on the key.
  repeated uint32 extra_column_ids = 7 [(gogoproto.customname) = "ExtraColumnIDs",
      (gogoproto.casttype) = "ColumnID"];

  // An ordered list of column IDs that parallels store_column_names if this
  // index uses the new STORING encoding (value-encoded data, always in the KV
  // value).
  repeated uint32 store_column_ids = 14
      [(gogoproto.customname) = "StoreColumnIDs", (gogoproto.casttype) = "ColumnID"];

  // CompositeColumnIDs contains an ordered list of IDs of columns that appear
  // in the index and have a composite encoding. Includes IDs from both
  // column_ids and extra_column_ids.
  repeated uint32 composite_column_ids = 13
      [(gogoproto.customname) = "CompositeColumnIDs", (gogoproto.casttype) = "ColumnID"];

  // ForeignKey and ReferencedBy are deprecated and not stored from 19.2 onward.
  optional ForeignKeyReference foreign_key = 9 [(gogoproto.nullable) = false, deprecated = true];
  repeated ForeignKeyReference referenced_by = 10 [(gogoproto.nullable) = false, deprecated = true];

  // Interleave, if it's not the zero value, describes how this index's data is
  // interleaved into another index's data.
  optional InterleaveDescriptor interleave = 11 [(gogoproto.nullable) = false];

  // InterleavedBy contains a reference to every table/index that is interleaved
  // into this one.
  repeated ForeignKeyReference interleaved_by = 12  [(gogoproto.nullable) = false];

  // Partitioning, if it's not the zero value, describes how this index's data
  // is partitioned into spans of keys each addressable by zone configs.
  optional PartitioningDescriptor partitioning = 15 [(gogoproto.nullable) = false];

  // Type is the type of index, inverted or forward.
  optional Type type = 16 [(gogoproto.nullable)=false];

  // CreatedExplicitly specifies whether this index was created explicitly
  // (i.e. via 'CREATE INDEX' statement).
  optional bool created_explicitly = 17 [(gogoproto.nullable) = false];

  // EncodingType represents what sort of k/v encoding is used to store this descriptor on disk.
  // As of now, this includes the existing secondary index encoding, or the primary index encoding.
  // N.B. This field is only recognized on secondary indexes.
  optional uint32 encoding_type = 19
    [(gogoproto.nullable) = false, (gogoproto.casttype) = "IndexDescriptorEncodingType"];

  // Sharded, if it's not the zero value, describes how this index is sharded.
  optional ShardedDescriptor sharded = 20 [(gogoproto.nullable) = false];

  // Disabled is used by the DROP PRIMARY KEY command to mark
  // that this index is disabled for further use.
  optional bool disabled = 21 [(gogoproto.nullable) = false];
}

// ConstraintToUpdate represents a constraint to be added to the table and
// validated for existing rows. More generally, in the future, when we support
// adding constraints that are unvalidated for existing rows and can be
// validated later using VALIDATE CONSTRAINT, this mutation will also represent
// either adding an unvalidated constraint or validating an existing constraint.
//
// This mutation effects changes only in the backfill step of the schema
// changer: First, a new version of the table descriptor with the constraint
// added is published, after all columns being added have been backfilled. After
// waiting for the constraint to be enforced for writes on all nodes, the
// constraint is then validated for all existing rows. This ensures that
// constraints added to columns that are being added are correctly enforced
// before the column becomes public.
message ConstraintToUpdate {
  option (gogoproto.equal) = true;
  enum ConstraintType {
    CHECK = 0;
    FOREIGN_KEY = 1;
    // NOT NULL constraints being added are represented by a dummy check
    // constraint so that a multi-state schema change, including a bulk
    // validation step, can occur. The check field contains the dummy
    // constraint.
    NOT_NULL = 2;
  }
  required ConstraintType constraint_type = 1 [(gogoproto.nullable) = false];
  required string name = 2 [(gogoproto.nullable) = false];
  optional TableDescriptor.CheckConstraint check = 3 [(gogoproto.nullable) = false];
  // All fields past 3 haven't been persisted before 19.2.
  optional ForeignKeyConstraint foreign_key = 4 [(gogoproto.nullable) = false];
  reserved 5;
  optional uint32 not_null_column = 6 [(gogoproto.nullable) = false, (gogoproto.casttype) = "ColumnID"];
}

// PrimaryKeySwap is a mutation corresponding to the atomic swap phase
// during a primary key change where old versions of indexes are exchanged for
// updated versions, and the table's new primary key is written into the descriptor.
message PrimaryKeySwap {
  option (gogoproto.equal) = true;
  // old_primary_index_id is the ID of the old primary index for the table.
  optional uint32 old_primary_index_id = 4 [(gogoproto.nullable) = false, (gogoproto.casttype) = "IndexID"];
  // new_primary_index_id is the ID of the new primary index for the table.
  optional uint32 new_primary_index_id = 1 [(gogoproto.nullable) = false, (gogoproto.casttype) = "IndexID"];
  // old_indexes and new_indexes are lists of IndexID's where the i'th index in old_indexes will be
  // swapped out with the i'th index in new_indexes.
  repeated uint32 old_indexes = 2 [(gogoproto.casttype) = "IndexID"];
  repeated uint32 new_indexes = 3 [(gogoproto.casttype) = "IndexID"];
}

// A DescriptorMutation represents a column or an index that
// has either been added or dropped and hasn't yet transitioned
// into a stable state: completely backfilled and visible, or
// completely deleted. A table descriptor in the middle of a
// schema change will have a DescriptorMutation FIFO queue
// containing each column/index descriptor being added or dropped.
// Mutations for constraints work differently from columns and
// indexes; see the documentation for ConstraintToUpdate.
message DescriptorMutation {
  option (gogoproto.equal) = true;
  oneof descriptor {
    ColumnDescriptor column = 1;
    IndexDescriptor index = 2;
    ConstraintToUpdate constraint = 8;
    PrimaryKeySwap primaryKeySwap = 9;
  }
  // A descriptor within a mutation is unavailable for reads, writes
  // and deletes. It is only available for implicit (internal to
  // the database) writes and deletes depending on the state of the mutation.
  enum State {
    // Not used.
    UNKNOWN = 0;
    // Operations can use this invisible descriptor to implicitly
    // delete entries.
    // Column: A descriptor in this state is invisible to
    // INSERT and UPDATE. DELETE must delete a column in this state.
    // Index: A descriptor in this state is invisible to an INSERT.
    // UPDATE must delete the old value of the index but doesn't write
    // the new value. DELETE must delete the index.
    //
    // When deleting a descriptor, all descriptor related data
    // (column or index data) can only be mass deleted once
    // all the nodes have transitioned to the DELETE_ONLY state.
    DELETE_ONLY = 1;
    // Operations can use this invisible descriptor to implicitly
    // write and delete entries.
    // Column: INSERT will populate this column with the default
    // value. UPDATE ignores this descriptor. DELETE must delete
    // the column.
    // Index: INSERT, UPDATE and DELETE treat this index like any
    // other index.
    //
    // When adding a descriptor, all descriptor related data
    // (column default or index data) can only be backfilled once
    // all nodes have transitioned into the DELETE_AND_WRITE_ONLY state.
    DELETE_AND_WRITE_ONLY = 2;
  }
  optional State state = 3 [(gogoproto.nullable) = false];

  // Direction of mutation.
  enum Direction {
    // Not used.
    NONE = 0;
    // Descriptor is being added.
    ADD = 1;
    // Descriptor is being dropped.
    DROP = 2;
  }
  optional Direction direction = 4 [(gogoproto.nullable) = false];

  // The mutation id used to group mutations that should be applied together.
  // This is used for situations like creating a unique column, which
  // involve adding two mutations: one for the column, and another for the
  // unique constraint index.
  optional uint32 mutation_id = 5 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "MutationID", (gogoproto.casttype) = "MutationID"];
  reserved 6;

  // Indicates that this mutation is a rollback.
  optional bool rollback = 7 [(gogoproto.nullable) = false];
}

// A TableDescriptor represents a table or view and is stored in a
// structured metadata key. The TableDescriptor has a globally-unique ID,
// while its member {Column,Index}Descriptors have locally-unique IDs.
message TableDescriptor {
  option (gogoproto.equal) = true;
  // Needed for the descriptorProto interface.
  option (gogoproto.goproto_getters) = true;

  // The table name. It should be normalized using NormalizeName() before
  // comparing it.
  optional string name = 1 [(gogoproto.nullable) = false];
  optional uint32 id = 3 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];
  // ID of the parent database.
  optional uint32 parent_id = 4 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ParentID", (gogoproto.casttype) = "ID"];
  // ID of the parent schema. For backwards compatibility, 0 means the table is
  // scoped under the public physical schema (id 29). Because of this backward
  // compatibility issue, this field should not be accessed directly or through
  // the generated getter. Instead, use GetParentSchemaID() which is defined in
  // structured.go.
  optional uint32 unexposed_parent_schema_id = 40 [(gogoproto.nullable) = false,
        (gogoproto.customname) = "UnexposedParentSchemaID", (gogoproto.casttype) = "ID"];
  // Monotonically increasing version of the table descriptor.
  //
  // The design maintains two invariants:
  // 1. Two safe versions: A transaction at a particular timestamp is
  //    allowed to use one of two versions of a table descriptor:
  //    the one that would be read from the store at that timestamp,
  //    and the one behind it in version.
  // 2. Two leased versions: There can be valid leases on at most the 2
  //    latest versions of a table in the cluster at any time. New leases
  //    are only granted on the latest version.
  //
  // The database must maintain correctness in light of there being two
  // versions of a descriptor that can be used.
  //
  // Multiple schema change mutations can be grouped together on a
  // particular version increment.
  optional uint32 version = 5 [(gogoproto.nullable) = false, (gogoproto.casttype) = "DescriptorVersion"];

  reserved 6;

  // Last modification time of the table descriptor.
  // Starting in 19.2 this field's value may sometime be zero-valued in which
  // case the MVCC timestamp of the row containing the value should be used to
  // populate it. This dance allows us to avoid observing the commit timestamp
  // for transactions which increment the descriptor version.
  // Encoded TableDescriptor structs should not be stored directly but rather
  // should live inside of a Descriptor. The Descriptor.Table() method takes an
  // hlc timestamp to ensure that this field is set properly when extracted from
  // a Descriptor.
  optional util.hlc.Timestamp modification_time = 7 [(gogoproto.nullable) = false];
  repeated ColumnDescriptor columns = 8 [(gogoproto.nullable) = false];
  // next_column_id is used to ensure that deleted column ids are not reused.
  optional uint32 next_column_id = 9 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "NextColumnID", (gogoproto.casttype) = "ColumnID"];
  // families holds information about the column families of this table.
  // This list has at least length 1, in which case all columns are stored in the same family.
  // families is stored in sorted order by family ID.
  repeated ColumnFamilyDescriptor families = 22 [(gogoproto.nullable) = false];
  // next_family_id is used to ensure that deleted family ids are not reused.
  optional uint32 next_family_id = 23 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "NextFamilyID", (gogoproto.casttype) = "FamilyID"];
  optional IndexDescriptor primary_index = 10 [(gogoproto.nullable) = false];
  // indexes are all the secondary indexes.
  repeated IndexDescriptor indexes = 11 [(gogoproto.nullable) = false];
  // next_index_id is used to ensure that deleted index ids are not reused.
  optional uint32 next_index_id = 12 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "NextIndexID", (gogoproto.casttype) = "IndexID"];
  optional PrivilegeDescriptor privileges = 13;
  // Columns or indexes being added or deleted in a FIFO order.
  repeated DescriptorMutation mutations = 14 [(gogoproto.nullable) = false];
  // The schema update lease. A single goroutine across a cockroach cluster
  // can own it, and will execute pending schema changes for this table.
  // Since the execution of a pending schema change is through transactions,
  // it is legal for more than one goroutine to attempt to execute it. This
  // lease reduces write contention on the schema change.
  message SchemaChangeLease {
    option (gogoproto.equal) = true;
    optional uint32 node_id = 1 [(gogoproto.nullable) = false,
        (gogoproto.customname) = "NodeID",
        (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];
    // Nanoseconds since the Unix epoch.
    optional int64 expiration_time = 2 [(gogoproto.nullable) = false];
  }
  optional SchemaChangeLease lease = 15 [deprecated = true];
  // An id for the next group of mutations to be applied together.
  optional uint32 next_mutation_id = 16 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "NextMutationID", (gogoproto.casttype) = "MutationID"];

  // format_version declares which sql to key:value mapping is being used to
  // represent the data in this table.
  optional uint32 format_version = 17 [(gogoproto.nullable) = false,
      (gogoproto.casttype) = "FormatVersion"];

  reserved 18;

  // State is set if this TableDescriptor is in the process of being added or deleted.
  // A non-public table descriptor cannot be leased.
  // A schema changer observing DROP set will truncate the table and delete the
  // descriptor.
  // It is illegal to transition DROP to any other state.
  enum State {
    // Not used.
    PUBLIC = 0;
    // Descriptor is being added.
    ADD = 1;
    // Descriptor is being dropped.
    DROP = 2;
    // Descriptor is offline (e.g. for bulk-ingestion). See offline_reason.
    OFFLINE = 3;
  }
  optional State state = 19 [(gogoproto.nullable) = false];
  optional string offline_reason = 38 [(gogoproto.nullable) = false];

  message CheckConstraint {
    option (gogoproto.equal) = true;
    optional string expr = 1 [(gogoproto.nullable) = false];
    optional string name = 2 [(gogoproto.nullable) = false];
    optional ConstraintValidity validity = 3 [(gogoproto.nullable) = false];
    reserved 4;
    // An ordered list of column IDs used by the check constraint.
    repeated uint32 column_ids = 5 [(gogoproto.customname) = "ColumnIDs",
      (gogoproto.casttype) = "ColumnID"];
    optional bool is_non_null_constraint = 6 [(gogoproto.nullable) = false];
    // Whether the check constraint should show up in the result of a `SHOW CREATE
    // TABLE..` statement.
    optional bool hidden = 7 [(gogoproto.nullable) = false];
  }

  repeated CheckConstraint checks = 20;

  // A table descriptor is named through a name map stored in the
  // system.namespace table: a map from {parent_id, table_name} -> id.
  // This name map can be cached for performance on a node in the cluster
  // making reassigning a name complicated. In particular, since a
  // name cannot be withdrawn across a cluster in a transaction at
  // timestamp T, we have to worry about the following:
  //
  // 1. A table is dropped at T, and the name and descriptor are still
  // cached and used by transactions at timestamps >= T.
  // 2. A table is renamed from foo to bar at T, and both names foo and bar
  // can be used by transactions at timestamps >= T.
  // 3. A name foo is reassigned from one table to another at T, and the name
  // foo can reference two different tables at timestamps >= T.
  //
  // The system ensures that a name can be resolved only to a single
  // descriptor at a timestamp thereby permitting 1 and 2, but not 3
  // (the name references two tables).
  //
  // The transaction at T is followed by a time period when names no longer
  // a part of the namespace are drained from the system. Once the old name
  // is drained from the system another transaction at timestamp S is
  // executed to release the name for future use. The interval from T to S
  // is called the name drain interval: If the T transaction is removing
  // the name foo then, at timestamps above S, foo can no longer be resolved.
  //
  // Consider a transaction at T in which name B is dropped, a new name C is
  // created. Name C is viable as soon as the transaction commits.
  // When the transaction at S commits, the name B is released for reuse.
  //
  // The transaction at S runs through the schema changer, with the system
  // returning a response to the client initiating transaction T only after
  // transaction at S is committed. So effectively the SQL transaction once
  // it returns can be followed by SQL transactions that do not observe
  // old name mappings.
  //
  // Note: an exception to this is #19925 which needs to be fixed.
  //
  // In order for transaction at S to act properly the system.namespace
  // table entry for an old name references the descriptor who was the
  // prior owner of the name requiring draining.
  //
  // Before T:   B -> Desc B
  //
  // After T and before S: B -> Desc B, C -> Desc C
  //
  // After S: C -> Desc C
  //
  // Between T and S the name B is drained and the system is unable
  // to assign it to another descriptor.
  //
  // BEGIN;
  // RENAME foo TO bar;
  // CREATE foo;
  //
  // will fail because CREATE foo is executed at T.
  //
  // RENAME foo TO bar;
  // CREATE foo;
  //
  // will succeed because the RENAME returns after S and CREATE foo is
  // executed after S.
  //
  // The above scheme suffers from the problem that a transaction can observe
  // the partial effect of a committed transaction during the drain interval.
  // For instance during the drain interval a transaction can see the correct
  // assignment for C, and the old assignments for B.
  //
  message NameInfo {
    option (gogoproto.equal) = true;
    // The database that the table belonged to before the rename (tables can be
    // renamed from one db to another).
    optional uint32 parent_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ParentID", (gogoproto.casttype) = "ID"];
    // The schemaID of the schema the table belongs to before the rename/drop.
    // Required to correctly identify which namespace entry to reclaim.
    optional uint32 parent_schema_id = 3 [(gogoproto.nullable) = false,
          (gogoproto.customname) = "ParentSchemaID", (gogoproto.casttype) = "ID"];
    optional string name = 2 [(gogoproto.nullable) = false];
  }

  // A list of draining names. The draining name entries are drained from
  // the cluster wide name caches by incrementing the version for this
  // descriptor and ensuring that there are no leases on prior
  // versions of the descriptor. This field is then cleared and the version
  // of the descriptor incremented.
  repeated NameInfo draining_names = 21 [(gogoproto.nullable) = false];

  // The TableDescriptor is used for views in addition to tables. Views
  // use mostly the same fields as tables, but need to track the actual
  // query from the view definition as well.
  //
  // For now we only track a string representation of the query. This prevents
  // us from easily supporting things like renames of the dependencies of a
  // view. Eventually we'll want to switch to a semantic encoding of the query
  // that relies on IDs rather than names so that we can support renames of
  // fields relied on by the query, as Postgres does.
  //
  // Note: The presence of this field is used to determine whether or not
  // a TableDescriptor represents a view.
  optional string view_query = 24 [(gogoproto.nullable) = false];

  // The IDs of all relations that this depends on.
  // Only ever populated if this descriptor is for a view.
  repeated uint32 dependsOn = 25 [(gogoproto.customname) = "DependsOn",
           (gogoproto.casttype) = "ID"];

  message Reference {
    option (gogoproto.equal) = true;
    // The ID of the relation that depends on this one.
    optional uint32 id = 1 [(gogoproto.nullable) = false,
             (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];
    // If applicable, the ID of this table's index that is referenced by the
    // dependent relation.
    optional uint32 index_id = 2 [(gogoproto.nullable) = false,
             (gogoproto.customname) = "IndexID", (gogoproto.casttype) = "IndexID"];
    // The IDs of this table's columns that are referenced by the dependent
    // relation.
    repeated uint32 column_ids = 3 [(gogoproto.customname) = "ColumnIDs",
             (gogoproto.casttype) = "ColumnID"];
  }

  // All references to this table/view from other views and sequences in the system,
  // tracked down to the column/index so that we can restrict changes to them while
  // they're still being referred to.
  repeated Reference dependedOnBy = 26 [(gogoproto.nullable) = false,
           (gogoproto.customname) = "DependedOnBy"];

  message MutationJob {
    option (gogoproto.equal) = true;
    // The mutation id of this mutation job.
    optional uint32 mutation_id = 1 [(gogoproto.nullable) = false,
             (gogoproto.customname) = "MutationID", (gogoproto.casttype) = "MutationID"];

    // The job id for a mutation job is the id in the system.jobs table of the
    // schema change job executing the mutation referenced by mutation_id.
    optional int64 job_id = 2 [(gogoproto.nullable) = false,
             (gogoproto.customname) = "JobID"];
  }

  // Mutation jobs queued for execution in a FIFO order. Remains synchronized
  // with the mutations list.
  repeated MutationJob mutationJobs = 27 [(gogoproto.nullable) = false];

  message SequenceOpts {
    option (gogoproto.equal) = true;
    // How much to increment the sequence by when nextval() is called.
    optional int64 increment = 1 [(gogoproto.nullable) = false];
    // Minimum value of the sequence.
    optional int64 min_value = 2 [(gogoproto.nullable) = false];
    // Maximum value of the sequence.
    optional int64 max_value = 3 [(gogoproto.nullable) = false];
    // Start value of the sequence.
    optional int64 start = 4 [(gogoproto.nullable) = false];
    // Whether the sequence is virtual.
    optional bool virtual = 5 [(gogoproto.nullable) = false];

    message SequenceOwner {
      option (gogoproto.equal) = true;
      // Sequence Owner's Column ID
      optional uint32 owner_column_id = 1 [(gogoproto.nullable) = false,
                                          (gogoproto.customname) = "OwnerColumnID",
                                          (gogoproto.casttype) = "ColumnID"];
      // Sequence Owner's Table ID
      optional uint32 owner_table_id = 2 [(gogoproto.nullable) = false,
                                         (gogoproto.customname) = "OwnerTableID",
                                         (gogoproto.casttype) = "ID"];
    }

    optional SequenceOwner sequence_owner = 6 [(gogoproto.nullable) = false];
  }

  // The presence of sequence_opts indicates that this descriptor is for a sequence.
  optional SequenceOpts sequence_opts = 28;

  // The drop time is set when a table is truncated or dropped,
  // based on the current time in nanoseconds since the epoch.
  // Use this timestamp + GC TTL to start deleting the table's
  // contents.
  //
  // TODO(vivek): Replace with the ModificationTime. This has been
  // added only for migration purposes.
  optional int64 drop_time = 29 [(gogoproto.nullable) = false];

  message Replacement {
    option (gogoproto.equal) = true;
    optional uint32 id = 1 [(gogoproto.nullable) = false, (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];
    // Time is just used for debugging purposes. It is not used in business
    // logic. It is an HLC rather than just wall time only for historical
    // reasons. Prior to 20.1 it was populated with the commit timestamp of the
    // transaction which created this replacement. In 20.1 and after it is
    // populated with the read timestamp at which the descriptor being
    // replaced was read.
    optional util.hlc.Timestamp time = 2 [(gogoproto.nullable) = false];
  }

  // ReplacementOf tracks prior IDs by which this table went -- e.g. when
  // TRUNCATE creates a replacement of a table and swaps it in for the the old
  // one, it should note on the new table the ID of the table it replaced. This
  // can be used when trying to track a table's history across truncatations.
  optional Replacement replacement_of = 30 [(gogoproto.nullable) = false];

  // AuditMode indicates which auditing actions to take when this table is used.
  enum AuditMode {
    DISABLED = 0;
    READWRITE = 1;
  }
  optional AuditMode audit_mode = 31 [(gogoproto.nullable) = false];

  // The job id for a drop job is the id in the system.jobs table of the
  // dropping of this table.
  optional int64 drop_job_id = 32 [(gogoproto.nullable) = false, (gogoproto.customname) = "DropJobID"];

  message GCDescriptorMutation {
    option (gogoproto.equal) = true;
    optional int64 index_id = 1 [(gogoproto.nullable) = false, (gogoproto.customname) = "IndexID",
                                (gogoproto.casttype) = "IndexID"];

    optional int64 drop_time = 2 [(gogoproto.nullable) = false, deprecated = true];

    // The job id for a mutation job is the id in the system.jobs table of the
    // schema change job executing the mutation referenced by mutation_id.
    optional int64 job_id = 3 [(gogoproto.nullable) = false,
                              (gogoproto.customname) = "JobID", deprecated = true];
  }

  // The schema elements that have been dropped and whose underlying
  // data needs to be gc-ed. These schema elements have already transitioned
  // through the drop state machine when they were in the above mutations
  // list, and can be safely deleted. The names for these schema elements
  // can be reused. This list is separate because mutations can
  // lie in this list for a long time (gc deadline) and should not block
  // the execution of other schema changes on the table.
  //
  // TODO(vivekmenezes): This is currently only used by the non-interleaved drop
  // index case. Also use for dropped interleaved indexes and columns.
  repeated GCDescriptorMutation gc_mutations = 33 [(gogoproto.nullable) = false,
                                                  (gogoproto.customname) = "GCMutations"];

  optional string create_query = 34 [(gogoproto.nullable) = false];

  // Starting in 19.2 CreateAsOfTime is initialized to zero for the first
  // version of a table and is populated from the MVCC timestamp of the read
  // like ModificationTime. See Descriptor.Table().
  // CreateAsOfSystemTime is used for CREATE TABLE ... AS ... and was
  // added in 19.1.
  optional util.hlc.Timestamp create_as_of_time = 35 [(gogoproto.nullable) = false];

  // outbound_fks contains all foreign key constraints that have this table as
  // the origin table.
  repeated ForeignKeyConstraint outbound_fks = 36 [(gogoproto.nullable) = false, (gogoproto.customname) = "OutboundFKs"];
  // inbound_fks contains all foreign key constraints that have this table as
  // the referenced table.
  repeated ForeignKeyConstraint inbound_fks = 37 [(gogoproto.nullable) = false, (gogoproto.customname) = "InboundFKs"];

  // Temporary table support will be added to CRDB starting from 20.1. The temporary
  // flag is set to true for all temporary tables. All table descriptors created
  // before 20.1 refer to persistent tables, so lack of the flag being set implies
  // the table is persistent.
  optional bool temporary = 39 [(gogoproto.nullable) = false];
}

// DatabaseDescriptor represents a namespace (aka database) and is stored
// in a structured metadata key. The DatabaseDescriptor has a globally-unique
// ID shared with the TableDescriptor ID.
// Permissions are applied to all tables in the namespace.
message DatabaseDescriptor {
  option (gogoproto.equal) = true;
  // Needed for the descriptorProto interface.
  option (gogoproto.goproto_getters) = true;

  optional string name = 1 [(gogoproto.nullable) = false];
  optional uint32 id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];
  optional PrivilegeDescriptor privileges = 3;
}

// Descriptor is a union type holding either a table or database descriptor.
message Descriptor {
  option (gogoproto.equal) = true;
  oneof union {
    TableDescriptor table = 1;
    DatabaseDescriptor database = 2;
  }
}