TcaplusDB Client 开始使用

TcaplusDB Client是一个用于访问TcaplusDB数据的命令行工具，用于访问TcaplusDB中数据，当前TcaplusDB提供的命令有：

1. 准备工作

参考创建集群文档，部署TcaplusDB集群，或者申请TcaplusDB服务。

参考创建业务文档，创建业务（App）。

参考创建游戏区文档，创建游戏区（Zone）。

参考创建表格文档，创建数据表。

注：以上准备工作如果某一项已经完成，可以直接跳过。

2. 环境要求

3. 下载Client

参见Client下载文档。

4. 使用Client

4.1. 部署Client

根据前述指导，下载TcaplusDB Client后，将其上传至可与TcaplusDB网络联通的服务器中。

TcaplusDB Client为可执行文件，无需解压，可直接运行。

4.2. 启动Client并连接TcaplusDB

直接运行tcaplus_client，不带任何参数，会提示需要提供连接TcaplusDB所需的参数信息及样例（见下表和代码），用户在将样例中的相关参数替换为准备工作中收集到的相关信息后，即可启动TcaplusDB Client并连接TcaplusDB。

连接的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.

运行tcaplus_client，并指定要连接的TcaplusDB的相关参数后，即可进入TcaplusDB Client命令行，执行其它命令访问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. 访问TcaplusDB数据

用户可使用help命令，或者参考命令说明文档，了解更多的命令及用法。

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.

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

用户也可通过 > help 具体命令 可以查看指令命令的具体使用方法。

命令执行过程中的常见错误信息和产生原因详见常见错误文档。

4.4. 设置Client日志输出

默认情况下，TcaplusDB Client会将日志输出到当前目录的client.log和client_NetThread*.log文件中，并且只输出INFO级别（INFO/WARN/ERROR/FATAL）以上的日志。

在某些场景下（如定位问题定位），用户可能需要自定义日志输出目录和日志输出级别，此时，用户可参考日志配置文件模板编辑日志配置文件，并通过tcaplus_client的-l参数指定使用的日志配置文件，注意：当前日志文件名只能为固定的client_log.xml。

4.4. 自定义二进制数据格式化输出插件

默认情况下，TcaplusDB Client会将二进进程数据以十六进制格式编码输出（如下图中的binary和single_struct字段），但也支持用户通过编写SO插件的方式，自定义二进制数据输出格式。

限制：目前仅支持对TDR表的一级binary类型字段和PB表的byte类型字段的二进行数据自定义输出格式。

用法：

1. 编写SO插件，如下所示，接口命名为ParseRecord，参数包括app_id、zone_id、table以及key和value，其中key map保存主键的字段名和值，value map保存非主键的字段名和值，解析之后的值也存在这两个map里面，log用于异常情况的报错提示。接口返回int类型，非0情况视为异常发生。

本例将single_struct字段和binary字段原本的十六进制格式输出，改为只输出字段内容的长度。

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. 编译SO文件。

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

1. 启动TcaplusDB Client时，通过-L参数指定SO文件路径。

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

1. 查询数据，查看输出

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