Use the OBKV-Table Go client to connect to a cluster

This topic describes how to create a Go client instance. For more information about the Go client, visit GitHub wiki.

Preparations

Before using the OBKV-Table client to connect to the OBKV-Table cluster for data processing, ensure that you have completed the following work:

• Deployed an OceanBase cluster. For supported deployment plans, deployment methods, and detailed deployment procedures, see Deployment overview.

• Created a MySQL tenant. For detailed instructions on creating a tenant, refer to Create a tenant.

• Created a database. For detailed instructions on creating a database, refer to Create a database.

• Created an OBKV-Table data table. For detailed instructions on creating an OBKV-Table data table, refer to OBKV-Table data models.

Below is a table creation example:

CREATE TABLE IF NOT EXISTS `test` (
    `c1` bigint(20) NOT NULL,
    `c2` bigint(20) NOT NULL,
    PRIMARY KEY (`c1`)
) PARTITION BY KEY(`c1`) PARTITIONS 10;

Import the obkv-table-client-go dependency

Run the following command on the local Go repository to obtain the obkv-table-client-go dependency of the latest version or a specified version:

go get github.com/oceanbase/obkv-table-client-go

Connect the Go client to an OBServer node

You can connect the Go client to an OBServer node in either of the following modes:

• Direct connection mode: use a config server

• OceanBase Database Proxy (ODP) mode

You can create a Go client from code or a .toml file on an OBServer node.

Direct connection mode

The syntax is as follows:

func NewClient(
    configUrl string,
    fullUserName string,
    password string,
    sysUserName string,
    sysPassWord string,
    cliConfig *config.ClientConfig) (Client, error) {

Input parameters:

• configUrl: the URL for obtaining the RootServer list from the config server.
• fullUserName: the full username, in the format of userName@tenantName#clusterName.
• passWord: the password of the user specified by userName in fullUserName for accessing OceanBase Database.
• sysUserName: the username of the user in the sys tenant. Only users in the sys tenant have privileges to access the routing table.
• sysPassWord: the password of the user in the sys tenant.
• cliConfig: the client configurations. For more information, see config.ClientConfig.

Response parameters:

• Client: the client API, which contains insert, get, update, and other methods.
• error: the error message.

ODP mode

The syntax is as follows:

func NewOdpClient(
    fullUserName string,
    passWord string,
    odpIP string,
    odpRpcPort int,
    database string,
    cliConfig *config.ClientConfig) (Client, error)

Input parameters:

• fullUserName: the full username, in the format of userName@tenantName#clusterName.
• passWord: the password of the user specified by userName in fullUserName for accessing OceanBase Database.
• odpIP: the IP address of ODP.
• odpRpcPort: the RPC port number of ODP.
• database: the name of the database to connect to.
• cliConfig: the client configurations. For more information, see config.ClientConfig.

Response parameters:

• Client: the client API, which contains insert, get, update, and other methods.
• error: the error message.

.toml file configurations

The obkv-table-default.toml file is stored in the /configurations directory.

You can choose to specify the parameters in the Direct mode or ODP mode section in the .toml file. For more information about other parameters, see config.ClientConfig.

The syntax is as follows:

func NewClientWithTomlConfig(configFilePath string) (Client, error)

Input parameter:

• configFilePath: the path of the .toml file.

Response parameters:

• Client: the client API, which contains insert, get, update, and other methods.
• error: the error message.

ClientConfig

The syntax is as follows:

type ClientConfig struct {
    ConnPoolMaxConnSize int
    ConnConnectTimeOut  time.Duration
    ConnLoginTimeout    time.Duration
    OperationTimeOut    time.Duration
    LogLevel            log.Level

    TableEntryRefreshLockTimeout     time.Duration
    TableEntryRefreshTryTimes        int
    TableEntryRefreshIntervalBase    time.Duration
    TableEntryRefreshIntervalCeiling time.Duration

    MetadataRefreshInterval    time.Duration
    MetadataRefreshLockTimeout time.Duration

    RsListLocalFileLocation    string
    RsListHttpGetTimeout       time.Duration
    RsListHttpGetRetryTimes    int
    RsListHttpGetRetryInterval time.Duration

    EnableRerouting bool
}

The special parameters are described as follows:

• ConnPoolMaxConnSize: the number of connections in the connection pool. The default value is 1.
• ConnConnectTimeOut: the timeout period for a TCP connection. The default value is 1s.
• ConnLoginTimeout: the timeout period for an authentication operation. The default value is 1s.
• OperationTimeOut: the timeout period for a single request. The default value is 10s.
• EnableRerouting: specifies whether to enable rerouting. By default, rerouting is disabled.