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 = "descpb";

import "util/hlc/timestamp.proto";
import "sql/catalog/descpb/privilege.proto";
import "sql/types/types.proto";
import "geo/geoindex/config.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;
}

// ForeignKeyReference is deprecated, replaced by ForeignKeyConstraint in v19.2
// (though it is still possible for table descriptors on disk to have
// ForeignKeyReferences).
//
// It is still used to describe interleavings (see
// IndexDescriptor.InterleavedBy), for which it is a poor choice: only the Table
// and Index fields are used, and the interleaving has nothing to do with
// traditional foreign key references.
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];

  // These fields were used for foreign keys until 20.1.
  reserved 10, 11, 12, 13;
}

// UniqueWithoutIndexConstraint is the representation of a unique constraint
// that is not enforced by an index. It is stored on the TableDescriptor.
message UniqueWithoutIndexConstraint {
  option (gogoproto.equal) = true;
  optional uint32 table_id = 1 [(gogoproto.nullable) = false,
                                      (gogoproto.customname) = "TableID",
                                      (gogoproto.casttype) = "ID"];
  repeated uint32 column_ids = 2 [(gogoproto.customname) = "ColumnIDs",
                                        (gogoproto.casttype) = "ColumnID"];
  optional string name = 3 [(gogoproto.nullable) = false];
  optional ConstraintValidity validity = 4 [(gogoproto.nullable) = false];

  // Predicate, if it's not empty, indicates that the constraint is a partial
  // unique constraint with Predicate as the expression. Columns are referred to
  // in the expression by their name.
  optional string predicate = 5 [(gogoproto.nullable) = false];
}

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 sql.sem.types.T type = 3;
  optional bool nullable = 4 [(gogoproto.nullable) = false];
  reserved 8;
  // Default expression to use to populate the column on insert if no
  // value is provided. Note that it is not correct to use DefaultExpr
  // as output to display to a user. User defined types within DefaultExpr
  // have been serialized in a internal format. Instead, use one of the
  // schemaexpr.FormatExpr* functions.
  optional string default_expr = 5;
  reserved 9;

  // On update expression to use to populate the column on update if no
  // value is provided. Note that it is not correct to use OnUpdateExpr
  // as output to display to a user. User defined types within OnUpdateExpr
  // have been serialized in a internal format. Instead, use one of the
  // schemaexpr.FormatExpr* functions.
  optional string on_update_expr = 18;

  // A hidden column does not appear in star expansion, but can be referenced in
  // queries and can be viewed when inspecting a table via SHOW CREATE TABLE. A
  // column cannot be both hidden and inaccessible.
  optional bool hidden = 6 [(gogoproto.nullable) = false];

  // An inaccessible column does not appear in star expansion and cannot be
  // referenced in queries. It cannot be viewed when inspecting a table via SHOW
  // CREATE TABLE and is not shown as an attribute of its table in
  // pg_catalog.pg_attribute. A column cannot be both hidden and inaccessible.
  optional bool inaccessible = 17 [(gogoproto.nullable) = false];

  // GeneratedAsIdentityType is an enum that represents how the creation of the
  // column is associated with the GENERATED ... AS IDENTITY syntax.
  // If the column is created with GENERATED ALWAYS AS IDENTITY syntax,
  // GeneratedAsIdentityType for this column will be set to GENERATED_ALWAYS.
  // If the column is created with GENERATED BY DEFAULT AS IDENTITY syntax,
  // GeneratedAsIdentityType for this column will be set to GENERATED_BY_DEFAULT.
  // If the column is created without using GENERATED ... AS IDENTITY syntax,
  // GeneratedAsIdentityType for this column will be set to the default
  // NOT_IDENTITY_COLUMN.
  optional GeneratedAsIdentityType generated_as_identity_type = 19 [(gogoproto.nullable) = false];

  // Expression to specify the sequence option for a `GENERATED AS IDENTITY`
  // column.
  optional string generated_as_identity_sequence_option = 20;

  reserved 7;
  // Ids of sequences used in this column's DEFAULT and ON UPDATE expressions,
  // 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. Note that it is not correct to use ComputeExpr
  // as output to display to a user. User defined types within ComputeExpr
  // have been serialized in a internal format. Instead, use one of the
  // schemaexpr.FormatExpr* functions.
  optional string compute_expr = 11;

  // A computed column can be stored or virtual.
  // Virtual can only be true if there is a compute expression.
  optional bool virtual = 16 [(gogoproto.nullable) = false];

  // PGAttributeNum must be accessed through the accessor, since it is set
  // lazily, it is incorrect to access it directly.
  // PGAttributeNum represents a column's number in catalog tables.
  // 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 pg_attribute_num = 13 [(gogoproto.nullable) = false, (gogoproto.customname) = "PGAttributeNum"];
  // Used to indicate column is used and dropped for ALTER COLUMN TYPE mutation.
  optional bool alter_column_type_in_progress = 14 [(gogoproto.nullable) = false];

  // SystemColumnKind represents what kind of system column this column
  // descriptor represents, if any.
  optional SystemColumnKind system_column_kind = 15 [(gogoproto.nullable) = false];
}

