OceanBase Connector/C 连接 OB Cloud 云数据库示例程序

本文将介绍如何使用 OceanBase Connector/C 和 OB Cloud 云数据库构建一个应用程序，实现创建表、插入数据和查询数据等基本操作。

点击下载 c-oceanbase-capi 示例工程

OceanBase Connector/C 连接 OceanBase 数据库示例程序（Oracle 模式）

前提条件

您已注册 OB Cloud 云数据库账号,并创建集群实例和 OB Cloud Oracle 模式租户。详情请参见创建集群实例和创建租户。
您已安装 OceanBase Connector/C 驱动程序。请联系技术支持获取 OceanBase Connector/C 驱动程序 Windows 版本的安装包。
您已安装 Visual Studio。

操作步骤

说明

本文中给出的操作步骤是在 Windows 环境下使用 Visual Studio Community 2019 编译和运行该项目的步骤。如果您使用的是其他操作系统环境或编译器，那么操作步骤可能会略有不同。

打开 c-oceanbase-capi 项目。
配置 c-oceanbase-capi 项目属性。
获取 OB Cloud 云数据库连接信息。
修改 c-oceanbase-capi 项目中的数据库连接信息。
构建项目。
运行应用程序。
查看输出结果。

步骤一：打开 c-oceanbase-capi 项目

启动 Visual Studio Community 2019。
打开现有项目。
1. 在 Visual Studio Community 2019 的起始界面上，在开始使用下面点击 打开项目或解决方案(P) 按钮。或者在 Visual Studio Community 2019 的起始界面上，在开始使用下面点击 继续但无需代码(W) 按钮；在上面菜单栏中选择文件 -> 打开 -> 项目/解决方案(P)。
2. 浏览到 c-oceanbase-capi 项目 的文件夹，选择项目文件（c-oceanbase-capi.sln 或者 c-oceanbase-capi.vcxproj），然后点击打开。

步骤二：配置 c-oceanbase-capi 项目属性

打开项目的属性页。

在 解决方案管理器中 右键单击选定的项目，然后在上下文菜单中选择属性，或者在 Visual Studio 的顶部菜单栏中选择项目 -> 属性，或者使用快捷键 Alt + Enter。
配置管理器设置。
1. 在属性页中选择上方找到 配置(C) 下拉菜单。在下拉菜单中，选择 Debug。
2. 在属性页中选择上方找到 平台(P) 下拉菜单。在下拉菜单中，选择 x64。
设置编译器的头文件路径。

在属性页中选择 VC++ 目录 选项卡，找到 包含目录 一栏，添加 OceanBase Connector/C 库的头文件路径。
设置编译器的链接库路径。

在属性页中选择 VC++ 目录 选项卡，找到 库目录 一栏，添加 OceanBase Connector/C 库的链接库路径。
字符集设置。

在属性页中选择高级选项卡，找到 字符集 一栏。在下拉菜单中，选择 使用多字节字符集。

步骤三：获取 OB Cloud 云数据库连接信息

登录 OB Cloud 云数据库控制台。在实例列表页面，展开目标实例的信息，在目标租户下，选择连接 > 获取连接串。

更多详细操作，请参见获取连接串。
根据已创建的 OB Cloud 云数据库填写下面 URL 的对应信息。

