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 it 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

The following command is used 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 parameters are described as follows:

• -h: the IP address for connecting to OceanBase Database. Replace $host with the actual IP address. When connecting to an OceanBase cluster via ODP, use the IP address of the ODP.

• -P: the port for connecting to OceanBase Database. Replace $port with the actual port. When connecting to OceanBase Database via ODP, the default value is 2883. The port can be customized when ODP is deployed.

• -u: the account for connecting to OceanBase Database. Here, $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 via ODP, you can use the following method to obtain the cluster name:
    First, connect directly to OceanBase Database. Then, use the SHOW PARAMETERS LIKE 'cluster'; command to retrieve the name of the cluster. This command will return 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 you connect to it. If ODP works for only one cluster, you do not need to specify the cluster name when you connect to it.

• -p: the 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 command line, 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 that comments must not be ignored in the runtime environment of OBClient.

  Note

  Hint is a special comment that is not affected by the -c option.

• -A: specifies that the statistics are not automatically retrieved when you connect to a database through OBClient. This parameter is optional.

• $schema_name: the name of the default schema to be used after you connect to OceanBase Database. If not specified, the connection will default to the schema associated with the logged-in user. This parameter is optional.

• --proxy_user: the username being proxied, that is, the target username. This parameter is optional. For more examples on using proxy users, see Use a proxy user.

Here is an example:

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

Connect to OceanBase Database by using SERVICE_NAME

You can also log in to OceanBase Database by using IP:PORT and SERVICE_NAME. ODP will convert the SERVICE_NAME into -uuser_name@primary tenant name#cluster of primary tenant, so that you do not need to manually change the connection string after a primary/standby switchover. For more information about how to create a SERVICE_NAME, see Create a service.

The following command is used to connect to OceanBase Database by using SERVICE_NAME:

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

The parameters are described as follows:

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

Here is an example:

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

Connect to OceanBase Database directly

The following command is used to connect to OceanBase Database directly:

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

The parameters are described as follows:

• -h: the IP address for connecting to OceanBase Database. Replace $host with the actual IP address, which is typically the IP address of an OBServer node when connecting OceanBase Database directly.

  Notice

  When you connect to a user tenant directly, make sure that the resources of the tenant are distributed on the OBServer node you specified. Otherwise, you cannot connect to the tenant by using this OBServer node.

• -P: the port for connecting to OceanBase Database. Replace $port with the actual port. The default value is 2881 when you connect to OceanBase Database directly, which can be customized when OceanBase Database is deployed.

• -u: the 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 connect to OceanBase Database directly, 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 include the cluster name in -u, a connection error will occur.

• -p: the password for connecting to OceanBase Database. Replace ****** with the actual password string.

  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 that comments must not be ignored in the runtime environment of OBClient. This parameter is optional.

  Note

  Hint is a special comment that is not affected by the -c option.

• -A: specifies that the statistics are not automatically retrieved when you connect to a tenant through OBClient.

• $schema_name: the name of the default schema to be used after you connect to OceanBase Database. If not specified, the connection will default to the schema associated with the logged-in user. This parameter is optional.

• --proxy_user: the username being proxied, that is, the target username. This parameter is optional. For more examples on using proxy users, 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. Use OBClient to connect to an Oracle tenant of OceanBase Database by using ODP.

   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 the OBClient command line, enter exit and press Enter, or press the shortcut key Ctrl + D.

References

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