Quick start with OceanBase Database Community Edition

This topic helps you quickly explore OceanBase Database Community Edition through three deployment scenarios: setting up a demo environment, deploying an OceanBase cluster, and using a container environment.

Background information

Starting from V4.0.0, OceanBase Database provides a unified all-in-one package for installing OceanBase Deployer (obd), OceanBase Database, OceanBase Database Proxy (ODP), OceanBase Agent (OBAgent), Grafana, and Prometheus. As of V4.1.0, OceanBase Cloud Platform (OCP) Express is incorporated into the package. You can choose the components to install based on your needs.

Components

• obd

  obd is a tool for installing and deploying OceanBase Database. For more information, see obd Documentation.

• ODP

  ODP, also known as OBProxy, is a dedicated proxy server for OceanBase Database. For more information, see ODP Documentation.

• OCP Express

  OCP Express is a web-based management tool for OceanBase Database V4.x. Integrated with an OceanBase cluster, OCP Express allows you to view key performance metrics of the cluster and perform basic database management operations on the cluster. For more information, see OCP Express.

• OBAgent

  OBAgent is a framework for data monitoring and collection in OceanBase Database. The framework supports both pushing and pulling modes for data collection in different scenarios.

• Grafana

  Grafana is an open-source data visualization tool that visualizes various metrics in data sources to help you understand the system running status and performance. For more information, visit the official website of Grafana.

• Prometheus

  Prometheus is an open-source service monitoring system and time series database. It provides common data models and APIs for fast data collection, storage, and query. For more information, visit the official website of Prometheus.

Deployment solutions

To help you quickly get started with OceanBase Database, we offer three different deployment solutions. You can select the most suitable one based on your specific environment.

• Solution 1: Deploy OceanBase Database in a demo environment

  If you have only one server, you can quickly build a demo environment to deploy OceanBase Database. The demo database provides basic features for you to quickly learn about OceanBase Database, but does not support distributed capabilities or high availability. Therefore, long-term use is not recommended. For more information, see Solution 1: Deploy OceanBase Database in a demo environment.

• Solution 2: Deploy OceanBase Database in a cluster

  You can choose this solution if you want to learn more about the distributed architecture and features of OceanBase Database. The cluster provides distributed capabilities and high availability apart from complete database features. To use this solution, you must have three hosts, each of which has four CPU cores, 10 GB of memory, and 50 GB of disk space. For more information, see Solution 2: Deploy OceanBase Database in a cluster.

• Solution 3: Deploy OceanBase Database in a container

  You can choose this solution if you want to deploy and manage OceanBase Database in a container. This solution has not been verified by large-scale practices and therefore is not recommended. For more information, see Solution 3: Deploy OceanBase Database in a container.

Prerequisites

Your software and hardware environments meet the following requirements.

Solution 1: Deploy OceanBase Database in a demo environment

If you have only one server available, you can run the obd demo command to quickly deploy a standalone OceanBase database by following the procedure described in this section.

Step 1: Download and install the all-in-one package

1. Download the latest all-in-one package from OceanBase Download Center and upload it to any directory on your server.

2. In the directory where the package is located, run the following commands to decompress and install the package:

   [admin@test001 ~]$ tar -xzf oceanbase-all-in-one-*.tar.gz
   [admin@test001 ~]$ cd oceanbase-all-in-one/bin/
   [admin@test001 bin]$ ./install.sh
   [admin@test001 bin]$ source ~/.oceanbase-all-in-one/bin/env.sh
   

Step 2: Deploy OceanBase Database on a single server

1. Run the following command to deploy OceanBase Database:

   [admin@test001 ~]$ obd demo
   

   By default, the obd demo command deploys OceanBase Database and its components with minimum specifications in the home directory on your server and then starts them. The components include ODP, OBAgent, Grafana, and Prometheus. The name of the deployed cluster is fixed to demo. For more information about custom deployment, see Quick deployment command.

   You can use obd commands to manage OceanBase Database. For more information about the commands, see Cluster commands.

   Note

   If you install Grafana or Prometheus, its access address is returned in the command output. On Alibaba Cloud or in other cloud environments, an intranet IP address may be returned in the case of a failure to obtain a public IP address. You must use a correct public IP address.

