TcaplusDB PB Table Go SDK Get Started

The preparations for using the Go SDK mainly include:

1. Prepare the environment;
2. Create an app;
3. Create a game zone;
4. Create a table;
5. Collect environmental information;
6. Download SDK;
7. Configure the development environment.

If the above preparations have been completed, they can be skipped.

1. Prepare the Environment

Refer to Create a Cluster to deploy the TcaplusDB cluster, or apply for the TcaplusDB service.

2. Create an App

Refer to Create an App to create an App.

3. Create A Game Zone

Refer to Create a Game Zone to create a game zone (Zone).

4. Create A Table

Refer to Add a Table to add a table.

PB tables are divided into Generic tables and List tables. All pb tables of TcaplusDB depend on this table tcaplusservice.optionv1.proto

// TcaplusService option Ver.1
// Author: Calvinshao
// 2016-8-1

syntax = "proto2";

package tcaplusservice;

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions
{
    optional string tcaplus_primary_key = 60000; //Tcaplus Primary Key
    repeated string tcaplus_index = 60001; //Tcaplus Index
}

extend google.protobuf.FieldOptions
{
    optional uint32 tcaplus_size = 60000; // Tcaplus field size
    optional string tcaplus_desc = 60001; // Tcaplus description
}

4.1. Generic Table Definition Descriptions

Content example of the Generic table description file:

syntax = "proto3";         // Specify the protobuf language version, proto3.

// Import the TcaplusDB public definition service 
import "tcaplusservice.optionv1.proto";

message game_players {  // Define a TcaplusDB table, including the message type

// Create a primary key field based on the option tcaplusservice.tcaplus_primary_key
// A single table of TcaplusDB can specify up to 8 primary key fields (3.37.0 and later)
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    option(tcaplusservice.tcaplus_sharding_key) = "player_id";

    // Create a primary key index based on the option tcaplusservice.tcaplus_index
    option(tcaplusservice.tcaplus_index) = "index_1(player_id, player_name)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)";

    // Numeric types supported by TcaplusDB:
    // int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
    // Nested type: message

    // Primary key field
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;

    // Common (non-primary) key field
    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;

}

Refer to PB Table for the format description of the PB table description file.

4.2. List Table Definition Descriptions

Content example of the List table description file:

syntax = "proto3";

package myTcaplusTable;

import "tcaplusservice.optionv1.proto";

message tb_online_list {
    option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey";
    option(tcaplusservice.tcaplus_customattr) = "TableType=LIST;ListNum=1900";

    int32 openid = 1;
    int32 tconndid = 2;
    string timekey = 3;
    string gamesvrid = 4;
    int32 logintime = 5 ;
    repeated int64 lockid = 6;
    pay_info pay = 7;

    message pay_info {
        uint64 total_money = 1;
        uint64 pay_times = 2;
    }
    map<string, pay_info> projects = 8;
}

Refer to PB Table for the format description of the PB table description file.

The TableType=LIST in tcaplus_customattr defined by the table is used to identify the List table, and the ListNum attribute is also used to specify how many elements can be stored in a single List at most.

Note: Since the List table has a built-in primarykey field to store the element serial numbers in the List, users can only define up to 7 primarykey fields for the List table.

5. Collect Environmental Information

When using the SDK, it requires some environment related parameters. See the following table for specific parameters and collection methods.

6. Download Go SDK

For details about the Go SDK release and download link, see PB Table SDK Download.

7. Configure the Compilation Development Environment

Remarks:

• After downloading protoc, copy it to the /usr/bin directory

• After downloading protoc-gen-go, enter the corresponding directory, find go build -o protoc-gen-go main.go to get binary files, and copy them to the /usr/bin system directory

7.1 Convert PB Table Proto File to Go Code

#Place the tcaplusservice.optionv1.proto, which the user-defined mytable.proto file already depends on, in the current directory
mkdir tcaplusservice
#Generate the pb protocol interface code
protoc --go_out=./tcaplusservice tcaplusservice.optionv1.proto
#Generate the table definition interface code
protoc --go_out=./tcaplusservice mytable.proto

Remarks:

• You need to install the protoc-gen-go plug-in at the same time

• You need to specify the package in the proto file, such as the default package tcaplusservice

7.2 Compile

Enter the example Directory and build the corresponding go code as follows

# Go parameters
export GO111MODULE=on
export GOPATH:=${GOPATH}:$(shell pwd)/../../../../
GOCMD=go
GOBUILD=$(GOCMD) build
GOCLEAN=$(GOCMD) clean
BINARY_NAME=async

all: build
build:
    $(GOBUILD) -o $(BINARY_NAME) *.go
clean:
    $(GOCLEAN)
    rm -f $(BINARY_NAME)

Example Directory Description:

• Sync is an example of synchronization + multi-coordination (recommended)

• Sync2.0 is further optimized and encapsulated based on sync. The synchronization + option mode is simpler to use (recommended)

• Async is an example of asynchronous mode

8. Use Go SDK

Please refer to the Go SDK Interfaces Descriptions for details

9. FAQ

In the process of using the SDK, if you have questions (such as viewing the SDK version, configuring SDK log printing, upgrading the SDK, etc.), or errors, please refer to "FAQ" and "Meaning and Handling of Error Codes".

1. FAQ document;

2. Meaning and Handling of Error Codes document;