TcaplusDB Client Get Started

TcaplusDB Client is a command line tool used to access data in TcaplusDB. It is used to access data in TcaplusDB. The current commands provided by TcaplusDB are:

1. Preparations

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

Refer to Create an App to create an App.

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

Refer to Add a Table to add a table.

Note: If one of the above preparations has been completed, you can skip it directly.

2. Environment Requirements

3. Download Client

See the Client Download document.

4. Use Client

4.1. Deploy Client

Following the preceding instructions, download the TcaplusDB Client and upload it to a server that can connect to the TcaplusDB network.

The TcaplusDB Client is an executable file that can be run without decompression.

4.2. Start Client and Connect to TcaplusDB

Run tcaplus_client directly, without any parameters. It will prompt the user to provide the parameter information and samples to connect to TcaplusDB (see the following table and code). The user can start TcaplusDB Client and connect to TcaplusDB after replacing the relevant parameters in the sample with the relevant information collected in the preparation.

See the following table for the relevant parameters and acquisition methods required to connect to TcaplusDB:

# ./tcaplus_client
--------------------------------------------------------------------------------
invalid parameters, please start the client as following:
         ./tcaplus_client -a access_id -z tablegroup_id [-s signature] -d dir_server_url [-t table_name] [-l log_file.xml] [-T tdr_file.tdr] [-e execute_command].
         the params in [] are optional, and their order is not important.
         -a(--app_id)    APP_ID or Access ID of Cluster.
         -z(--zone_id)    ZONE ID or TableGroup Id.
         -s(--signature)    PASSWORD.
         -d(--dir)    dir server addr.
         -t(--table)    table to add.
         -l(--log)    log file name that must be client_log.xml, and log class name be client.
         -T(--tdr)    tdr filename.
         -e(--execute)    SQL command need to execute, the content should be in quotes.
         e.g. ./tcaplus_client -a 2 -z 3 -s "FE6533875C8385C3" -d 172.25.40.181:9999 -T table_test.tdr -e "select a, b from table where key = 1;".
         -f(--command_file)    the file that saves sql query commands.
         -n(--timeout)    set timeout seconds.
         -q(--qps)    set the upper limit of the number of requests sent per second, currently only valid for load operations.

Run tcaplus_client, and specify the relevant parameters of the TcaplusDB to be connected, then enter the TcaplusDB Client command line and execute other commands to access the data in TcaplusDB.

# ./tcaplus_client -a 2 -z 3 -s 51BD7E6215D6F0BE -d 9.135.8.93:9999

====== Welcome to use tcaplus_client, use "help" to show usage ======

tcaplus>

4.3. Access TcaplusDB Data

Users can use the help command or refer to the Command Description for more commands and instructions.

tcaplus> help;
--------------------------------------------------------------------------------     
      help: show usage of commands, example: "help select;".
      show: get server status related information. executing "help show;" for details.
      exit/quit: exit the client.
     count: print record number in the database.

      desc: print table field name and type.
    select: query records from database.
    insert: insert a new record into database.
   replace: replace a record into the database.
    update: update a record in the database.
    delete: delete record(s) from database.

      dump: dump records from database.
      load: load records into the database.

--------------------------------------------------------------------------------

Users can also view the command instructions through `> help specific command`.

Refer to the Common Errors for common error information and causes during command execution.

4.4. Set Client Log Output

By default, TcaplusDB Client will output logs to client.log and client_NetThread*.log files in the current directory, and only output logs above INFO level (INFO/WARN/ERROR/FATAL).

In some scenarios (such as fault locating), you may need to customize the log output directory and log output level. In this case, users can refer to the Log Configuration File Template to edit the log configuration file, and use the -l parameter of tcaplus_client to specify the log configuration file to be used. Note: The current log file name can only be a fixed client_log.xml.

4.4. Custom Binary Data Format Output Plug-in

By default, TcaplusDB Client encodes and outputs binary data in hexadecimal format (such as binary and single_struct fields in the figure below), but it also supports users to customize the binary data output format by writing SO plug-ins.

Limitation: At present, it only supports the customized output format of binary data for the first-level binary type field of the TDR table and the byte type field of the PB table.

Instructions:

1. Write the SO plug-in, as shown below. The interface is named ParseRecord, and the parameters include app_id、zone_id, table, key, and value. The key map stores the field names and values of the primary keys, and the value map stores the field names and values of the non-primary keys. The parsed values are also stored in these two maps. The log is used for the error prompt of exceptions. The interface returns an int type. The return of non-0 is regarded as an exception.

This example changes the original hexadecimal format output of the single_struct field and the binary field to only output the length of the field content.

parse.cc

#include <string>
#include <map>
#include <sstream>

typedef unsigned long long uint64_t;
typedef unsigned long int32_t;

template<typename T>
std::string ToStr(const T& val)
{
        std::ostringstream oss;
        oss<<val;
        return oss.str();
}
// g++ -fPIC -shared -g -lstdc++ parse.cc -o parse.so
extern "C" int ParseRecord (const int32_t app_id, const int32_t zone_id, const char* table, std::map<std::string, std::string>& key, std::map<std::string, std::string>& value, std::string& log)
{
        std::map<std::string, std::string>::const_iterator iter = value.find("single_struct");
        if(iter==value.end())
        {
                log = "invalid value, not find single_struct.";
                return -1;
        }
        std::string val = value["single_struct"];
        value["single_struct"] = ToStr(val.size());
        iter = value.find("binary");
        if(iter==value.end())
        {
                log = "invalid value, not find binary.";
                return -1;
        }
        val = value["binary"];
        value["binary"] = ToStr(val.size());

        return 0;
}

1. Compile the SO file.

g++ -fPIC -shared -g -lstdc++ parse.cc -o parse.so

1. When starting TcaplusDB Client, specify the SO file path through the -L parameter.

./tcaplus_client -a 2 -z 3 -s "35D60968120FA165" -d 9.135.12.47:9999 -L ./parse.so

1. Query the data and view the output.

select * from table_list_bin where uin=1 and name=3;