2. Run the connection command returned in the output to connect to the database.

   After the obd demo command succeeds, you will find the command for connecting to OceanBase Database through OceanBase Client (OBClient). Here are two examples:

   • Directly connect to the database through port 2881

     [admin@test001 ~]$ obclient -h127.0.0.1 -P2881 -uroot@sys -Doceanbase -A
     

   • Connect to the database in proxy mode through ODP

     [admin@test001 ~]$ obclient -h127.0.0.1 -P2883 -uroot@sys -Doceanbase -A
     

   For detailed instructions on how to connect to an OceanBase cluster using the OBClient client, see Connect to an OceanBase tenant by using OBClient. For more information about how to connect to OceanBase Database, see Overview of connection methods.

3. (Optional) Configure the password.

   After you deploy OceanBase Database by using the obd demo command, you can follow the steps below to configure a password for the demo cluster.

   1. Modify the configuration file.

      obd cluster edit-config demo
      

      After you execute the above command to open the configuration file, add root_password: xxxx under the oceanbase-ce component in the configuration file. Then save the file and exit. Here is an example:

      oceanbase-ce:
        servers:
          - 127.0.0.1
        global:
          home_path: /home/admin/oceanbase-ce
          ... # Some parameters are omitted here.
          log_disk_size: 13G
          root_password: ******
      

   2. Restart the cluster.

      After you modify and save the configuration file, obd will output the restart command. You can directly copy and execute it. Here is an example:

      [admin@test001 ~]$ obd cluster edit-config demo
      Search param plugin and load ok
      Search param plugin and load ok
      Parameter check ok
      Save deploy "demo" configuration
      Use `obd cluster reload demo` to make changes take effect.
      Trace ID: 29dd12fa-3d73-11ee-91bc-00163e01cd7a
      If you want to view detailed obd logs, please run: obd display-trace 29dd12fa-3d73-11ee-91bc-00163e01cd7a
      

      The output shows that you must run the obd cluster reload demo command to restart the demo cluster after you modify the password for the root@sys user in the configuration file.

Solution 2: Deploy OceanBase Database in a cluster

If you have multiple servers available, you can run the obd web command to start the GUI of obd and deploy a distributed OceanBase cluster on the GUI.

Step 1: Download and install the all-in-one package

1. Download the latest all-in-one package from OceanBase Download Center and upload it to any directory on your server.

2. In the directory where the package is located, run the following commands to decompress and install the package:

   [admin@test001 ~]$ tar -xzf oceanbase-all-in-one-*.tar.gz
   [admin@test001 ~]$ cd oceanbase-all-in-one/bin/
   [admin@test001 bin]$ ./install.sh
   [admin@test001 bin]$ source ~/.oceanbase-all-in-one/bin/env.sh
   

Step 2: Deploy OceanBase Database on the GUI

1. Run the obd web command on the CLI to start the GUI of obd. Visit the URL in the output and click Try Now on the page displayed to start deployment.

   [admin@test001 ~]$ obd web
   start OBD WEB in 0.0.0.0:8680
   please open http://172.xx.xxx.233:8680
   

   Note

   • The default port in the URL is 8680. You can use the obd web -p <PORT> command to specify a port.

   • On Alibaba Cloud or other cloud environments, the program may fail to obtain a public IP address but return an intranet IP address. You must use a correct public IP address to access the GUI.

   • The obd web command is bound to 0.0.0.0. In a deployment where multiple network interface cards (NICs) are used, you can access the GUI through any accessible IP address.

2. On the Deployment Configuration page, modify Cluster Name and select the components that you want to deploy. You can also retain the default configurations. By default, all components are deployed. Click Next Step to go to the Node Configuration page.

   

3. On the Node Configuration page, enter node IP addresses and the user password and then click Next Step to go to the Cluster Configuration page.

   

4. On the Cluster Configuration page, specify the deployment mode, password, directory, port, and other information about the cluster. You can also retain the default values. Click Next Step to go to the Pre-check page.

   

5. On the Pre-check page, verify the configuration information and then click Pre-check. If an error code is returned, you can click Auto repair to automatically repair the error, or click Learn more to go to the error code document and correct the error based on the reference document. After all the errors are fixed, click Re-check to perform a pre-check again.

   

6. After the pre-check is passed, click Deploy to start the deployment. If the deployment is successful, the connection strings of the components are displayed. You can copy a connection string to access the corresponding component.

   

7. Click Finish.

