Log in to an OceanBase tenant

OceanBase Database adopts the multi-tenant architecture. This architecture is suitable for scenarios such as resource consolidation and cloud services, and also reduces the complexity of O&M.

Starting from OceanBase Database 4.0, there are three types of tenants: the sys tenant, user tenants, and meta tenants corresponding to each user tenant.

Log in as the system tenant

The system tenant is a database instance in OceanBase Database that handles cluster-level tasks. Root Service, based on the system tenant, manages OceanBase Database, including cluster management, tenant management, resource management, load balancing, daily major compaction scheduling, and data migration and replication. The system tenant is the default tenant created for the cluster and is consistent with the cluster's lifecycle. It is responsible for managing the lifecycle of the cluster and all tenants.

The system tenant is compatible with MySQL mode and can be logged in using a MySQL client or OceanBase Client (OBClient).

Log in using a MySQL client

The following example shows how to connect to OceanBase Database using a MySQL client:

mysql -h<host IP> -P<port number> -u<username> -p<'database password'> -D<default database> -A -c --prompt "OceanBase(\u@\d)> "

Key parameters:

• -h: the IP address of the host where OceanBase Database is installed. OceanBase Database supports logging in through the ODP or directly connecting to an OBServer node. We recommend that you log in through the ODP. The ODP can better handle the distributed characteristics of OceanBase Database, including routing and disaster recovery.

• -P: the port number for logging in to OceanBase Database. OceanBase Database allows you to modify the port number in the configuration file during deployment. You can view the mysql_port parameter of each OBServer node and the listen_port parameter of the ODP in the configuration file. If you do not explicitly specify a port number, the default value is used.

  • When you log in through the ODP, the default port number is 2883.

  • When you directly connect to an OBServer node, the default port number is 2881.

• -u: the username for logging in to OceanBase Database. Unlike traditional databases, OceanBase Database usernames contain more fields, including the username, tenant name, and cluster name.

  • When you log in through the ODP, you need to specify the username, tenant name, and cluster name. The format is as follows: username@tenant name#cluster name, cluster name:tenant name:username, cluster name-tenant name-username, or cluster name.tenant name.username. For example, to log in as the root user to the SYS tenant in the test cluster, the username is root@sys#test.

  • When you directly connect to an OBServer node, you need to specify the username and tenant name. The format is username@tenant name. For example, to log in as the root user to the SYS tenant in the test cluster, the username is root@sys.

• -p: the password for logging in to OceanBase Database. For a newly created cluster, the initial password for the root user of the SYS tenant is empty. We recommend that you modify the root user password immediately after the cluster is created by executing the alter user root identified by '******' statement.

For more information about how to connect to OceanBase Database using a MySQL client, see Connect to OceanBase Database using a MySQL client.

Log in using OBClient

In addition to using a MySQL client, you can also use OceanBase Client (OBClient) to log in. OBClient is the recommended OceanBase Database CLI tool. Its users are compatible with those of a MySQL client. The database connection string is as follows:

obclient -h<host IP> -P<port number> -u<username> -p<'database password'> -D<default database> -A -c --prompt "OceanBase(\u@\d)> "

For more information about how to connect to OceanBase Database using OBClient, see Connect to OceanBase Database using OBClient.

Best practices

• The root user has extensive privileges. If it is arbitrarily distributed, it will pose a significant threat to database security. We recommend that you use the root user only for managing other users and creating dedicated maintenance users and read-only users that follow the "minimum necessary" principle.

