如何用OCCI库在C++中创建Oracle环境并连接Docker容器

环境验证 #

已通过sqlplus成功连接Docker容器内的Oracle 23 Free数据库，连接命令及验证结果如下：

sqlplus dbusername/password@localhost:1521/freepdb1

SQL*Plus: Release 23.0.0.0.0 - for Oracle Cloud and Engineered Systems on Mon Dec 9 09:25:08 2024
Version 23.6.0.24.10

Copyright (c) 1982, 2024, Oracle.  All rights reserved.

Last Successful login time: Mon Dec 09 2024 09:14:52 +01:00

Connected to:
Oracle Database 23ai Free Release 23.0.0.0.0 - Develop, Learn, and Run for Free
Version 23.5.0.24.07

SQL> SELECT version FROM PRODUCT_COMPONENT_VERSION
 WHERE product LIKE 'Oracle Database%';

VERSION
--------------------------------------------------------------------------------
23.0.0.0.0

Docker容器配置信息：

$ docker ps
CONTAINER ID   IMAGE                                                COMMAND                  CREATED      STATUS                   PORTS
                   NAMES
629de2771f43   container-registry.oracle.com/database/free:latest   "/bin/bash -c $ORACL…"   5 days ago   Up 8 minutes (healthy)   0.0.0.0:1521->1521/tcp, :::1521->1521/tcp   oradb

问题现象 #

1. 环境创建失败 #

使用以下C++代码无法创建Oracle数据库环境：

#include <iostream>
#include <occi.h>

using namespace oracle::occi;
using namespace std;

int main() {

    Environment *env = nullptr;

    env = Environment::createEnvironment(Environment::DEFAULT);

    // 之前判断逻辑错误，现在已修正为if(env)
    if(env)
            cout << "Environment created." << endl;
    else
            cerr << "Environment not created." << endl;
    return 0;
}

编译命令：

$ g++ -o mwe dbconnection.cpp -I/path/to/oracle/instantclient_23_6/sdk/include   -L/path/to/oracle/instantclient_23_6  -locci -lclntsh

运行结果：

$ ./mwe
Environment not created.

2. 运行时异常 #

尝试连接的代码运行时抛出异常，错误码为-529697949（0xe06d7363），代码如下：

#include <iostream>
#include <string>
#include <occi.h>

using namespace oracle::occi;
using namespace std;

int main()
{
    string user = "dbusername";
    string password = "password";
    string connectString = "localhost:1521/freepdb1";

    Environment* env = nullptr;
    Connection* conn = nullptr;

    env = Environment::createEnvironment(Environment::DEFAULT);
    // 之前判断逻辑错误，现在已修正为if(env)
    if(env)
        cout << "Environment created." << endl;
    else
        cerr << "Environment not created." << endl;

    conn = env->createConnection(user, password, connectString);
    if (!conn)
        cout << "Connection established." << endl;
    else
        cerr << "Connection not established." << endl;
    return 0;
}

解决方案 #

1. 排查环境创建失败问题 #

动态库加载问题

编译时指定了-L参数，但运行时系统可能找不到OCCI相关动态库。需设置环境变量：

• Linux/macOS：执行 export LD_LIBRARY_PATH=/path/to/oracle/instantclient_23_6:$LD_LIBRARY_PATH
• Windows：将InstantClient路径添加到PATH环境变量

版本兼容性确认

确保InstantClient版本（23.6）与Docker内Oracle数据库版本（23.5）兼容，Oracle官方建议使用同大版本的客户端与服务端，23.x系列相互兼容，但需确认客户端是否完整安装。

代码异常捕获

OCCI的createEnvironment失败时会抛出SQLException，而非返回空指针。修改代码捕获异常，获取具体错误信息：

#include <iostream>
#include <occi.h>
#include <exception>

using namespace oracle::occi;
using namespace std;

int main() {
    Environment *env = nullptr;
    try {
        env = Environment::createEnvironment(Environment::DEFAULT);
        cout << "Environment created." << endl;
    } catch (SQLException& e) {
        cerr << "环境创建失败，错误码：" << e.getErrorCode() << endl;
        cerr << "错误信息：" << e.getMessage() << endl;
        return 1;
    } catch (exception& e) {
        cerr << "未知异常：" << e.what() << endl;
        return 1;
    }
    return 0;
}

2. 解决运行时异常（0xe06d7363） #

错误码0xe06d7363是Windows平台的结构化异常代码，通常对应C++未捕获的异常。结合环境创建失败的问题，本质还是动态库未正确加载或OCCI初始化失败。

修正连接代码的判断逻辑

原代码中conn = env->createConnection(...)的判断逻辑错误：createConnection成功返回连接指针，失败抛出异常，不会返回空指针。修正后的代码：

#include <iostream>
#include <string>
#include <occi.h>
#include <exception>

using namespace oracle::occi;
using namespace std;

int main()
{
    string user = "dbusername";
    string password = "password";
    string connectString = "localhost:1521/freepdb1";

    Environment* env = nullptr;
    Connection* conn = nullptr;

    try {
        env = Environment::createEnvironment(Environment::DEFAULT);
        cout << "Environment created." << endl;

        conn = env->createConnection(user, password, connectString);
        cout << "Connection established." << endl;

        // 使用连接完成操作后，释放资源
        env->terminateConnection(conn);
        Environment::terminateEnvironment(env);
    } catch (SQLException& e) {
        cerr << "数据库操作失败，错误码：" << e.getErrorCode() << endl;
        cerr << "错误信息：" << e.getMessage() << endl;
        // 清理已创建的资源
        if (conn) env->terminateConnection(conn);
        if (env) Environment::terminateEnvironment(env);
        return 1;
    } catch (exception& e) {
        cerr << "未知异常：" << e.what() << endl;
        if (conn) env->terminateConnection(conn);
        if (env) Environment::terminateEnvironment(env);
        return 1;
    }
    return 0;
}

3. 编译与运行注意事项 #

• 编译时确保-I参数指向正确的OCCI头文件路径（instantclient_23_6/sdk/include）
• 运行前必须设置动态库路径，避免加载失败
• 若使用Windows平台，需使用对应版本的MSVC编译器（Oracle OCCI对GCC的Windows支持有限）

内容的提问来源于stack exchange，提问作者Stefan Bollmann