8. Connect to OceanBase Database from OBClient or log in to the GUI of OCP Express to manage the cluster.

   For more information about how to connect to OceanBase Database from OBClient, see Connect to an OceanBase tenant by using OBClient. For other connection methods, see Overview.

   • Directly connect to the OBServer node 10.10.10.1 of the database through port 2881.

     [admin@test001 ~]$ obclient -h10.10.10.1 -P2881 -uroot@sys -p -Doceanbase -A
     

   • Connect to the database in proxy mode through the ODP node 10.10.10.1.

     [admin@test001 ~]$ obclient -h10.10.10.1 -P2883 -uroot@sys -p -Doceanbase -A
     

Solution 3: Deploy OceanBase Database in a container

You can deploy OceanBase Database in a Docker container to quickly get started with OceanBase Database.

(Optional) Step 1: Pull the image of OceanBase Database

Run the following commands to pull the image needed by OceanBase Database.

• Search for images related to OceanBase Database.

  [admin@test001 ~]$ sudo docker search oceanbase
  

• Pull the latest image of OceanBase Database.

  [admin@test001 ~]$ sudo docker pull oceanbase/oceanbase-ce
  

  Note

  • If pulling the Docker image fails, you can also fetch it from the quay.io or ghcr.io repository. To do so, you only need to replace oceanbase/oceanbase-ce in the preceding command with quay.io/oceanbase/oceanbase-ce or ghcr.io/oceanbase/oceanbase-ce. For example, you can run sudo docker pull quay.io/oceanbase/oceanbase-ce to pull the Docker image from the quay.io repository.

  • Once you change the repository address in this step, make sure to update the repository address in Step 2 as well. Both commands need to use the same repository.

  • By default, the preceding command pulls the latest version of the Docker image. You can select a desired image from Docker Hub, quay.io, or ghcr.io.

Step 2: Start an OceanBase Database instance

Run either of the following commands to start an OceanBase Database instance.

• Deploy an instance with the maximum specifications supported by the container.

  [admin@test001 ~]$ sudo docker run -p 2881:2881 --name obstandalone -e MODE=NORMAL -e OB_TENANT_PASSWORD=***** -d oceanbase/oceanbase-ce
  

• Deploy a mini standalone instance.

  [admin@test001 ~]$ sudo docker run -p 2881:2881 --name obstandalone -e MODE=MINI -e OB_TENANT_PASSWORD=***** -d oceanbase/oceanbase-ce
  

where:

• --name specifies the name of the Docker container, such as obstandalone in the preceding examples.

• -e specifies the environment variables. Here, MODE specifies the deployment specifications of OceanBase Database and OB_TENANT_PASSWORD specifies the password of the root@sys user in OceanBase Database. For more information, see the Supported environment variables section.

The startup is expected to take 2 to 5 minutes. Run the following command, and if it returns boot success!, the startup was successful.

[admin@test001 ~]$ sudo docker logs obstandalone | tail -1
boot success!

Step 3: Connect to the OceanBase Database instance

The oceanbase-ce image includes obd and OBClient. You can enter the container and use obd commands to manage an OceanBase Database instance or use OBClient to connect to the instance. You can also connect to an OceanBase Database instance from the host by using the local OBClient or MySQL client.

Enter the container and then connect to the instance

1. Enter the Docker container.

   [admin@test001 ~]$ sudo docker exec -it obstandalone bash
   

2. View cluster details.

   # View the cluster list.
   obd cluster list
   # View the details of the obcluster cluster.
   obd cluster display obcluster
   

3. Connect to the cluster.

   obclient -h127.0.0.1 -uroot@sys -A -Doceanbase -P2881 -p
   

Connect to the instance from the host by using a local client

You can connect to an OceanBase instance from the host by using the local OBClient or MySQL client. Here is an example:

[admin@test001 ~]$ obclient -uroot@sys -h127.1 -P2881 -p

After the connection is established, the following information is displayed:

Welcome to the OceanBase.  Commands end with ; or \g.
Your OceanBase connection id is 3221711319
Server version: OceanBase_CE 4.3.0.1 (r100000242024032211-0193a343bc60b4699ec47792c3fc4ce166a182f9) (Built Mar 22 2024 13:19:48)

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 [(none)]>

Supported environment variables

References

For more information about how to deploy OceanBase Database Enterprise Edition, see Deployment process.