syntax = "proto3";

package cosmos.orm.v1alpha1;

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions {

  // table specifies that this message will be used as an ORM table. It cannot
  // be used together with the singleton option.
  TableDescriptor table = 104503790;

  // singleton specifies that this message will be used as an ORM singleton. It cannot
  // be used together with the table option.
  SingletonDescriptor singleton = 104503791;
}

// TableDescriptor describes an ORM table.
message TableDescriptor {

  // primary_key defines the primary key for the table.
  PrimaryKeyDescriptor primary_key = 1;

  // index defines one or more secondary indexes.
  repeated SecondaryIndexDescriptor index = 2;

  // id is a non-zero integer ID that must be unique within the
  // tables and singletons in this file. It may be deprecated in the future when this
  // can be auto-generated.
  uint32 id = 3;
}

// PrimaryKeyDescriptor describes a table primary key.
message PrimaryKeyDescriptor {

  // fields is a comma-separated list of fields in the primary key. Spaces are
  // not allowed. Supported field types, their encodings, and any applicable constraints
  // are described below.
  //   - uint32, uint64 are encoded as big-endian fixed width bytes and support
  //   sorted iteration.
  //   - string's are encoded as raw bytes in terminal key segments and null-terminated
  //   in non-terminal segments. Null characters are thus forbidden in strings.
  //   string fields support sorted iteration.
  //   - bytes are encoded as raw bytes in terminal segments and length-prefixed
  //   with a single byte in non-terminal segments. Because of this byte arrays
  //   longer than 255 bytes are unsupported and bytes fields should not
  //   be assumed to be lexically sorted. If you have a byte array longer than
  //   255 bytes that you'd like to index, you should consider hashing it first.
  //   - int32, sint32, int64, sint64 are encoding as fixed width bytes with
  //   an encoding that enables sorted iteration.
  //   - google.protobuf.Timestamp and google.protobuf.Duration are encoded
  //   as 12 bytes using an encoding that enables sorted iteration.
  //   - enum fields are encoded using varint encoding and do not support sorted
  //   iteration.
  //   - bool fields are encoded as a single byte 0 or 1.
  //
  // All other fields types are unsupported in keys including repeated and
  // oneof fields.
  //
  // Primary keys are prefixed by the varint encoded table id and the byte 0x0
  // plus any additional prefix specified by the schema.
  string fields = 1;

  // auto_increment specifies that the primary key is generated by an
  // auto-incrementing integer. If this is set to true fields must only
  // contain one field of that is of type uint64.
  bool auto_increment = 2;

  // references specifies that this primary key references the primary key
  // of another table. See the documentation for the SecondaryIndexDescriptor.references
  // field for more details. An additional constraint placed on primary keys
  // which reference another table is that those references cannot be circular.
  string references = 3;
}

// PrimaryKeyDescriptor describes a table secondary index.
message SecondaryIndexDescriptor {

  // fields is a comma-separated list of fields in the index. The supported
  // field types are the same as those for PrimaryKeyDescriptor.fields.
  // Index keys are prefixed by the varint encoded table id and the varint
  // encoded index id plus any additional prefix specified by the schema.
  //
  // In addition the the field segments, non-unique index keys are suffixed with
  // any additional primary key fields not present in the index fields so that the
  // primary key can be reconstructed. Unique indexes instead of being suffixed
  // store the remaining primary key fields in the value..
  string fields = 1;

  // id is a non-zero integer ID that must be unique within the indexes for this
  // table. It may be deprecated in the future when this can be auto-generated.
  uint32 id = 2;

  // unique specifies that this an unique index.
  bool unique = 3;

  // references specifies that this index references another table defined in the same
  // proto file. Currently references are not support to tables with composite
  // primary keys, therefore fields must reference one field and its type must
  // be the same type as the primary key field of the referenced table.
  // References to tables in defined by different proto files are not supported
  // to avoid tight coupling of dependencies. Beyond validating that the reference
  // is valid key constraints are currently not enforced, but references should
  // be used by clients to perform automatic joins.
  string references = 4;
}

// TableDescriptor describes an ORM singleton table which has at most one instance.
message SingletonDescriptor {

  // id is a non-zero integer ID that must be unique within the
  // tables and singletons in this file. It may be deprecated in the future when this
  // can be auto-generated.
  uint32 id = 1;
}