ODBC 连接器

ODBC 支持列表

DolphinDB ODBC 连接器支持以下接口：


功能	接口
连接数据库	`SQLAllocHandle`, `SQLFreeStmt`, `SQLGetEnvAttr`, `SQLDriverConnect`, `SQLDisconnect`, `SQLFreeConnect`, `SQLFreeEnv`, `SQLFreeHandle`, `SQLConnect`
获取配置属性	`SQLGetTypeInfo`, `SQLGetFunctions`, `SQLGetConnectAttr`, `SQLSetEnvAttr`, `SQLGetStmtAttr`, `SQLGetInfo`, `SQLSetConnectAttr`, `SQLSetStmtAttr`
获取错误信息	`SQLGetDiagRec`, `SQLGetDiagField`
SQL 增删改查	`SQLFetch`, `SQLGetData`, `SQLPrepare`, `SQLBindParameter`, `SQLExecDirect`, `SQLExecute`
获取库表元信息	`SQLNumResultCols`, `SQLRowCount`, `SQLColAttribute`, `SQLTables`, `SQLBindCol`, `SQLColumns`, `SQLDescribeCol`

ODBC 连接字符串如下例所示：

// 连接字符串
std::string connectionStr = "driver={DolphinDB ODBC Driver};server=ddbHost;port=35998;uid=admin;pwd=123456;"
// 使用 ODBC 的 SQLDriverConnect 函数进行连接。
SQLDriverConnect(hDbc, NULL, (SQLCHAR*)(connectionStr.c_str()), SQL_NTS, NULL, 0, NULL, SQL_DRIVER_COMPLETE);

连接字符串支持以下参数：

server 数据库 IP 地址，用于连接数据库。

port 数据库端口，用于连接数据库。

uid 数据库用户名，用于登录数据库。

pwd 用户密码，用于登录数据库。

enableHighAvailability 布尔值，指示是否高可用模式，默认为 false，表示不开启。

highAvailabilitySites 字符串，用于在开启高可用情况下指定主机名和端口号数组。

enableSSL 布尔值，指示是否启动 SSL 连接。默认为 false，表示不启动。

enableEncryption 布尔值，指示是否加密用户名和密码。默认为 false，表示不加密。

Linux ODBC 驱动环境配置

下载

下载 ODBC 驱动。

配置

编辑 /etc/odbcinst.ini 添加 ODBC 驱动位置。

[DolphinDB ODBC Driver]
Description=DolphinDB ODBC Driver
Driver=/path/to/libddbodbc.so

编辑 /etc/odbc.ini 添加数据源。

[dolphindb]
Driver=DolphinDB ODBC Driver
Server=127.0.0.1
Port=8848
Uid=admin
Pwd=123456

验证

通过以下命令连接 DolphinDB。

isql -v -k "dsn=dolphindb"
# 进入isql后，可以使用select * from table(1..10 as id)来查询表数据。

使用示例

示例 ODBC 应用程序提供了一个交互式命令行界面，使用户能够借助 DolphinDB 的 SQL 语法，方便地对数据库执行各类操作。若需深入了解和实践，您可以下载示例代码，体验完整的操作流程。

编译命令

g++ -o command command.cpp -I ./ -lodbc -std=c++11

连接数据源

定义一个 ODBC 错误获取函数，用于后续发生错误时，获取环境句柄、数据库连接句柄和语句句柄的报错信息。

void sqlerr(SQLSMALLINT HandleType, SQLHANDLE handle)
{
    SQLCHAR state[32];
    SQLINTEGER native;
    SQLCHAR message[255];
    SQLGetDiagRec(HandleType, handle, 1, state, &native, message, 255, NULL);
    printf("state = %s, message = %s\n", state, message);
}

申请环境句柄和连接句柄，并建立数据库连接。

SQLHANDLE hEnv;
SQLHANDLE hDbc;
SQLHANDLE hStmt;
int ret;

