【TcaplusDB知识库】PB表定义示例

• 关于Protobuf

  Protobuf是Google开发的一种描述性语言，针对结构化数据进行序列化，同时强调简单性和性能。 官方文档：https://developers.google.com/protocol-buffers

PB表定义示例

以下是protobuf表game_players.proto的示例，您可以将文件上传到控制台并创建该表。

syntax = "proto3";         // 指定protobuf语言版本,proto3.
 
// 导入TcaplusDB公共定义服务 
import "tcaplusservice.optionv1.proto";
 
message game_players {  // 定义TcaplusDB表，包含message类型
 
// 基于选择项tcaplusservice.tcaplus_primary_key创建主键字段
// TcaplusDB单个表最多能指定8个主键字段(3.37.0及其之后版本)
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    option(tcaplusservice.tcaplus_sharding_key) = "player_id";
 
    // 基于选择项tcaplusservice.tcaplus_index创建主键索引
    option(tcaplusservice.tcaplus_index) = "index_1(player_id, player_name)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)";
 
    // TcaplusDB支持的数值类型:
    // int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
    // 嵌套类型: message
 
    // 主键字段
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;
     
    // 普通(非主键) 字段
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;
     
    payment pay = 8;
}
 
message payment {
     
int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;
 
}

Tcaplus相关属性

TcaplusDB 表定义可以在 protobuf 语法基础上通过 option 进行扩展，可以实现更丰富的语义功能，可定义的内容如下表所示。 详细的定义格式为：option(tcaplusservice.选项) = "值";

主键 tcaplus_primary_key

tcaplus_primary_key属性指明此元素对应数据库表的主键，如果有多个成员组成表的主键，则成员名之间用逗号（','）隔开，单个表最多能指定8个主键字段。 约束：

1. 作为主键的成员不能为复合数据类型，只能是基本内置数据类型。

2. 作为主键的成员其取值不能为NULL。

option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";

根据上面的描述，GameItem的数据表使用player_id, player_name, player_email三个成员作为主键。

分表属性(分表因子) tcaplus_sharding_key

如何选择分表因子

tcaplus_sharding_key属性用户可以自定义表分片键。 约束： 作为此成员不能为复合数据类型，只能是基本内置数据类型。

option(tcaplusservice.tcaplus_sharding_key) = "player_id";

本地索引 tcaplus_index

tcaplus_index属性用于设置TcaplusDB 表索引键字段。

option(tcaplusservice.tcaplus_index) = "player_email";

文件定义信息

文件定义信息区域主要定义当前表描述文件的公共信息，主要涉及如下3种类型的内容：

表定义信息

表定义信息主要通过 message 定义表的格式，在 message 中可对表的扩展信息进行定义，也可以对表的字段信息进行定义。

字段信息定义

TcaplusDB 定义字段的格式为：字段修饰符 字段类型 字段名称 = 标识号[特殊定义];

字段修饰符

proto2 支持3种类型的限定修饰符，proto3 不再支持 required 修饰，默认为 optional 类型。

• required：表示字段为必填字段，proto2 中主键字段必须被 required 修饰。

• optional：表示此字段为可选字段，支持设定字段的默认值。

• repeated：表示该字段可以包含0 - N个元素，其特性和 optional 一样，但是每一次可以包含多个值，可看作是在传递一个数组的值，必须指定 [packed = true] 的特殊定义。

字段类型

TcaplusDB 支持普通字段以及嵌套型字段，详细的字段介绍可参考 数据类型（PB，TDR）。

字段名称

针对当前属性而进行对字段进行命名，支持大小写字母，数字与下划线。建议字段的命名采用驼峰式命名方式，不能以数字开头。

标识号

标识号使用范围：[1,2^29 - 1]，不可使用 [19000－19999] 标识号，因为 Protobuf 协议实现中对这些标识号进行了预留，若使用，则会报错。 每个字段在进行编码时都会占用内存，而占用内存大小取决于标识号：

• 范围 [1,15] 标识号的字段在编码时占用1个字节。

• 范围 [16,2047] 标识号的字段在编码时占用2个字节。

特殊定义

• 当 repeated 修饰的字段需要指定 packed=true 选项。用法如下：

  repeated int64 lockid = 6 [packed = true]; 

• 使用 optional 修饰的字段可以通过 default = 1 指定其默认值。用法如下：

  optional int32 logintime = 5 [default = 1];

• 字段类型为 string 和 bytes 类型的字段可以指定为加密字段。用法如下：

  required string name = 2[(tcaplusservice.tcaplus_crypto) = true];

嵌套类型信息

TcaplusDB 支持嵌套类型，嵌套类型可以包含另一个嵌套类型作为其字段，也可以在嵌套类型内定义一个新的嵌套类型。 嵌套类型的定义与表的定义相似，均是通过 message 进行声明，但是结构体中不能包含扩展信息定义，如"主键"，"索引"等定义。 TcaplusDB 支持最多128层连续嵌套，但是不建议大量使用嵌套，嵌套层数过多会导致数据访问性能降低。

message game_players {  
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;
    payment pay = 8;
}
 
message payment {
int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;
}

PB表修改限制

1. 主键字段不能删除。

2. 主键字段名和字段类型不能改变。

3. 不能增加主键字段。

4. 普通字段有 required 标识的不能删除。

5. 同标识号的字段名称和字段类型不能改变。

6. 增加的普通字段名要符合命名规则,不能修改原有字段类型、名称，更不能删除原有字段。

7. 本地索引只能新增不能删除和修改。

示例：

1. 增加本地索引

2. 增加字段

syntax = "proto3";         
 
import "tcaplusservice.optionv1.proto";
 
message game_players {  
 
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    option(tcaplusservice.tcaplus_index) = "index_1(player_id, player_name)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)"; // 增加本地索引
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;
     
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;
     
    payment pay = 8;

    string player_email_copy = 9; // 增加value字段
}
 
message payment {
     
int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;
 
}

TcaplusDB是腾讯出品的分布式NoSQL数据库，存储和调度的代码完全自研。具备缓存+落地融合架构、PB级存储、毫秒级时延、无损水平扩展和复杂数据结构等特性。同时具备丰富的生态、便捷的迁移、极低的运维成本和五个九高可用等特点。客户覆盖游戏、互联网、政务、金融、制造和物联网等领域。