// SystemColumnKind is an enum representing the different kind of system
// columns that can be synthesized by the execution engine.
enum SystemColumnKind {
  // Default value, unused.
  NONE = 0;
  // A system column containing the value of the MVCC timestamp associated
  // with the kv's corresponding to the row.
  MVCCTIMESTAMP = 1;
  // A system column containing the OID of the table that the row came from.
  TABLEOID = 2;
}

// GeneratedAsIdentityType is an enum representing how the creation of
// a column is associated with the GENERATED {ALWAYS | BY DEFAULT} AS IDENTITY
// syntax.
enum GeneratedAsIdentityType {
  // A column created without `GENERATED ... AS IDENTITY` syntax.
  NOT_IDENTITY_COLUMN = 0;
  // A column created with `GENERATED ALWAYS AS IDENTITY` syntax.
  // Such a column does not allow override without `OVERRIDING SYSTEM VALUE`
  // syntax.
  GENERATED_ALWAYS = 1;
  // A column created with `GENERATED BY DEFAULT AS IDENTITY` syntax.
  // Such a column can be overridden without `OVERRIDING SYSTEM VALUE` syntax.
  GENERATED_BY_DEFAULT = 2;
}

// 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];
  // NumImplicitColumns specifies the number of columns that implicitly prefix a given index.
  // This occurs if a user specifies a PARTITION BY which is not a prefix of the given index,
  // in which case the ColumnIDs are added in front of the index and this field denotes
  // the number of columns added as a prefix.
  // If NumImplicitColumns is 0, there are no implicit columns defined for the index."
  optional uint32 num_implicit_columns = 4 [(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
//   key_column_names:       k1, k2
//   key_column_directions:  ASC, ASC
//   key_column_ids:         1, 2   // k1, k2
//
// [old STORING encoding] Index k1v (k1, v) STORING (w):
//   name:                   k1v
//   id:                     2
//   unique:                 false
//   key_column_names:       k1, v
//   key_column_directions:  ASC, ASC
//   store_column_names:     w
//   key_column_ids:         1, 4   // k1, v
//   key_suffix_column_ids:  2, 5   // k2, w
//
// [new STORING encoding] Index k1v (k1, v) STORING (w):
//   name:                   k1v
//   id:                     2
//   unique:                 false
//   key_column_names:       k1, v
//   key_column_directions:  ASC, ASC
//   store_column_names:     w
//   key_column_ids:         1, 4   // k1, v
//   key_suffix_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 key_column_ids list.
  //
  // If the index is an inverted index, the last column in the list is
  // inverted and all others are not.
  //
  // 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 key_column_names = 4;

  // The sort direction of each column in key_column_names.
  repeated Direction key_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 key is comprised. This
  // list parallels the key_column_names list and does not include any
  // additional stored columns. If the index is an inverted index, the last
  // column in the list is inverted and all others are not.
  repeated uint32 key_column_ids = 6 [(gogoproto.customname) = "KeyColumnIDs",
      (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, in other words
  //        PrimaryIndex.key_column_ids - key_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 key_suffix_column_ids = 7 [(gogoproto.customname) = "KeySuffixColumnIDs",
      (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
  // key_column_ids and key_suffix_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.
  //
  // Note that any of these indexes can themselves be interleaved by other
  // tables but this list contains only those for which this index is a direct
  // interleave parent.
  //
  // Only the Table and Index fields of the ForeignKeyReference are used. And
  // despite the message used here, interleavings don't have to have
  // corresponding foreign key references (and whether they do or not is
  // irrelevant for this field).
  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];

  // GeoConfig, if it's not the zero value, describes configuration for
  // this geospatial inverted index.
  optional geo.geoindex.Config geo_config = 22 [(gogoproto.nullable) = false];

  // Predicate, if it's not empty, indicates that the index is a partial index
  // with Predicate as the expression. If Predicate is empty, the index is not
  // a partial index. Columns are referred to in the expression by their name.
  // TODO(mgartner): Update the comment to explain that columns are referenced
  // by their ID once #49766 is addressed.
  optional string predicate = 23 [(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;
    UNIQUE_WITHOUT_INDEX = 3;
  }
  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"];
  optional UniqueWithoutIndexConstraint unique_without_index_constraint = 7 [(gogoproto.nullable) = false];
}

// 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"];
  // new_primary_index_name is the name of the primary key when added as a
  // new constraint to a table without a primary key. In other cases, it is
  // the empty string.
  optional string new_primary_index_name = 5 [(gogoproto.nullable) = false];

  message LocalityConfigSwap {
    option (gogoproto.equal) = true;
    optional TableDescriptor.LocalityConfig old_locality_config = 1 [(gogoproto.nullable) = false];
    optional TableDescriptor.LocalityConfig new_locality_config = 2 [(gogoproto.nullable) = false];

    // NewRegionalByRowColumnID is set when we are creating a new column for a
    // REGIONAL BY ROW table. It is used by NewRegionalByRowColumnDefaultExpr
    // to identify the column we may have to change DefaultExpr for.
    optional uint32 new_regional_by_row_column_id = 3 [(gogoproto.casttype) = "ColumnID", (gogoproto.customname) = "NewRegionalByRowColumnID"];
    // NewRegionalByRowColumnDefaultExpr is the default expression to set when a
    // REGIONAL BY ROW involving a new crdb_region column is required.
    // This is required so that the backfill uses a well-known value, but after
    // the backfill is complete we can set it to use the gateway_region.
    //
    // This must be set at mutation creation time, as the schema changer loses
    // context on what the database is. The default expression should be already
    // serialized in the same internal format as default_expr on the
    // ColumnDescriptor.
    optional string new_regional_by_row_column_default_expr = 4;
  }
  // LocalityConfigSwap is set for ALTER TABLE SET LOCALITY when the command
  // requires PK changes. If set, additional zone configurations are set to
  // match the new locality config.
  optional LocalityConfigSwap locality_config_swap = 6;
}

// ComputedColumnSwap is a mutation corresponding to the atomic swap phase
// where Column a' that is computed using Column a is swapped to replace
// Column a while Column a becomes computed using a'.
message ComputedColumnSwap {
  option (gogoproto.equal) = true;
  optional uint32 new_column_id = 1 [(gogoproto.nullable) = false, (gogoproto.casttype) = "ColumnID"];
  optional uint32 old_column_id = 2 [(gogoproto.nullable) = false, (gogoproto.casttype) = "ColumnID"];
  // inverse_expr is the expression used to compute values for the old column
  // once it is swapped for the new column.
  optional string inverse_expr = 3 [(gogoproto.nullable) = false];
}

// MaterializedViewRefresh is a mutation corresponding to a request to
// refresh a materialized view. The mutation operates by backfilling the
// result of the view query into the indexes specified by the mutation.
message MaterializedViewRefresh {
  option (gogoproto.equal) = true;
  // NewPrimaryIndex is the new primary index of the view to backfill into.
  // NewPrimaryIndex and NewIndexes below are copies of the existing indexes on
  // the view, but with different ID's.
  optional IndexDescriptor new_primary_index = 1 [(gogoproto.nullable) = false];
  // NewIndexes are the new set of indexes to backfill the view into.
  repeated IndexDescriptor new_indexes = 2 [(gogoproto.nullable) = false];
  // AsOf is the timestamp to perform the view query at.
  optional util.hlc.Timestamp as_of = 3 [(gogoproto.nullable) = false];
  // ShouldBackfill indicates whether or not the schema changer should backfill
  // the query into the new indexes. This can be false if the `WITH NO DATA` flag
  // was specified for the `REFRESH MATERIALIZED VIEW` statement. `WITH NO DATA`
  // indicates that the user just wants the space used by the view to be reclaimed.
  optional bool should_backfill = 4 [(gogoproto.nullable) = false];
}

// 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;
    ComputedColumnSwap computedColumnSwap = 10;
    MaterializedViewRefresh materializedViewRefresh = 11;
  }
  // 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 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];
}

// State indicates whether a descriptor is public (i.e., normally visible,
// resolvable, etc.) or in some other state subject to restrictions.
// 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 DescriptorState {
  // Descriptor is visible and can be leased.
  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;
}