// 1.分配 ODBC 环境句柄
ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
if (!SQL_SUCCEEDED(ret))
{
	printf("allocate env handle error\n");
	return -1;
}

// 2.设置环境
ret = SQLSetEnvAttr(hEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
if (!SQL_SUCCEEDED(ret))
{
	printf("set env error\n");
	sqlerr(SQL_HANDLE_ENV, hEnv);
	return -1;
}

// 3.分配 ODBC 连接句柄
ret = SQLAllocHandle(SQL_HANDLE_DBC, hEnv, &hDbc);
if (!SQL_SUCCEEDED(ret))
{
	printf("allocate connection handle error\n");
	sqlerr(SQL_HANDLE_ENV, hEnv);
	return -1;
}
bool flag = true;
while(flag) {
	cout << "Your DSN str: \n  For example: dsn=dolphindb \n";
	string dsn;
	getline(cin, dsn);
	if(dsn == "exit" || dsn == "quit") {
		flag = false;
		break;
	}
	// 4.连接数据库
	ret = SQLDriverConnect(hDbc,
			NULL,
			(SQLCHAR*)(dsn.c_str()),
			SQL_NTS,
			NULL,
			0,
			NULL,
			SQL_DRIVER_COMPLETE);
	if (!SQL_SUCCEEDED(ret))
	{
		printf("connect error\n");
		sqlerr(SQL_HANDLE_DBC,hDbc);
		continue;
	}
	break;
}

执行 SQL 语句

申请语句句柄，然后执行 SQL 语句。

// 5.分配语句句柄
ret = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, &hStmt);
if (!SQL_SUCCEEDED(ret))
{
  printf("allocate statement handle error\r\n");
	sqlerr(SQL_HANDLE_DBC,hDbc);
	return -1;
}
// 6.执行指定的语句
string stat;
getline(cin, stat);
if(stat == "exit" || stat == "quit") {
	break;
}
ret = SQLExecDirect(hStmt,(SQLCHAR*)(stat.c_str()), SQL_NTS);

if (!SQL_SUCCEEDED(ret))
{
	printf("execute error\n");
	sqlerr(SQL_HANDLE_STMT, hStmt);
	continue;
}

显示查询结果

获取查询结果集的列数，行数及列名。

// 7.取得结果集的列数
SQLSMALLINT sNumResults;
ret = SQLNumResultCols(hStmt, &sNumResults);
if (!SQL_SUCCEEDED(ret))
{
	printf("get result error\n");
	sqlerr(SQL_HANDLE_STMT, hStmt);
	continue;
}

// 8.取得结果集的行数
SQLLEN cRowCount;
ret = SQLRowCount(hStmt, &cRowCount);
if (!SQL_SUCCEEDED(ret))
{
	printf("allocate connection handle error\n");
	sqlerr(SQL_HANDLE_STMT, hStmt);
	continue;
}
// 9.获取列名

for(int i = 0; i < sNumResults; i++)
{
	SQLCHAR colName[64];
	ret = SQLDescribeCol(hStmt, i + 1, colName, 64, NULL, NULL, NULL, NULL, NULL);
	if(!SQL_SUCCEEDED(ret))
	{
		printf("get column name error\n");
		sqlerr(SQL_HANDLE_STMT, hStmt);
		continue;
	}
	printf("%s\t", colName);
}

绑定数据缓冲区。