示例如下：
```
obclient -h t********.********.oceanbase.cloud` -P1521 -u oracle001 -p******
```
参数说明：
- -h：提供 OB Cloud 云数据库连接地址，例如 t********.********.oceanbase.cloud。
- -P：提供 OB Cloud 云数据库连接端口，默认为 1521。
- -u：提供访问数据库的账号。
- -p：提供账号密码。

更多连接串的信息，请参见通过 OBClient 连接 OceanBase 租户。

步骤四：修改 c-oceanbase-capi 项目中的数据库连接信息

根据 步骤三：获取 OB Cloud 云数据库连接信息 中的信息修改 test_tbl1.cpp 文件中的数据库连接信息。

示例如下：

if (NULL == mysql_real_connect(&con_oboracle, "t********.********.oceanbase.cloud", "oracle001", "******", "sys", 1521, NULL, 0))

步骤五：构建项目

选择生成菜单，然后选择 生成解决方案。构建过程中会显示编译器的输出和任何错误或警告信息。

步骤六：运行应用程序

选择调试菜单，然后选择 开始调试 或者 开始执行(不调试) 来运行的应用程序。

步骤七：查看输出结果

输出结果将显示在调试控制台中。您可以根据程序的设计逻辑和代码来判断如何处理输出。

项目代码介绍

点击 c-oceanbase-capi 下载项目代码，是一个名称为 c-oceanbase-capi.zip 的压缩包。

解压后，得到一个名为 c-oceanbase-capi 的文件夹。目录结构如下所示：

c-oceanbase-capi
├─ c-oceanbase-capi.sln
├─ c-oceanbase-capi.vcxproj
├─ c-oceanbase-capi.vcxproj.filters
├─ c-oceanbase-capi.vcxproj.user
└─ test_tbl1.cpp

文件说明：

c-oceanbase-capi.sln：Visual Studio 的解决方案文件，用于管理一个或多个项目。
c-oceanbase-capi.vcxproj：Visual Studio 的项目文件，用于描述一个 C/C++ 项目的结构和配置。
c-oceanbase-capi.vcxproj.filters：Visual Studio 的项目过滤器文件，用于定义项目中文件的目录结构和组织方式。
c-oceanbase-capi.vcxproj.user：用于存储用户特定的项目设置的文件。
test_tbl1.cpp：定义数据表的结构和实现数据表操作的源代码文件。

test_tbl1.cpp 文件代码介绍

test_tbl1.cpp 文件用于定义名称为 test_tbl1 的数据表，实现了数据表的创建、插入数据和查询操作。

本文 test_tbl1.cpp 文件的代码主要包括以下几个部分：

引用头文件和库文件。
- 引用头文件 stdio.h、stdlib.h 和 mysql.h。
- 指定链接器需要链接特定的库文件 Shlwapi.lib、ws2_32.lib、Crypt32.lib、Secur32.lib 和 obclnt.lib。这些库文件分别是 Windows API 库、WinSock 库、加密库、安全库和 OB Cloud 云数据库客户端库。
代码如下：
```
#include <stdio.h>
#include <stdlib.h>
#include <mysql.h>
#pragma comment(lib, "Shlwapi.lib")
#pragma comment( lib, "ws2_32.lib" ) 
#pragma comment(lib, "Crypt32.lib")
#pragma comment(lib, "Secur32.lib")
#pragma comment(lib, "obclnt.lib")
```
定义 main 函数。

定义程序的入口函数 main，返回一个整数值。在 main 函数中，编写了与数据库连接、数据操作相关的代码。

代码如下：
```
int main() {
    // 创建一个连接的实例对象
    // 连接数据库
    // 创建表
    // 插入数据
    // 查询数据
    // ...
}
```
声明变量和数组。
- 声明了一个名为 con_oboracle 的变量，其类型为 MYSQL。通过声明这个变量，我们可以创建一个连接实例。
- 声明了一个名为 sql_str 的字符数组，长度为 1024，初始化为 { 0 }。这个数组用于存储 SQL 查询语句。
代码如下：
```
    MYSQL con_oboracle;
    char sql_str[1024] = { 0 };