// 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 following 5 fields: name, id, version, modification_time, and
  // draining_names are metadata fields required by all descriptors to be
  // leasable. The reason that they do not exist in a message of their own is
  // to ease the migration burden as not all descriptors initially had all of
  // these fields but many had some.

  // 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"];
  // 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 uint64 version = 5 [(gogoproto.nullable) = false, (gogoproto.casttype) = "DescriptorVersion"];
  // 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];
  // 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];

  // 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"];


  reserved 6;

  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;

  optional DescriptorState state = 19 [(gogoproto.nullable) = false];
  optional string offline_reason = 38 [(gogoproto.nullable) = false];

  message CheckConstraint {
    option (gogoproto.equal) = true;
    // Expr is the expression that this check constraint represents.
    // Note that it is not correct to use Expr as output to display
    // to a user. User defined types within Expr have been serialized
    // in a internal format. Instead, use one of the schemaexpr.FormatExpr*
    // functions.
    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];
    // Hidden is set to true for hash-sharded column check constraints.
    // Previously, this field was used to hide these constraints in the output
    // of SHOW CREATE TABLE. We no longer them in order to make the output to be
    // round-trippable, but we still set this field for now. See #68031.
    optional bool hidden = 7 [(gogoproto.nullable) = false];
  }

  repeated CheckConstraint checks = 20;

  // 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];
  // IsMaterializedView indicates whether this view is materialized or not.
  // A materialized view has the view query results stored durably on disk
  // as a table. The data on disk is refreshed with the REFRESH MATERIALIZED
  // VIEW command. This flag is only set when ViewQuery != "".
  optional bool is_materialized_view = 41 [(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"];

  // The IDs of all types that this depends on.
  // Only ever populated if this descriptor is for a view.
  repeated uint32 dependsOnTypes = 45 [(gogoproto.customname) = "DependsOnTypes",
    (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"];
    // ByID indicates whether the relation is referenced via its name or its ID.
    // For example, nextval('foo.public.seq') vs. nextval(12345::REGCLASS),
    // where 12345 is the ID of foo.public.seq
    // Sequences referenced only by its ID have the ability to be renamed.
    optional bool by_id = 4 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ByID"];
  }

  // 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.
    // This is not a jobspb.JobID to avoid a dependency cycle.
    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];

  // The job associated with a schema change job run in the new schema changer
  // (in sql/schemachanger), if one exists. Only one such job can exist at a
  // time.
  optional int64 new_schema_change_job_id = 46 [(gogoproto.nullable) = false,
                                               (gogoproto.customname) = "NewSchemaChangeJobID"];

  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 number of values (which have already been created in KV)
    // that a node can cache locally.
    optional int64 cache_size = 7 [(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"];

  // UniqueWithoutIndexConstraints contains all the unique constraints defined
  // on this table that are not enforced by an index.
  repeated UniqueWithoutIndexConstraint unique_without_index_constraints = 43 [(gogoproto.nullable) = false];

  // 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];

  message LocalityConfig {
    option (gogoproto.equal) = true;
    // REGIONAL BY TABLE tables have an "implicit" bidirectional dependency with
    // the multi-region enum. The dependency is described "implicit" because
    // even though no column on the table uses the multi-region type descriptor
    // to store the homing region, a value from the type descriptor is stored in
    // the locality config below (when the table is homed in the non-primary
    // region).
    // This changes how type dependencies are constructed for table descriptors.
    // After the introduction of REGIONAL BY TABLE tables, a column on the table
    // descriptor using a type is no longer a necessary (note it is still a
    // sufficient) condition to establish a type dependency. As is the case with
    // adding and dropping columns, this type dependency must be negotiated. As
    // such, switching locality patterns or adding new locality configs must be
    // done so that back references to the multi-region type descriptor are
    // kept sane.
    message RegionalByTable {
      option (gogoproto.equal) = true;
      // Region is set if the table has an affinity with a non-primary region.
      optional string region = 1 [(gogoproto.casttype)="RegionName"];
    }
    message RegionalByRow {
      option (gogoproto.equal) = true;
      // As is set if the table has a REGIONAL BY ROW AS ... set to a specific column.
      optional string as = 1;
    }
    message Global {
      option (gogoproto.equal) = true;
    }
    oneof locality {
      Global global = 1;
      RegionalByTable regional_by_table = 2;
      RegionalByRow regional_by_row = 3;
    }
  }
  optional LocalityConfig locality_config = 42;

  // PartitionAllBy is set if PARTITION ALL BY is set on the table.
  // This means that all indexes implicitly inherit all partitioning
  // from the PARTITION ALL BY clause.
  optional bool partition_all_by = 44 [(gogoproto.nullable)=false];
}

// SurvivalGoal is the survival goal for a database.
enum SurvivalGoal {
  // Survive a zone failure. This is the default.
  ZONE_FAILURE = 0;
  // Survive a region failure.
  REGION_FAILURE = 1;
}

// DataPlacement is the data placement strategy for a database.
enum DataPlacement {
  // Default placement - use non-voters.
  DEFAULT = 0;
  // Restricted placement - contain data strictly inside assigned region.
  RESTRICTED = 1;
}

// DatabaseDescriptor represents a namespace (aka database) and is stored
// in a structured metadata key. The DatabaseDescriptor has a globally-unique ID
// shared with other Descriptors.
// 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;

  // Shared descriptor fields. See the discussion at the top of TableDescriptor.

  optional string name = 1 [(gogoproto.nullable) = false];
  optional uint32 id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];
  // Last modification time of the descriptor.
  optional util.hlc.Timestamp modification_time = 4 [(gogoproto.nullable) = false];
  optional uint64 version = 5 [(gogoproto.nullable) = false, (gogoproto.casttype) = "DescriptorVersion"];
  repeated NameInfo draining_names = 6 [(gogoproto.nullable) = false];

  optional PrivilegeDescriptor privileges = 3;

  // SchemaInfo represents the state of a child user defined schema.
  message SchemaInfo {
    option (gogoproto.equal) = true;
    // ID is the ID of the schema.
    optional uint32 id = 1 [(gogoproto.nullable) = false, (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];
    // dropped represents whether the schema is dropped or not. This field
    // is used in a similar way as the draining_names.
    optional bool dropped = 2 [(gogoproto.nullable) = false];
  }

  // schemas is a mapping from child schema name to ID. It is used during
  // name resolution to know without a KV lookup whether a database has a
  // child schema with a target name. Temporary schemas are not stored here.
  map<string, SchemaInfo> schemas = 7 [(gogoproto.nullable) = false];

  optional DescriptorState state = 8 [(gogoproto.nullable) = false];
  optional string offline_reason = 9 [(gogoproto.nullable) = false];

  // RegionConfig stores region configuration for a given database.
  message RegionConfig {
    option (gogoproto.equal) = true;

    reserved 1;
    optional SurvivalGoal survival_goal = 2 [(gogoproto.nullable)=false];
    optional string primary_region = 3 [(gogoproto.nullable)=false,(gogoproto.casttype)="RegionName"];

    // RegionEnumID represents ID of the type descriptor corresponding to the
    // region enum for a multi-region database. If the database is not a
    // multi-region database then this field is 0 and no such region enum exists.
    optional uint32 region_enum_id = 4 [(gogoproto.nullable) = false, (gogoproto.customname) = "RegionEnumID", (gogoproto.casttype) = "ID"];

    // DataPlacement dictates whether or not to use a restricted data placement
    // policy.
    optional DataPlacement placement = 5 [(gogoproto.nullable) = false];
  }
  // RegionConfig is only set if multi-region controls are set on the database.
  optional RegionConfig region_config = 10;

  // DefaultPrivileges contains the default privileges for the database.
  optional DefaultPrivilegeDescriptor default_privileges = 11;
}

// TypeDescriptor represents a user defined type and is stored in a structured
// metadata key. The TypeDescriptor has a globally-unique ID shared with other
// Descriptors.
message TypeDescriptor {
  option (gogoproto.equal) = true;
  // Needed for the descriptorProto interface.
  option (gogoproto.goproto_getters) = true;

  // Shared descriptor fields. See the discussion at the top of TableDescriptor.

  // name is the current name of this user defined type.
  optional string name = 3 [(gogoproto.nullable) = false];

  // id is the globally unique ID for this type.
  optional uint32 id = 4 [(gogoproto.nullable) = false, (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];


  optional uint64 version = 9 [(gogoproto.nullable) = false, (gogoproto.casttype) = "DescriptorVersion"];
  // Last modification time of the descriptor.
  optional util.hlc.Timestamp modification_time = 10 [(gogoproto.nullable) = false];
  repeated NameInfo draining_names = 11 [(gogoproto.nullable) = false];

  // privileges contains the privileges for the type.
  optional PrivilegeDescriptor privileges = 14;

  // Fields that are shared among all kinds of user defined types.

  // parent_id represents the ID of the database that this type resides in.
  optional uint32 parent_id = 1
  [(gogoproto.nullable) = false, (gogoproto.customname) = "ParentID", (gogoproto.casttype) = "ID"];

  // parent_schema_id represents the ID of the schema that this type resides in.
  optional uint32 parent_schema_id = 2
  [(gogoproto.nullable) = false, (gogoproto.customname) = "ParentSchemaID", (gogoproto.casttype) = "ID"];

  // array_type_id is the globally unique ID for the implicitly created array
  // type for this type. It is only set when the type descriptor points to a
  // non-array type.
  optional uint32 array_type_id = 8
    [(gogoproto.nullable) = false, (gogoproto.customname) = "ArrayTypeID", (gogoproto.casttype) = "ID"];

  optional DescriptorState state = 13 [(gogoproto.nullable) = false];
  optional string offline_reason = 15 [(gogoproto.nullable) = false];

  // Represents the kind of type that this type descriptor represents.
  enum Kind {
    // Represents a user defined enum type.
    ENUM = 0;
    // Represents a user defined type that is just an alias for another type.
    // As of now, it is used only internally.
    ALIAS = 1;
    // Represents a special multi-region enum type which tracks available regions
    // as its enum values.
    MULTIREGION_ENUM = 2;
    // Represents the virtual record type created on behalf of each table. This
    // kind of TypeDescriptor is *never* persisted to disk! If you are here,
    // thinking about using or persisting this value, you should *not* do that!
    VIRTUAL_TABLE_RECORD_TYPE = 3;
    // Add more entries as we support more user defined types.
  }
  optional Kind kind = 5 [(gogoproto.nullable) = false];

  // referencing_descriptor_ids is a set of descriptors that reference this type.
  repeated uint32 referencing_descriptor_ids = 12
    [(gogoproto.casttype) = "ID", (gogoproto.customname) = "ReferencingDescriptorIDs"];

  // The fields below are used only when this type is an ENUM or a
  // MULTIREGION_ENUM.

  // EnumMember represents a value in an enum.
  message EnumMember {
    option (gogoproto.equal) = true;
    optional bytes physical_representation = 1;
    optional string logical_representation = 2 [(gogoproto.nullable) = false];

    // Represents what operations are allowed on this ENUM member.
    enum Capability {
      // A member in the ALL state can be both read and written.
      ALL = 0;
      // A member in the READ_ONLY state can be only read from the bytes
      // representation of the member. Creation of this member from the logical
      // representation is disallowed, which prevents writes of the member.
      READ_ONLY = 1;
    }

    enum Direction {
      // Not used. Corresponds to the ALL capability.
      NONE = 0;
      // Enum value is being added.
      ADD = 1;
      // Enum value is being removed.
      REMOVE= 2;
    }
    optional Capability capability = 3 [(gogoproto.nullable) = false];
    optional Direction direction = 4 [(gogoproto.nullable) = false];
  }
  // enum_members is the set of values in an enum.
  repeated EnumMember enum_members = 6 [(gogoproto.nullable) = false];

  // The fields below are used only when this type is an ALIAS.

  // alias is the types.T that this descriptor is an alias for.
  optional sql.sem.types.T alias = 7;


  // The fields below are used only when this type is a MULTIREGION_ENUM.

  // RegionConfig stores the multi-region configuration for a type descriptor of
  // MULTIREGION_ENUM kind.
  message RegionConfig {
    option (gogoproto.equal) = true;

    // PrimaryRegion represents the PrimaryRegion for a multi-region enum.
    optional string primary_region = 1 [(gogoproto.nullable) = false, (gogoproto.casttype)="RegionName"];
  }

  optional RegionConfig region_config = 16;
}

// SchemaDescriptor represents a physical schema and is stored in a structured
// metadata key.
message SchemaDescriptor {
  option (gogoproto.equal) = true;
  // Needed for the descriptorProto interface.
  option (gogoproto.goproto_getters) = true;

  // Shared descriptor fields. See the discussion at the top of TableDescriptor.

  // name is the name of the schema.
  optional string name = 2 [(gogoproto.nullable) = false];

  // id is the schema ID, globally unique across all descriptors.
  optional uint32 id = 3
  [(gogoproto.nullable) = false, (gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"];

  optional DescriptorState state = 8 [(gogoproto.nullable) = false];
  optional string offline_reason = 9 [(gogoproto.nullable) = false];

  // Last modification time of the descriptor.
  optional util.hlc.Timestamp modification_time = 5 [(gogoproto.nullable) = false];
  optional uint64 version = 6 [(gogoproto.nullable) = false, (gogoproto.casttype) = "DescriptorVersion"];
  repeated NameInfo draining_names = 7 [(gogoproto.nullable) = false];

  // parent_id refers to the database the schema is in.
  optional uint32 parent_id = 1
  [(gogoproto.nullable) = false, (gogoproto.customname) = "ParentID", (gogoproto.casttype) = "ID"];

  // privileges contains the privileges for the schema.
  optional PrivilegeDescriptor privileges = 4;
}

// Descriptor is a union type for descriptors for tables, schemas, databases,
// and types.
message Descriptor {
  option (gogoproto.equal) = true;
  oneof union {
    TableDescriptor table = 1;
    DatabaseDescriptor database = 2;
    TypeDescriptor type = 3;
    SchemaDescriptor schema = 4;
  }
}