• We recommend that you log in as a dedicated read-only user to view views.

  The biggest change in OceanBase Database 4.0 compared to previous versions is that internal information queries have been fully transitioned to views. You can view rich view information in OceanBase Database under the system tenant.

  obclient> use oceanbase
  
  obclient> show tables;
  +-------------------------------------------+
  | Tables_in_oceanbase                       |
  +-------------------------------------------+
  | CDB_INDEXES                               |
  | CDB_IND_COLUMNS                           |
  | CDB_IND_PARTITIONS                        |
  | CDB_IND_SUBPARTITIONS                     |
  | CDB_OBJECTS                               |
  | CDB_OB_ARCHIVELOG                         |
  | CDB_OB_ARCHIVELOG_PIECE_FILES             |
  ......
  

  These views are divided into two categories: data dictionary views and dynamic performance views.

  • Data dictionary views: These views are named with DBA_ and CDB_ as prefixes. Views starting with DBA_ display information within each tenant. For example, the DBA_OB_LS view displays log stream information within a tenant. The DBA_OB_LS table in the system tenant only displays log stream information for the system tenant. Views starting with CDB_ are exclusive to the system tenant and are used to view the database status of all tenants in the cluster. For example, the CDB_OB_LS view displays log stream information for all tenants in the cluster. Generally, each view starting with DBA_ has a corresponding view starting with CDB_ in the system tenant.

  • Dynamic performance views: These views are named with GV$ and V$ as prefixes. The V$ views display information only on the logged-in machine, while the GV$ views aggregate information from all machines of the tenant. OceanBase Database 4.0 has also added many dynamic performance views in regular tenants. For example, the GV$OB_UNITS view allows you to query unit distribution information for the current tenant. Dynamic performance views in the system tenant are specially handled and directly display aggregated information for all tenants in the cluster.

  For example, to view node information in an OceanBase cluster:

  obclient> use oceanbase
  Database changed
  

  obclient> select * from dba_ob_servers;
  

  The query result is as follows:

  +-------------+----------+----+--------------+----------+-----------------+--------+----------------------------+-----------+-----------------------+----------------------------+----------------------------+-------------------------------------------------------------------------------------------+-------------------+
  | SVR_IP      | SVR_PORT | ID | ZONE         | SQL_PORT | WITH_ROOTSERVER | STATUS | START_SERVICE_TIME         | STOP_TIME | BLOCK_MIGRATE_IN_TIME | CREATE_TIME                | MODIFY_TIME                | BUILD_VERSION                                                                             | LAST_OFFLINE_TIME |
  +-------------+----------+----+--------------+----------+-----------------+--------+----------------------------+-----------+-----------------------+----------------------------+----------------------------+-------------------------------------------------------------------------------------------+-------------------+
  | 6.x.xxx.xx  |     2882 |  6 | sa128_obv4_2 |     2881 | NO              | ACTIVE | 2025-12-30 16:17:03.173519 | NULL      | NULL                  | 2025-12-30 16:08:04.749100 | 2026-01-04 11:48:36.589270 | 4.5.0.0_200000012026020917-8b39902a3092ef10e5b05ec2240093e9443de5d2(Feb  9 2026 22:50:07) | NULL              |
  | 6.x.xxx.xx  |     2882 |  4 | sa128_obv4_3 |     2881 | NO              | ACTIVE | 2025-12-30 16:36:35.567437 | NULL      | NULL                  | 2025-12-30 16:08:02.755200 | 2026-01-04 14:13:36.976548 | 4.5.0.0_200000012026020917-8b39902a3092ef10e5b05ec2240093e9443de5d2(Feb  9 2025 22:50:07) | NULL              |
  | 6.x.xxx.xxx |     2882 |  3 | sa128_obv4_3 |     2881 | NO              | ACTIVE | 2025-12-12 12:42:00.054759 | NULL      | NULL                  | 2025-11-03 15:37:09.530894 | 2025-12-22 14:43:26.717736 | 4.5.0.0_200000012026020917-8b39902a3092ef10e5b05ec2240093e9443de5d2(Feb  9 2025 22:50:07) | NULL              |
  | 6.x.xx.xx   |     2882 |  1 | sa128_obv4_1 |     2881 | NO              | ACTIVE | 2025-12-12 12:25:17.555651 | NULL      | NULL                  | 2025-11-03 15:37:08.990683 | 2025-12-12 12:25:18.553763 | 4.5.0.0_200000012026020917-8b39902a3092ef10e5b05ec2240093e9443de5d2(Feb  9 2025 22:50:07) | NULL              |
  | 6.x.xx.xxx  |     2882 |  2 | sa128_obv4_2 |     2881 | YES             | ACTIVE | 2025-12-12 11:46:37.222980 | NULL      | NULL                  | 2025-11-03 15:37:09.490511 | 2025-12-12 11:47:31.075335 | 4.5.0.0_200000012026020917-8b39902a3092ef10e5b05ec2240093e9443de5d2(Feb  9 2025 22:50:07) | NULL              |
  | 6.x.xx.xx   |     2882 |  5 | sa128_obv4_1 |     2881 | NO              | ACTIVE | 2025-12-30 16:25:45.420996 | NULL      | NULL                  | 2025-12-30 16:08:03.928478 | 2026-01-04 11:48:36.578231 | 4.5.0.0_200000012026020917-8b39902a3092ef10e5b05ec2240093e9443de5d2(Feb  9 2026 22:50:07) | NULL              |
  +-------------+----------+----+--------------+----------+-----------------+--------+----------------------------+-----------+-----------------------+----------------------------+----------------------------+-------------------------------------------------------------------------------------------+-------------------+
  6 rows in set
  

• We recommend that you execute cluster management commands as a dedicated maintenance user.

  You can execute cluster management commands through the system tenant. For example, you can isolate an abnormal node:

  obclient> ALTER SYSTEM STOP SERVER 'xx.xx.xx.xx:2882';
  

  After the command is successfully executed, you can check the STOP_TIME field in the DBA_OB_SERVERS view for the corresponding node to confirm whether the isolation was successful.

Log in to a user tenant

A user tenant is a tenant created by a user. It provides complete database features and supports MySQL and Oracle compatibility modes.

To view the information of all tenants, log in to the sys tenant and query the DBA_OB_TENANTS view.

• The TENANT_TYPE column indicates the type of the tenant. SYS indicates the sys tenant, META indicates the meta tenant, and USER indicates the user tenant. The sys tenant has a tenant ID of 1. For a tenant with a tenant ID greater than 1000, if the tenant ID is even, the tenant is a user tenant; if the tenant ID is odd, the tenant is a meta tenant. The tenant ID of a user tenant is 1 greater than that of its corresponding meta tenant.

• The COMPATIBILITY_MODE column indicates the compatibility mode of the tenant. MYSQL indicates the MySQL compatibility mode, and ORACLE indicates the Oracle compatibility mode.

To log in to a user tenant in MySQL compatibility mode, you can use the MySQL client or the OBClient. To log in to a user tenant in Oracle compatibility mode, you can use the OBClient only. The login method is the same as that for the sys tenant, except that the tenant name in the login account must be changed to the name of the target tenant.

In a user tenant in MySQL compatibility mode, the system data dictionary views and dynamic performance views of OceanBase Database are in the oceanbase namespace. In a user tenant in Oracle compatibility mode, the system views of OceanBase Database are in the SYS user. In both modes, the names, fields, and usage experience of the views of OceanBase Database are consistent.

Log in to a meta tenant

A meta tenant is an internal tenant of OceanBase Database. When a user tenant is created, a corresponding meta tenant is also created. The lifecycle of a meta tenant is consistent with that of its corresponding user tenant. You cannot log in to a meta tenant directly. You can access the information of a meta tenant from a user tenant or the sys tenant.

References

For more information about how to connect to and access OceanBase Database, see:

• Connect to OceanBase Database in MySQL mode

• Connect to OceanBase Database in Oracle mode