Try out OceanBase Database Community Edition

This topic will guide you through deploying OceanBase Database Community Edition in a demo environment, in a cluster, and in a container, to help you quickly get started with OceanBase Database.

Background information

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

Component overview

• obd

  OceanBase Deployer, the installation and deployment tool for OceanBase Database, is commonly referred to as obd. For more information, see obd Documentation.

• ODP

  OceanBase Database Proxy (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 4.x that is integrated with an OceanBase cluster. It allows you to view key performance metrics of the cluster and perform basic database management operations on the cluster. For more information, see OceanBase Cloud Platform Express (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.

Overview

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 has 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 OceanBase cluster has distributed capabilities and high availability in addition to complete database features. To use this solution, you need to 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

Before installing OceanBase Database, make sure your software and hardware environments meet the following requirements:

Solution 1: Deploy OceanBase Database in the demo environment

If you have only one server available, you can use the obd demo command to deploy OceanBase Database in standalone mode.

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 in the home directory on your server and then starts them. The name of the deployed cluster is fixed to demo in obd. If you want 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 need to 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 for connecting 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 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 in the configuration file 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. 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 OceanBase Database in a cluster

If you have multiple servers available, you can use the obd web interface to deploy a distributed OceanBase cluster.

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 using the GUI

1. Run the obd web command to start the GUI, then log in to the GUI by using the output address and click Start your OceanBase Database deployment experience to begin the deployment.

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

   Note

   • The GUI uses port 8680 by default. You can use the obd web -p <PORT> command to specify a different port.

   • On Alibaba Cloud or in 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 multi-NIC deployment, you can use any accessible IP address to access the GUI.

2. On the Deployment Configuration page, modify the Cluster Name and select the components to deploy. If you do not modify the parameters, the default values will be used (all components are deployed by default). Click Next to go to the Node Configuration page.

   

3. On the Node Configuration page, enter the IP address and user password of the node, and click Next to go to the Cluster Configuration page.

   

4. On the Cluster Configuration page, configure the deployment mode, password, directory, port, and other parameters of the cluster. If you do not modify the parameters, the default values will be used. Click Next to go to the Pre-check page.

   

5. On the Pre-check page, check the configuration information. If everything is correct, click Pre-check to perform the precheck. If an error occurs during the precheck, you can choose Auto Repair on the page or click More Solutions to jump to the error code topic in the documentation for self-modification. After all modifications are completed, click Recheck to perform the precheck again.

   

6. After the precheck is completed, click Deploy to deploy the OceanBase cluster. The connection methods of the components are displayed in the console after the deployment is successful. You can copy and use them to access the components.

   

7. Click Complete to end the deployment process.

8. Connect to the OceanBase Database using the OBClient client or manage the cluster using the OCP Express GUI.

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

   • Directly connect to the database on port 2881, for example, to connect to the node with the IP address of 10.10.10.1

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

   • Connect to the database with ODP as the proxy, for example, if the ODP node is 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 start OceanBase Database in a Docker container to quickly learn about OceanBase Database.

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

Run the following commands to pull the image of 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

  By default, the preceding command pulls the latest version of Docker image. You can select a desired image from Docker images as needed.

Step 2: Start an OceanBase Database instance

Run the following command to start an OceanBase Database instance.

[admin@test001 ~]$ sudo docker run -p 2881:2881 -v $PWD/ob:/root/ob -v $PWD/obd/cluster:/root/.obd/cluster --name obstandalone -e MODE=NORMAL -d oceanbase/oceanbase-ce

[admin@test001 ~]$ sudo docker run -p 2881:2881 -v $PWD/ob:/root/ob -v $PWD/obd/cluster:/root/.obd/cluster --name obstandalone -e MODE=MINI -d oceanbase/oceanbase-ce

[admin@test001 ~]$ sudo docker run -p 2881:2881 -v $PWD/ob:/root/ob -v $PWD/obd/cluster:/root/.obd/cluster --name obstandalone -e MODE=SLIM -d oceanbase/oceanbase-ce

The options in the example are described as follows:

• -p is used to map a port of the container to a port on the host. In the example, port 2881 of the container is mapped to port 2881 on the host.

• -v is used to share files or directories between the container and the host for data persistence or configuration sharing. By default, the system deploys OceanBase Database in the /root/ob directory of the container and saves its configuration in the /root/.obd/cluster directory. You can use the -v option to persist data on the host.

  You can also use the -v option to mount an SQL script for execution. Remember to modify {init_sql_folder_path} in the following example to the actual file path of the initialization script.

  [admin@test001 ~]$ sudo docker run -p 2881:2881 -v {init_sql_folder_path}:/root/boot/init.d --name obstandalone -e MODE=SLIM -d oceanbase/oceanbase-ce
  

• --name is used to set the Docker container name, such as obstandalone in the example.

• -e is used to set environment variables. In the example, the MODE variable is used to set the startup mode of OceanBase Database. For more information about the environment variables, see [Configurable environment variables](#Configurable environment variables).

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 OceanBase Deployer (obd) and OceanBase Client (OBClient). You can either enter the container and use the obd commands and OBClient to manage and connect to the instance, or you can connect to the OceanBase Database instance from your host machine using a local OBClient or a MySQL client.

Connect to the instance after you enter 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 from your host machine

You can connect to the OceanBase Database instance from your host machine using a local OBClient or a MySQL client. Here is an example of connecting to the instance using a local OBClient:

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

After the connection is established, 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)]>

Supported environment variables

References

For more information about deploying the Enterprise Edition of OceanBase Database, see Deploy OceanBase Enterprise Edition.