Connect to an OceanBase tenant by using OBClient

This topic describes how to connect to an Oracle tenant of OceanBase Database by using 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]

The options are described as follows:

• -h specifies the IP address for connecting to OceanBase Database. Replace $host with the actual IP address of the 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. $user_name can be in any of the following formats: 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 connecting to an OceanBase cluster by using ODP, you can obtain the cluster name in the following way:
    First, connect directly to OceanBase Database. Then, use the SHOW PARAMETERS LIKE 'cluster'; command to retrieve the name of the cluster. This command returns the name of the OceanBase cluster corresponding to the value of VALUE.
  • 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 is optional, which specifies that comments are not ignored in the runtime environment of OBClient.

  Note

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

• -A is optional, which specifies not to automatically retrieve the statistical information when OBClient connects to OceanBase Database.

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

• --proxy_user is optional, which specifies the username of the proxy user, that is, the target user name. 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

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]

The options are described as follows:

• -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. The format of $user_name is username@tenant name. 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 including 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 is optional, which specifies that comments are not ignored in the runtime environment of OBClient.

  Note

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

• -A is optional, which specifies not to automatically retrieve the statistical information when OBClient connects to OceanBase Database.

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

• --proxy_user is optional, which specifies the username of the proxy user, that is, the target user name. 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 by using OBClient.

   obclient -hxxx.xx.xxx.xxx -P2883 -usys@oracle001#test432 -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.3.2.0 (r200000272024061717-93c0ed73ebbcac6edbf7b585860b75d825935358) (Built Jun 17 2024 18:06:04)
   
   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.