KingbaseES客户端编程开发框架-Qt.pdf

KingbaseES 客户端编程开发框架-Qt 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 驱动说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 配置说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3 编译说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 第 3 章 管理连接 6 3.1 连接到数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2 关闭连接 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 4 章 执行 SQL 语句 8 4.1 查询和结果集处理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2 执行非查询 SQL 语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.3 准备语句和绑定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 第 5 章 程序示例 10 5.1 连接数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.2 获取结果集 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.3 批量 DML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 版权声明 13 服务周期承诺 14 I 第 1 章 前言 1 第 章 前言 本文档描述了使用 QT 框架操作 KingbaseES 数据库的方法和配置。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 《KingbaseES QT 指南》面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用程序开发人员。 1.2 相关文档 有关 QT 的更多信息，请参阅以下资源： https://doc.qt.io 1.3 术语 无 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 1 第 1 章 前言 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 • 驱动说明 • 配置说明 • 编译说明 2.1 驱动说明 Qt 是开源的跨平台开发框架，只需在对应平台上编译，便可以被运用于该系统。该驱动主要运用于客户开发的 Qt 项目。 Qt 驱动并不能被直接使用，用户通过 QSqlDatabase 和 QSqlQuery 来获取指向该驱动的实例，然后通过 QSql 模块对外提供的接口方法来操作数据库。 本章主要说明了 Qt 如何使用以及使用时应当注意的情况。 目前提供的 Qt 驱动支持情况如下表所示： 表 2.1.1: Qt 支持情况 Qt 版本 系统架构 说明 Qt4.8 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Linux mips64le 尚不支持该版本 Windows MinGW 仅提供 32 位支持 Windows MSVC 仅提供 32 位支持; 使用 VS2008 编译，需要 VC9 运行时 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Qt5.6 见续表 3 第 2 章 概述 表 2.1.1 – 续表 Qt 版本 2.2 系统架构 说明 Linux mips64le 尚不支持该版本 Windows MinGW 仅提供 32 位支持 Windows MSVC 提供 32 和 64 位支持; 使用 VS2013 编译，需要 VC12 运行时 配置说明 首先，需要已经安装 Qt，且配置 kingbase 数据库。 由于 qkingbase 驱动对 kingbase 数据库有依赖，最好将 kingbase 目录下的 lib 库加入至环境变量中。 将对应 Qt 版本的 qkingbase 驱动解压后，把驱动文件放在 Qt 安装目录下的插件目录的 sqldrivers 文件夹下，如 “D:\Qt\4.8.6\plugins\sqldrivers”或“/usr/local/Qt-5.6.1/plugins/sqldrivers”。 如果不确定路径，可以编写以下程序然后使用 Qt 编译执行： // main.cpp #include #include#include int main() { qDebug() << "The driver should be put in this path:" << QCoreApplication::libraryPaths(); qDebug() << "Available drivers:" << QSqlDatabase::drivers(); } 如果已经放入正确的路径且无依赖问题，可以看到可用驱动列表中有 KINGBASE。 图 2.2.1: 可用驱动列表 2.3 编译说明 如果使用 Qt Creator 开发工具的话，可以在该工具界面左下角的套件选择器中查看当前选择的 Qt 版本，如图 1.3.1 所示。 4 第 2 章 概述 图 2.3.1: 查看当前选择的 Qt 版本 如果在命令行模式下执行的话，可以使用 qmake--version 查看当前版本信息，如图 1.3.2 所示。 图 2.3.2: 查看当前版本信息 5 第3章 管理连接 3 第 章 管理连接 • 连接到数据库 • 关闭连接 3.1 连接到数据库 我们可以使用以下语句连接到数据库： QSqlDatabase db = QSqlDatabase::addDatabase("QKINGBASE"); db.setHostName("127.0.0.1"); db.setDatabaseName("TEST"); db.setUserName("SYSTEM"); db.setPassword("123456"); db.setPort(54321); db.setConnectOptions("connect_timeout=2"); db.open(); 连接参数说明可参考表 2.1.1 。 6 第3章 管理连接 表 3.1.1: 连接参数说明 参数名 说明 备注 host 数据库服务器的地址，包 无默认值，通过调用函数 setHostName 传入 括域名、主机名、主机的 参数 IP 地址等。 port 端口号 无默认值，通过调用函数 setPort 传入参数 user 登录的用户名 无默认值，通过调用函数 setUserName 传入 参数 password 该用户对应的密码 无默认值，通过调用函数 setPassword 传入 参数 database 连接至的数据库名 无默认值，通过调用函数 setDatabaseName 传入参数 connect_timeout client_encoding 连接的最长等待时间，单 通过调用函数 setConnectOptions 传入参数， 位为秒 0 值或未指定均为无限等待，最小值为 2 设置客户端的编码 通过调用函数 setConnectOptions 传入参数 如果通过调用函数 setConnectOptions 传入多个参数，需要使用分号间隔，如下所示： db.setConnectOptions("connect_timeout=5;client_encoding=UTF8"); 3.2 关闭连接 要关闭与数据库的连接，只需要对数据库对象 db 调用 close 方法。 db.close() 7 第 4 章 执行 SQL 语句 4 第 章 执行 SQL 语句 • 查询和结果集处理 • 执行非查询 SQL 语句 • 准备语句和绑定 4.1 查询和结果集处理 创建 QSqlQuery 对象，然后调用其 exec 方法来执行 sql 语句。 next 函数可以从结果集中检索下一条记录，若为空，将返回 false。 QSqlQuery q(db); q.exec("select id from test"); while (q.next()) { qDebug() << q.value(0); } 4.2 执行非查询 SQL 语句 获取游标对象后，直接执行 execute 函数即可。 QSqlQuery q(db); q.exec("create table test(id integer, name TEXT)"); q.exec("INSERT INTO TEST(id, name) VALUES(1, 'John')") 8 第 4 章 执行 SQL 语句 4.3 准备语句和绑定 Qt 具有较为强大的准备和绑定功能，可以使用 Oracle 风格占位符（:name）或者 ODBC 风格占位符（?），但 不能混合使用。 q.prepare("INSERT INTO TEST(id, name) VALUES(?, ?)"); q.bindValue(0, 100); q.bindValue(0, "prepare"); q.exec(); 9 第5章 程序示例 5 第 章 程序示例 • 连接数据库 • 获取结果集 • 批量 DML 您可前往 人大金仓官网 下载 QT 测试用例 。 5.1 连接数据库 #include #include#include const QString host = "127.0.0.1"; const int port = 54321; const QString dbName = "TEST"; const QString user = "SYSTEM"; const QString password = "123456"; int main() { QSqlDatabase db = QSqlDatabase::addDatabase("QKINGBASE"); db.setHostName(host); db.setDatabaseName(dbName); db.setUserName(user); db.setPassword(password); db.setPort(port); db.setConnectOptions("connect_timeout=2"); db.open(); if (!db.isOpen()) { 10 第5章 程序示例 qDebug() << db.lastError(); } db.close(); } QT 驱动支持 SSL 模式连接 KingbaseES 数据库，具体过程可参见:ref: KingbaseES 安全指南手册下的” 客户端 接口加密传输” 章节。 获取结果集 5.2 #include #include#include#include const QString host = "127.0.0.1"; const int port = 54321; const QString dbName = "TEST"; const QString user = "SYSTEM"; const QString password = "123456"; int main() { QSqlDatabase db = QSqlDatabase::addDatabase("QKINGBASE"); db.setHostName(host); db.setDatabaseName(dbName); db.setUserName(user); db.setPassword(password); db.setPort(port); db.setConnectOptions("connect_timeout=2"); db.open(); if (!db.isOpen()) { qDebug() << db.lastError(); } QSqlQuery q(db); q.exec("create table TEST(id integer, name TEXT)"); q.exec("INSERT INTO TEST(id, name) VALUES(1, 'John')") q.exec("select id from TEST"); while (q.next()) { qDebug() << q.value(0); 11 第5章 程序示例 } q.close(); db.close(); } 5.3 批量 DML bool testBatchDML(QSqlDatabase& db) { QSqlQuery sql_query(db); sql_query.exec("drop table if exists Persons"); sql_query.exec(QObject::tr("create table Persons(person_id int primary key , sex varchar(255) , age int , hobbies varchar(255) , birthday date)")); sql_query.prepare(QObject::tr("insert into Persons values(?,?,?,?, ?)")); QVariantList var_id_list , var_sex_list , var_age_list , var_hobbies_list , var_birthday_list; var_id_list << 1 << 2 << 0 << 3 << 4 << 5; var_sex_list << QObject::tr("man")<< QObject::tr("woman")<< QObject::tr("woman") << QObject::tr("man")<< QObject::tr("man")<< QObject::tr("woman"); var_age_list << 21 << 23 << 20 << 53 << 14 << 45; var_hobbies_list << QObject::tr("swim")<< QObject::tr("read")<< QObject::tr("swim") << QObject::tr("read")<< QObject::tr("play")<< QObject::tr("football"); var_birthday_list << QObject::tr("1995-04-04")<< QObject::tr("1925-12-14")<< QObject::tr("2005-02-04") << QObject::tr("2014-02-11")<< QObject::tr("1995-04-04")<