// 10.将缓冲区提交驱动程序进行绑定。
vector<DataBinding> columnData;
columnData.resize(sNumResults);
int bufferSize = 1024;
vector<vector<char>> buffer;
buffer.resize(sNumResults);
for (int i = 0 ; i < sNumResults ; i++ ) {
	columnData[i].TargetType = SQL_C_CHAR;
	columnData[i].BufferLength = (bufferSize);
	buffer[i].resize(bufferSize);
	columnData[i].TargetValuePtr = buffer[i].data();
}
for (int i = 0 ; i < sNumResults ; i++ ) {
	ret = SQLBindCol(hStmt, (SQLUSMALLINT)i + 1, columnData[i].TargetType,
		columnData[i].TargetValuePtr, columnData[i].BufferLength, &(columnData[i].StrLen_or_Ind));
		if(!SQL_SUCCEEDED(ret))
		{
			printf("bind col error\n");
			sqlerr(SQL_HANDLE_STMT, hStmt);
			continue;
		}
}

逐行读取数据到缓冲区后打印结果。

// 11.调用 SQLFetch 提取数据，直至返回 SQL_NO_DATA_FOUND。驱动程序将提取的数据写入上一步绑定的缓冲区中，供应用程序访问
for ( ret = SQLFetch(hStmt) ; ret == SQL_SUCCESS || ret == SQL_SUCCESS_WITH_INFO ; ret = SQLFetch(hStmt) ) {
	for (int j = 0 ; j < sNumResults ; j++ ){
		printf( "%s\t",(char*)columnData[j].TargetValuePtr);
	}
	printf("\n");
}

退出 ODBC

退出前需依次释放语句句柄、数据库连接句柄和环境句柄，以确保资源正确释放。

SQLFreeHandle(SQL_HANDLE_STMT, hStmt);
SQLDisconnect(hDbc);
SQLFreeHandle(SQL_HANDLE_DBC, hDbc);
SQLFreeHandle(SQL_HANDLE_ENV, hEnv);

类型转换

ODBC 类型到 DolphinDB 类型

写入数据时默认的类型转换对应关系如下：


ODBC 类型	DolphinDB 类型
SQL_C_CHAR, SQL_C_BINARY,	STRING
SQL_C_SHORT, SQL_C_SSHORT	SHORT
SQL_C_USHORT	INT
SQL_C_LONG, SQL_C_SLONG, SQL_C_ULONG, SQL_C_SBIGINT, SQL_C_UBIGINT	LONG
SQL_C_FLOAT, SQL_C_DOUBLE	DOUBLE
SQL_C_BIT, SQL_C_TINYINT, SQL_C_STINYINT, SQL_C_UTINYINT	CHAR
SQL_C_DATE, SQL_C_TYPE_DATE,	DATE
SQL_C_TIME, SQL_C_TYPE_TIME	SECOND
SQL_C_TIMESTAMP, SQL_C_TYPE_TIMESTAMP	DATE，MONTH，TIME，MINUTE，SECOND，DATETIME，TIMESTAMP，NANOTIME，NANOTIMESTAMP，DATEHOUR

DolphinDB 类型到 ODBC 类型

支持查询的 DolphinDB 类型：

BOOL, CHAR, SHORT, INT, LONG, DATE, MONTH, TIME, MINUTE, SECOND, DATETIME, TIMESTAMP, NANOTIME, NANOTIMESTAMP, DATEHOUR, FLOAT, DOUBLE, SYMBOL, STRING, BLOB, INT128, UUID, IPADDR。

DolphinDB 的数值类型可以转为 ODBC 的任意数值类型，DolphinDB 的时间类型可以转换为 ODBC 的任意时间类型。

获取数据时默认的类型转换对应关系：


DolphinDB 类型	ODBC 类型
BOOL	SQL_BIT
CHAR	SQL_TINYINT
SHORT	SQL_SMALLINT
INT	SQL_INTEGER
LONG	SQL_BIGINT
MONTH, DATE	SQL_DATE
TIME, MINUTE, SECOND, NANOTIME	SQL_TIME
DATEHOUR, DATETIME, TIMESTAMP, NANOTIMESTAMP	SQL_TIMESTAMP
FLOAT	SQL_FLOAT
DOUBLE	SQL_DOUBLE
BLOB, SYMBOL, STRING, UUID, INT128, IP	SQL_VARCHAR