Connect to an OceanBase tenant by using OBClient

This topic describes how to connect to an Oracle tenant of OceanBase Database by using OceanBase Client (OBClient).

Prerequisites

• OBClient is downloaded and installed. If OBClient is not downloaded, download the required version from OceanBase Download Center.

• The client is in the allowlist of the tenant. For more information about how to query and configure a tenant allowlist, see View and set a tenant allowlist.

Procedure

Connect to OceanBase Database by using ODP

Run the following command to connect to OceanBase Database from OBClient by using OceanBase Database Proxy (ODP):

obclient -h$host -P$port -u$user_name -p****** [-c] [-A] [$schema_name] [--proxy_user[=]user_name]

where:

• -h specifies the IP address for connecting to OceanBase Database. Replace $host with the actual IP address of ODP used for connection.

• -P specifies the port for connecting to OceanBase Database. Replace $port with the port customized when ODP is deployed. The default value is 2883.

• -u specifies the tenant account for connecting to OceanBase Database. The following account formats are supported: username@tenant name#cluster name, cluster name:tenant name:username, cluster name-tenant name-username, and cluster name.tenant name.username. The default username of the administrator of an Oracle tenant is sys.

  Note

  • When you use ODP to connect to an OceanBase cluster, you can obtain the cluster name in the following way:
    Directly connect to OceanBase Database and execute the SHOW PARAMETERS LIKE 'cluster'; statement to query the cluster name. In the query result, VALUE indicates the name of the OceanBase cluster.
  • If ODP works for multiple clusters, you must specify the cluster name when connecting to it. If ODP works for only one cluster, you do not need to specify the cluster name when connecting to it.

• -p specifies the account password for connecting to OceanBase Database. Replace ****** with the actual password.

  Note

  For security purposes, we recommend that you do not directly enter the password on the CLI, especially in an environment where the script or historical records are visible. You can skip this option and enter the password when being prompted to.

• -c specifies not to ignore comments in the runtime environment of OBClient. This parameter is optional.

  Note

  Hints are special comments that are not affected by the -c option.

• -A specifies not to automatically retrieve the statistical information when you use OBClient to connect to OceanBase Database. This parameter is optional.

• $schema_name specifies the default schema to be used after the connection to OceanBase Database is established. This parameter is optional. If this option is not specified, the schema of the currently logged-in user is accessed.

• --proxy_user specifies the name of the target user corresponding to the proxy user. This parameter is optional. For more information about how to use a proxy user, see Use a proxy user.

Here is an example:

obclient -h10.10.10.1 -P2883 -uuser001@obtenant#obdemo -p****** -c -A test_user001

Specify SERVICE_NAME of ODP to connect to OceanBase Database

You can specify IP:PORT and SERVICE_NAME of ODP to connect to OceanBase Database. ODP converts the connection string into the format of -uuser_name@name of the primary tenant#name of the cluster where the primary tenant resides based on the specified SERVICE_NAME. You do not need to manually modify the connection string after a primary/standby switchover. For more information about the SERVICE_NAME parameter, see Create a service.

Run the following command to connect to OceanBase Database by using ODP based on SERVICE_NAME:

obclient -h$host -P$port -u$user_name@SERVICE:$service_name -p******

where:

• $host specifies the IP address of ODP.
• $port specifies the port number of ODP.
• $user_name specifies the username.
• $service_name specifies the service name.
• -p specifies the account password for connecting to OceanBase Database. Replace ****** with the actual password.

Here is an example:

obclient -h10.10.10.1 -P2883 -uuser001@SERVICE:service_oracle001 -p******

Directly connect to OceanBase Database

Run the following command to directly connect to OceanBase Database from OBClient:

obclient -h$host -P$port -u$user_name -p****** [-c] [-A] [$schema_name] [--proxy_user[=]user_name]

where:

• -h specifies the IP address for connecting to OceanBase Database. Replace $host with the actual IP address of the OBServer node for direct connection.

  Notice

  When you use the direct connection method, make sure that the tenant resources are distributed on the OBServer node you specified. Otherwise, you cannot connect to the tenant by using this OBServer node.

• -P specifies the port for connecting to OceanBase Database. Replace $port with the port customized when OceanBase Database is deployed. The default value is 2881.

• -u specifies the tenant account for connecting to OceanBase Database, which is in the username@tenant name format. The default username of the administrator of an Oracle tenant is sys.

  Notice

  When you directly connect to OceanBase Database, enter the username and tenant name in the format of username@tenant name for the connection parameter -u and do not specify the cluster name. If you specify the cluster name in -u, a connection error is returned.

• -p specifies the account password for connecting to OceanBase Database. Replace ****** with the actual password.

  Note

  For security purposes, we recommend that you do not directly enter the password on the CLI, especially in an environment where the script or historical records are visible. You can skip this option and enter the password when being prompted to.

• -c specifies not to ignore comments in the runtime environment of OBClient. This parameter is optional.

  Note

  Hints are special comments that are not affected by the -c option.

• -A specifies not to automatically retrieve the statistical information when you use OBClient to connect to OceanBase Database. This parameter is optional.

• $schema_name specifies the default schema to be used after the connection to OceanBase Database is established. This parameter is optional. If this option is not specified, the schema of the currently logged-in user is accessed.

• --proxy_user specifies the name of the target user corresponding to the proxy user. This parameter is optional. For more information about how to use a proxy user, see Use a proxy user.

Here is an example:

obclient -h10.10.10.1 -P2881 -uuser001@obtenant -p****** -c -A test_user001

Connection example

1. Open a command-line terminal.

2. Run the following command to connect to an Oracle tenant of OceanBase Database from OBClient by using ODP.

   obclient -hxxx.xx.xxx.xxx -P2883 -usys@oracle001#test424 -p****** -A test_user001
   

   The return result is as follows:

   Welcome to the OceanBase.  Commands end with ; or \g.
   Your OceanBase connection id is 21
   Server version: OceanBase 4.2.4.0 (r200000342024061210-c4c0c18741e45a1d40889b6147c3132574d6e7ea) (Built Jun 12 2024 10:58:58)
   
   Copyright (c) 2000, 2018, OceanBase and/or its affiliates. All rights reserved.
   
   Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
   
   obclient [TEST_USER001]>
   

3. To exit OBClient, enter exit and press Enter, or press the keyboard shortcut Ctrl + D.

References

For information about how to connect to a MySQL tenant of OceanBase Database by using OBClient, see Connect to an OceanBase tenant by using OBClient.