Connect C applications to OceanBase Database

This topic describes how to connect C applications to OceanBase Database.

Prerequisites

Before you install OceanBase Connector/C, make sure that you have set up the basic database development environment that meets the following requirements:

• The GNU Compiler Collection (GCC) version is 3.4.6 or later. Version 4.8.5 is recommended.

• The CMake version is 2.8.12 or later.

Install OceanBase Connector/C

Install Linux

Obtain the installation packages of OceanBase Connector/C (also known as libobclient) and OBClient.

Find the required installation packages in the image repository based on your system version and download the installation packages. For more information, see Software resources in [Software and hardware requirements] (https://mirrors.aliyun.com/oceanbase/community/stable/el/) .

1. Install OceanBase Connector/C.

   sudo rpm -ivh libobclient-xx.x86_64.rpm
   

2. Install OBClient.

   sudo rpm -ivh obclient-xx.x86_64.rpm
   

   Note

   OBClient depends on OceanBase Connector/C. Therefore, you must install OceanBase Connector/C first.

Compile a C application by using the source code

OceanBase Database provides the source code of the latest OBClient in its GitHub repository, which also includes the sub-repository libobclient.

1. Install the dependency tool.

   sudo yum install -y git cmake gcc make openssl-devel ncurses-devel rpm-build  gcc-c++ bison bison-devel zlib-devel gnutls-devel libxml2-devel openssl-devel \
   libevent-devel libaio-devel
   

2. Compile and package the code

   1. Download the source code of OBClient, which also includes sub-repositories.

      git clone --recurse-submodules https://github.com/oceanbase/obclient # Download the source code of OBClient, which also includes sub-repositories.
      cd obclient
      

   2. Compile OceanBase Connector/C.

      cd obclient/libmariadb
      sh build.sh
      

   3. Package up the RPM package of OceanBase Connector/C.

      cd rpm
      sh libobclient-build.sh
      

   4. Compile OBClient.

      cd ../..  # Return to the OBClient directory.
      sh build.sh
      

   5. Package up the RPM package of OBClient.

      cd rpm
      sh obclient-build.sh
      

3. Install OceanBase Connector/C and OBClient.

   cd /obclient/libmariadb/rpm
   sudo rpm -ivh libobclient-xx.x86_64.rpm
   cd ../../rpm # Go to the obclient/rpm directory of OBClient.
   sudo rpm -ivh obclient-xx.x86_64.rpm
   

   Note

   OBClient depends on OceanBase Connector/C. Therefore, you must install OceanBase Connector/C first.

Examples

The basic methods for an application to interact with an OBServer by using OceanBase Connector/C include:

1. Call mysql_library_init() to initialize the MySQL library.

   mysql_library_init(0, NULL, NULL);
   

2. Call mysql_init() to initialize a connection handle.

   MYSQL *mysql = mysql_init(NULL);
   

3. Call mysql_real_connect() to connect to the OBServer.

   mysql_real_connect (mysql, host_name, user_name, password,
   db_name, port_num, socket_name, CLIENT_MULTI_STATEMENTS)
   

4. Call mysql_real_query() or mysql_query() to send an SQL statement to the OBServer.

   mysql_query(mysql,"sql_statement");
   

5. Call mysql_store_result() or mysql_use_result() to process the result.

   result=mysql_store_result(mysql);
   

6. Call mysql_free_result() to release the memory.

   mysql_free_result(result);
   

7. Call mysql_close() to disconnect from the OBServer.

   mysql_close(mysql);
   

8. Call mysql_library_end() to stop using OceanBase Connector/C.

   mysql_library_end();
   

Sample code

The following example shows the content of the mysql_test.c file:

#include "mysql.h"
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char** argv)
{
  mysql_library_init(0, NULL, NULL);
  MYSQL *mysql = mysql_init(NULL);
  char* host_name = "172.xx.xx.xx";// Set your MySQL host.
  char* user_name = "r***"; // Set your username.
  char* password = "***1**"; // set your password.
  char* db_name = "test"; // Set your database name.
  int port_num = 2883; // Set your MySQL port number.
  char* socket_name = NULL;
  MYSQL_RES* result;
  int status = 0;
  /* connect to server with the CLIENT_MULTI_STATEMENTS option */
  if (mysql_real_connect (mysql, host_name, user_name, password,
    db_name, port_num, socket_name, CLIENT_MULTI_STATEMENTS) == NULL)
  {
    printf("mysql_real_connect() failed\n");
    mysql_close(mysql);
    exit(1);
  }

  /* execute multiple statements */
  status = mysql_query(mysql,
                     "DROP TABLE IF EXISTS test_table;\
                      CREATE TABLE test_table(id INT);\
                      INSERT INTO test_table VALUES(10);\
                      UPDATE test_table SET id=20 WHERE id=10;\
                      SELECT * FROM test_table;\
                      DROP TABLE test_table");
  if (status)
  {
    printf("Could not execute statement(s)");
    mysql_close(mysql);
    exit(0);
  }

 /* process each statement result */
 do {
   /* did current statement return data? */
   result = mysql_store_result(mysql);
   if (result)
   {
     /* yes; process rows and free the result set */
     //process_result_set(mysql, result);
     mysql_free_result(result);
   }
   else          /* no result set or error */
   {
     if (mysql_field_count(mysql) == 0)
     {
       printf("%lld rows affected\n",
            mysql_affected_rows(mysql));
     }
     else  /* some error occurred */
     {
       printf("Could not retrieve result set\n");
       break;
     }
  }
  /* more results? -1 = no, >0 = error, 0 = yes (keep looping) */
  if ((status = mysql_next_result(mysql)) > 0)
    printf("Could not execute statement\n");
  } while (status == 0);

  mysql_close(mysql);
}

Parameters

• hostname: specifies the IP address for connecting to the OceanBase database, which is usually the IP address of an OBProxy.

• username: specifies the account for connecting to the tenant. In MySQL mode, the default username of the tenant administrator is root.

• password: specifies the password of the account.

• dbname: specifies the name of the database to access.

• port: specifies the port for connecting to the OceanBase database, which is also the listening port of the OBProxy. Default value: 2883, which can be changed.

After you edit the code, run the following command:

// Compile the code.
g++ -I/u01/obclient/include/ -L/u01/obclient/lib -lobclnt mysql_test.c -o mysql_test
// Specify the execution path.
export LD_LIBRARY_PATH=/u01/obclient/lib
// Run the code.
./mysql_test

Note

By default, OBClient is installed in the /u01/obclient directory.

Related topics

For more information about how to install and use OceanBase Connector/C, see OceanBase Connector/C Developer Guide.