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, OCP Express is incorporated into the package. You can choose to install components 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 (which are ODP, OBAgent, Grafana, and Prometheus) with minimum specifications and then starts them in the home directory of the current user. The name of the deployed cluster is fixed to demo in obd. 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 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.

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

   After the obd demo command is executed successfully, you will find the command to connect to OceanBase Database via OBClient. The examples are as follows:

   • 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 using the obd demo command, you can follow the steps below to configure the 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 and exit. The following 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 that needs to be executed. You can directly copy and execute it. The following 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
      

      As we can see in the output, after you modify the password for the root@sys user in the configuration file, you need to execute the obd cluster reload demo command to restart the demo cluster.

Solution 2: Deploy an OceanBase 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 in your 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 the case of multi-NIC deployment, 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 server IP addresses and the 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 repair the error by referring to the error code document. After all the errors are repaired, 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 Complete.

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

   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.

   • 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. Just replace oceanbase/oceanbase-ce in the command with quay.io/oceanbase/oceanbase-ce or ghcr.io/oceanbase/oceanbase-ce. For example, use sudo docker pull quay.io/oceanbase/oceanbase-ce to pull the image from quay.io.

  • 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 command pulls the latest version. You can select a specific version based on your needs 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 is used to set the Docker container name. For example, the command creates a Docker container named obstandalone.

• -e is used to set environment variables. Here, MODE specifies the deployment specification for OceanBase Database, and OB_TENANT_PASSWORD specifies the password for the root@test user in OceanBase Database.

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 have the option to either enter the container and utilize the obd commands and OBClient to manage and connect to the instance, or connect to the OceanBase Database instance from your host machine using a local OBClient or a MySQL client.

Connect to the instance after entering the container

1. Enter the Docker container.

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

2. View cluster details.

   # View the list of clusters
   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 using the local host

You can use the host's local OBClient or MySQL client to connect to the OceanBase Database instance, as shown below:

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

Upon a successful connection, your terminal will display the following message:

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)]>

References

To learn more about deploying the Enterprise Edition of OceanBase Database, see Deploy OceanBase Enterprise Edition.