```
初始化连接的实例对象。

初始化连接对象 con_oboracle，并根据初始化结果进行相应的处理。如果初始化失败，则打印错误信息并返回非零值；如果初始化成功，则打印成功消息，并继续执行后续的操作。具体步骤如下：
1. 调用 mysql_init() 函数来初始化连接对象 con_oboracle。这个函数会返回一个指向已初始化连接对象的指针，如果初始化失败则返回 NULL。NULL 是一个宏，表示空指针。NULL 与 mysql_init() 的返回值进行比较，判断初始化是否成功。
  1. 使用 fprintf() 函数是将错误信息打印到标准错误流 stderr 中。fprintf() 函数的第一个参数是输出流，"Error: %s\n" 是格式化字符串，mysql_error(&con_oboracle) 是用于替换格式化字符串中 %s 的实际参数。mysql_error(&con_oboracle) 是获取连接对象 con_oboracle 的错误信息。
  2. 使用 return 1 在初始化失败时，退出 main 函数并返回一个非零值。这个值可以用来表示程序异常终止或初始化失败的状态。
2. 在初始化成功时，打印一条成功的消息。这样可以在控制台中看到连接对象的初始化是否成功。
代码如下：
```
    if (NULL == mysql_init(&con_oboracle)) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        return 1;
    }
    printf("mysql_init() success\n");
```
连接数据库。

在程序中尝试连接到数据库，并根据连接结果进行相应的处理。如果连接失败，则打印错误信息并返回非零值；如果连接成功，则打印成功消息，并继续执行后续的操作。具体步骤如下：
1. 调用 mysql_real_connect() 函数来连接到数据库。这个函数会返回一个指向已连接对象的指针，如果连接失败则返回 NULL。
  1. 使用 fprintf() 函数是将错误信息打印到标准错误流 stderr 中。fprintf() 函数的第一个参数是输出流，"Error: %s\n" 是格式化字符串，mysql_error(&con_oboracle) 是用于替换格式化字符串中 %s 的实际参数。mysql_error(&con_oboracle) 是获取连接对象 con_oboracle 的错误信息。
  2. 使用 return 1 在连接失败时，退出 main 函数并返回一个非零值。这个值可以用来表示程序异常终止或连接失败的状态。
2. 在连接成功时，打印一条成功的消息。这样可以在控制台中看到是否成功连接到数据库。
代码如下：
```
    if (NULL == mysql_real_connect(&con_oboracle, "your_ip", "your_user", "your_password", "your_schema", your_port, NULL, 0)) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        return 1;
    }
    printf("mysql_real_connect() success\n");
```
连接 OB Cloud 云数据库所需要的参数说明：
- your_ip：提供 OB Cloud 云数据库连接地址，例如 t********.********.oceanbase.cloud。
- your_user：提供访问数据库的账号。
- your_password：提供账号密码。
- your_schema：需要访问的 Schema 名称。
- your_port：提供 OB Cloud 云数据库连接端口，默认为 1521。
创建表。

执行一个 SQL 查询语句来创建一个表。如果表创建成功，则打印成功消息；如果表创建失败，则打印错误信息，并退出程序。具体步骤如下：
1. 使用 sprintf_s() 函数将一个 SQL 查询字符串格式化并存储在 sql_str 字符数组中。这个 SQL 查询语句用于创建一个名为 test_tbl1 的表，该表包含 id（主键）、name 和 age 列。
2. 使用 mysql_query() 函数执行 SQL 查询语句。&con_oboracle 是一个指向数据库连接对象的指针，用于指定要对其进行查询操作的连接对象。sql_str 是要执行的查询语句。然后检查查询的执行结果是否成功。如果查询执行失败（返回值不为 0），则执行下面的代码块。
  1. 使用 fprintf() 函数是将错误信息打印到标准错误流 stderr 中。fprintf() 函数的第一个参数是输出流，"Error: %s\n" 是格式化字符串，mysql_error(&con_oboracle) 是用于替换格式化字符串中 %s 的实际参数。mysql_error(&con_oboracle) 是获取连接对象 con_oboracle 的错误信息。
  2. 关闭与数据库的连接，释放连接对象的资源。
  3. 使用 return 1 在创建表失败时退出 main 函数，并返回一个非零值 1，用于表示程序异常终止的状态。
3. 如果表创建成功，则打印一条成功消息，表示表已成功创建。
代码如下：
```
    sprintf_s(sql_str, "CREATE TABLE test_tbl1(id NUMBER PRIMARY KEY, name VARCHAR2(50),age NUMBER NOT NULL)");
    if (mysql_query(&con_oboracle, sql_str) != 0) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }
    printf("Table created successfully\n");
```
插入数据。

执行一个 SQL 查询语句向表中插入数据。如果数据插入成功，则打印成功消息；如果插入失败，则打印错误信息，并退出程序。具体步骤如下：
1. 使用 sprintf_s() 函数将一个 SQL 查询字符串格式化并存储在 sql_str 字符数组中。这个 SQL 查询语句用于向 test_tbl1 表中插入数据，插入的数据包括 id、name 和 age 列的值。
2. 使用 mysql_query() 函数执行 SQL 查询语句。&con_oboracle 是一个指向数据库连接对象的指针，用于指定要对其进行查询操作的连接对象。sql_str 是要执行的查询语句。然后检查查询的执行结果是否成功。如果查询执行失败（返回值不为 0），则执行下面的代码块。
  1. 使用 fprintf() 函数是将错误信息打印到标准错误流 stderr 中。fprintf() 函数的第一个参数是输出流，"Error: %s\n" 是格式化字符串，mysql_error(&con_oboracle) 是用于替换格式化字符串中 %s 的实际参数。mysql_error(&con_oboracle) 是获取连接对象 con_oboracle 的错误信息。
  2. 关闭与数据库的连接，释放连接对象的资源。
  3. 使用 return 1 在数据插入失败时退出 main 函数，并返回一个非零值 1，用于表示程序异常终止的状态。
3. 如果数据插入成功，则打印一条成功消息，表示数据已成功插入。
代码如下：
```
    sprintf_s(sql_str, "INSERT INTO test_tbl1 (id,name,age) VALUES  (1,'Tom', 18),(2,'Jerry', 20),(3,'Bob', 22)");
    if (mysql_query(&con_oboracle, sql_str) != 0) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }
    printf("Data inserted successfully\n");
```
查询数据。

执行一个 SQL 查询来检索表中的数据，并逐行打印检索到的数据。如果数据检索成功，则打印成功消息；如果检索失败，则打印错误信息，并退出程序。具体步骤如下：
1. 使用 sprintf_s() 函数将一个 SQL 查询字符串格式化并存储在 sql_str 字符数组中。这个 SQL 查询语句用于从 test_tbl1 表中检索所有列的数据。
2. 使用 mysql_query() 函数执行 SQL 查询语句。&con_oboracle 是一个指向数据库连接对象的指针，用于指定要对其进行查询操作的连接对象。sql_str 是要执行的查询语句。然后检查查询的执行结果是否成功。如果查询执行失败（返回值不为 0），则执行下面的代码块。
  1. 使用 fprintf() 函数是将错误信息打印到标准错误流 stderr 中。fprintf() 函数的第一个参数是输出流，"Error: %s\n" 是格式化字符串，mysql_error(&con_oboracle) 是用于替换格式化字符串中 %s 的实际参数。mysql_error(&con_oboracle) 是获取连接对象 con_oboracle 的错误信息。
  2. 关闭与数据库的连接，释放连接对象的资源。
  3. 使用 return 1 在查询失败时退出 main 函数，并返回一个非零值 1，用于表示程序异常终止的状态。
3. 使用 mysql_store_result() 函数将查询结果集存储在一个 MYSQL_RES 结构体中。&con_oboracle 是一个指向数据库连接对象的指针，用于指定要获取结果集的连接对象。
4. 检查结果集是否为空。如果结果集为空，则表示查询结果集存储失败，执行下面的代码块。
  1. 使用 fprintf() 函数是将错误信息打印到标准错误流 stderr 中。fprintf() 函数的第一个参数是输出流，"Error: %s\n" 是格式化字符串，mysql_error(&con_oboracle) 是用于替换格式化字符串中 %s 的实际参数。mysql_error(&con_oboracle) 是获取连接对象 con_oboracle 的错误信息。
  2. 关闭与数据库的连接，释放连接对象的资源。
  3. 使用 return 1 在存储查询结果集失败时退出 main 函数，并返回一个非零值 1，用于表示程序异常终止的状态。
5. 如果数据检索成功，则打印一条成功消息，表示数据已成功检索。
6. 定义一个 MYSQL_ROW 类型的变量 row，用于存储每一行的数据。
7. 使用 mysql_fetch_row() 函数逐行检索结果集中的数据，并将每一行的数据存储在 row 变量中。while 循环将继续迭代，直到结果集中的所有行都被检索完毕。在循环中，打印每一行的数据。row[0]、row[1] 和 row[2] 分别表示当前行中第一个、第二个和第三个列的值。
代码如下：
```
    sprintf_s(sql_str, "SELECT * FROM test_tbl1");
    if (mysql_query(&con_oboracle, sql_str) != 0) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }

    MYSQL_RES* result = mysql_store_result(&con_oboracle);
    if (result == NULL) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }

    printf("Data retrieved successfully\n");

    MYSQL_ROW row;
    while ((row = mysql_fetch_row(result)) != NULL) {
        printf("id: %s, name: %s, age: %s\n", row[0], row[1], row[2]);
    }
```
程序结束。

释放资源和关闭与数据库的连接。具体步骤如下：
1. 使用 mysql_free_result(result) 释放通过 mysql_store_result() 函数存储的结果集资源。result 是一个指向 MYSQL_RES 结构体的指针，它存储了查询结果集的信息和数据。
2. 使用 mysql_close(&con_oboracle) 关闭与数据库的连接，释放连接对象占用的资源。&con_oboracle 是一个指向数据库连接对象的指针，通过调用 mysql_close() 函数，可以关闭与数据库的连接，并释放与连接对象相关的资源。
3. 使用 return 0; 表示程序正常执行结束，并返回 0 作为程序的退出状态。
代码如下：
```
    mysql_free_result(result);

    mysql_close(&con_oboracle);
    printf("finish\n");

    return 0;
}
```

完整的代码展示

test_tbl1.cpp

#include <stdio.h>
#include <stdlib.h>
#include <mysql.h>
#pragma comment(lib, "Shlwapi.lib")
#pragma comment( lib, "ws2_32.lib" ) 
#pragma comment(lib, "Crypt32.lib")
#pragma comment(lib, "Secur32.lib")
#pragma comment(lib, "obclnt.lib")

int main() {
    MYSQL con_oboracle;
    char sql_str[1024] = { 0 };

    if (NULL == mysql_init(&con_oboracle)) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        return 1;
    }
    printf("mysql_init() success\n");

    if (NULL == mysql_real_connect(&con_oboracle, "your_ip", "your_user", "your_password", "your_schema", your_port, NULL, 0)) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        return 1;
    }
    printf("mysql_real_connect() success\n");

    sprintf_s(sql_str, "CREATE TABLE test_tbl1(id NUMBER PRIMARY KEY, name VARCHAR2(50),age NUMBER NOT NULL)");
    if (mysql_query(&con_oboracle, sql_str) != 0) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }
    printf("Table created successfully\n");

    sprintf_s(sql_str, "INSERT INTO test_tbl1 (id,name,age) VALUES  (1,'Tom', 18),(2,'Jerry', 20),(3,'Bob', 22)");
    if (mysql_query(&con_oboracle, sql_str) != 0) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }
    printf("Data inserted successfully\n");

    sprintf_s(sql_str, "SELECT * FROM test_tbl1");
    if (mysql_query(&con_oboracle, sql_str) != 0) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }

    MYSQL_RES* result = mysql_store_result(&con_oboracle);
    if (result == NULL) {
        fprintf(stderr, "Error: %s\n", mysql_error(&con_oboracle));
        mysql_close(&con_oboracle);
        return 1;
    }

    printf("Data retrieved successfully\n");
    MYSQL_ROW row;
    while ((row = mysql_fetch_row(result)) != NULL) {
        printf("id: %s, name: %s, age: %s\n", row[0], row[1], row[2]);
    }

    mysql_free_result(result);

    mysql_close(&con_oboracle);
    printf("finish\n");

    return 0;
}