GaussDB应用程序开发教程概述

JDBC

JDBC（Java Database Connectivity，Java数据库连接）是用于执行SQL语句的Java API，可以为多种关系数据库提供统一访问接口。它允许Java应用程序通过SQL语句来执行数据库操作，包括查询、插入、更新和删除数据等。

JDBC架构主要包括以下组件：

• JDBC API：提供Java应用程序与数据库交互的标准接口（如Connection、Statement、ResultSet等）。
• 驱动程序管理器：加载和管理JDBC驱动程序，根据连接请求url匹配合适的驱动。
• 驱动程序：实现JDBC API的接口，将Java调用转换为数据库协议，发送SQL到数据库执行，并将结果返回到应用程序。

Java应用程序发起数据库操作请求（如查询、更新），通过JDBC API接口与JDBC驱动管理程序通信，而JDBC驱动管理程序负责加载和管理JDBC驱动程序。JDBC驱动程序则负责与特定的数据库通信，发送SQL到数据库。数据库执行SQL操作并返回结果集。JDBC的系统架构请参见图1。

图1 JDBC系统架构

以下是JDBC的一些关键特点和用法：

1. 数据库连接管理：JDBC允许应用程序建立与数据库的连接，并管理这些连接的生命周期。
2. SQL执行： 使用JDBC可以执行SQL查询、更新、删除等操作。这通过在Java代码中构建SQL语句并将其发送到数据库来实现。
3. 事务管理：JDBC支持事务管理，可以通过JDBC API来启动、提交或回滚事务，确保数据库操作的一致性和完整性。
4. 异常处理： JDBC定义了一组异常类来处理数据库操作期间可能发生的各种异常情况，开发人员可以使用try-catch块来捕获和处理这些异常。
5. 批处理操作：JDBC提供了批处理功能，允许一次性执行多个SQL语句，从而提高数据库操作的效率。
6. 元数据访问： 通过JDBC可以获取数据库的元数据信息，如表结构、列名、数据类型等，从而动态地构建SQL查询或根据数据库结构进行操作。

总的来说，JDBC提供了一个灵活且强大的桥梁，使Java应用程序能够与各种不同的数据库进行交互，从而实现数据的持久化和管理。GaussDB数据库提供了对JDBC 4.2特性的支持，需要使用JDK1.8、JDK17、JDK21版本（需使用对应版本的驱动包）编译程序代码，不支持JDBC桥接ODBC方式。

基于JDBC开发详细教程请参见基于JDBC开发。

ODBC

ODBC（Open Database Connectivity，开放式数据库连接）是由Microsoft基于Open Group与ISO/IEC的CLI（Call Level Interface）规范制定的数据库访问标准接口，使用C/C++语言提供统一的API，使应用程序能够在不同数据库管理系统（DBMS）之间实现跨平台访问，而无需关注底层数据库类型或操作系统差异。

ODBC的核心目标是最大化互操作性：同一套应用程序源码可通过更换驱动程序访问不同的DBMS。应用程序发出的ODBC函数调用由驱动管理程序处理，并在运行期动态加载对应数据库的驱动程序。驱动程序负责将SQL请求转化为特定数据库能够识别的指令，并将执行结果返回给应用程序。这样的抽象机制类似打印机驱动屏蔽硬件差异，使ODBC成为数据库访问的通用层，从而增强了跨平台能力、可维护性和扩展性。

ODBC的架构包括三个主要组成部分：

• 应用程序：负责业务逻辑与发起ODBC调用。
• 驱动程序管理器：负责接收、分发并管理驱动程序。
• 驱动程序：处理ODBC函数调用，将SQL请求提交到特定数据源，并将结果返回到应用程序。

应用程序与驱动程序管理器之间通过标准ODBC API连接，驱动管理器再负责管理ODBC驱动的加载和执行流程。更直观的架构请参考图2。

图2 ODBC系统架构

作为数据库API标准，ODBC与具体DBMS、操作系统及编程语言均保持独立性。ODBC API基于Open Group与ISO/IEC的CLI规范，ODBC 3.x已完全实现该标准。GaussDB目前支持ODBC 3.5，并提供在Linux/Unix以及Windows环境下的驱动使用能力：

• Unix/Linux环境采用unixODBC-2.3.7作为驱动程序管理器。
• Windows系统采用操作系统默认内置的ODBC驱动程序管理器，可在“控制面板 > 管理工具 > 数据源（ODBC）”中进行管理。

Linux/Unix环境支持列表参见表1。

Windows环境支持列表请参见表2。

在使用ODBC访问GaussDB时，除了标准ODBC行为外，还需特别注意GaussDB当前ODBC驱动的如下若干限制，这些限制可能影响部分SQL功能或数据类型的使用。

• ODBC不支持自定义类型，不支持在存储过程中使用自定义类型参数。
• 当数据库开启proc_outparam_override参数时（即启用GUC参数behavior_compat_options的proc_outparam_override配置项），ODBC无法正常调用带有out参数的存储过程。
• ODBC不支持容灾集群的备机读。
• 当表类型为HASHBUCKET表、SLICEBUCKET表和复制表时或者操作类型为SQL_UPDATE时，ODBC不支持使用可更新游标功能。
• ODBC驱动基于开源版本，在处理TINYINT、SMALLDATETIME、NVARCHAR2等类型时，可能出现类型不兼容的问题。

有关ODBC开发详细教程请参见基于ODBC开发。

libpq

libpq是GaussDB提供的C语言客户端接口库。是C/C++应用程序访问GaussDB数据库的主要开发接口。

libpq封装了客户端与数据库服务器之间的完整通信协议，为开发者提供了一组功能丰富、性能高效的函数接口。通过libpq，应用程序可以完成数据库连接的建立、管理、SQL语句的执行、结果集的处理、事务控制以及各种高级数据库操作。其采用轻量级设计，适合对性能、并发和资源占用有较高要求的业务场景。同时也是其他几个GaussDB应用程序接口的底层引擎，比如ODBC、Psycopg、ecpg等依赖的库文件。

libpq的系统架构主要由以下2个部分组成：

应用程序：开发者编写的C/C++程序，通过调用libpq提供的API完成所有数据库操作。

libpq客户端库：核心接口库（libpq.so），负责API函数的实现、协议封装、连接状态维护、数据编解码以及错误处理。

libpq系统架构图如下图所示：

图3 libpq系统架构

libpq支持的操作系统平台与GaussDB内核所支持的操作系统平台保持一致，并随数据库内核版本更新而同步更新。

libpq本身不是线程安全的。在多线程应用程序中，建议每个线程使用独立的连接，或通过外部连接池进行管理。

基于libpq开发详细教程请参见基于libpq开发。

Psycopg

Psycopg是一种用于执行SQL语句的PythonAPI，可以为GaussDB数据库提供统一访问接口，应用程序可基于它进行数据操作。Psycopg2是对libpq的封装，主要使用C语言实现，既高效又安全。它具有客户端游标和服务器端游标、异步通信和通知、支持“COPY TO/COPY FROM”功能。支持多种类型Python开箱即用，适配GaussDB数据类型。通过灵活的对象适配系统，可以扩展和定制适配。Psycopg2兼容Unicode。

GaussDB数据库提供了对Psycopg2特性的支持，并且支持psycopg2通过SSL模式连接。

Psycopg系统架构主要由以下4个部分组成：

• 应用程序：负责业务逻辑。通过调用标准的Python对象和方法来发起数据库操作请求并接收返回的数据结果。
• psycopg2标准接口：Python数据库API规范（DB-API 2.0）的实现层。核心作用是把Python应用的请求（如执行SQL语句、处理查询结果）规范化，并作为纽带向下传递给C扩展模块。
• C扩展模块：负责将Python的数据类型和对象快速转换成底层的C数据结构，并直接调用libpq的函数。
• libpq库：底层C动态链接库，真正负责与数据库服务端建立TCP连接并收发网络协议包。

Psycopg系统架构如图4所示。

图4 psycopg系统架构

目前仅支持Linux/Unix环境，请参见表3。

psycopg2在编译过程中，会链接（link）GaussDB的openssl，GaussDB的openssl与操作系统自带的openssl可能不兼容。如果遇到不兼容现象，例如提示"version 'OPENSSL_1_1_1f' not found"，请使用环境变量LD_LIBRARY_PATH进行隔离，以避免混用操作系统自带的openssl与GaussDB依赖的openssl。

例如，在执行某个调用psycopg2的应用软件client.py时，将环境变量显性赋予该应用软件：

export LD_LIBRARY_PATH=/path/to/psycopg2/lib:$LD_LIBRARY_PATH python client.py

其中，/path/to/psycopg2/lib表示GaussDB依赖的openssl库所在目录，需根据文件实际存储路径修改。

基于Psycopg开发详细教程请参见基于Psycopg开发。

Go

Go驱动是一个用于连接和操作GaussDB数据库的Go语言驱动。它提供了一些用于连接和操作GaussDB数据库的接口，可以用于执行查询、插入、更新和删除等操作。

Go架构主要包括以下组件：

• 应用程序：业务逻辑的载体，负责发起数据库操作请求（如SQL查询、事务处理等）。
• database/sql：Go标准库提供的抽象层，定义统一的数据库操作接口（如sql.Open、type DB等）。
• 驱动程序管理器：加载和管理Go驱动程序，根据调用database/sql中sql.Open接口的driverName参数以匹配相应驱动。
• 驱动程序：实现database/sql数据库操作接口，将Go调用转换为数据库协议，发送SQL到数据库执行，并将结果返回到应用程序。

Go系统架构如图5所示。

图5 Go系统架构

以下是Go驱动当前支持的部分功能及其用法：

1. 数据库连接：Go驱动支持通过db.Open连接数据库。连接串支持URL和DSN两种格式。
2. SQL执行与查询：Go驱动提供接口如db.Exec、db.Query等，可以用于SQL的执行与查询 。
3. 事务管理：Go驱动支持Tx接口进行事务管理，其中实现了启动、提交、回滚事务等方法，确保数据库操作的一致性和完整性。
4. 元数据访问： Go驱动提供ColumnType接口用于查询数据库中列属性信息，包括是否可以为空、数据库类型名称、长度和小数位数等信息。
5. 可重用性：Go驱动提供Prepare方法用于预编译SQL，该SQL可以被多次执行，只需改变传入参数，提高数据库可重用性。

基于Go驱动开发详细教程请参见基于Go驱动开发。

ecpg

ecpg（embedded SQL C preprocessor for GaussDB）是一种用于C语言程序的嵌入式SQL预处理器，旨在为 C语言程序提供直接集成SQL能力的标准化手段。ecpg允许开发者在C源代码中以EXEC SQL为前缀直接嵌入标准SQL语句。

EXEC SQL ...;

这些语句在语法上取代了一个C语句，可以出现在全局或者是具体函数内部。其核心价值在于通过预处理技术隐藏了底层通信及协议处理的复杂性，实现了宿主语言（C）与数据库语言（SQL）在语法层面的深度融合。

ecpg的实现机制遵循“预处理 -> 编译 -> 链接”的典型分层架构。其核心工作流如下图6所示：

图6 ecpg架构

如上图所示，一个嵌入式SQL程序由一种普通编程语言编写的代码（此处为C语言）和SQL命令共同组成。要构建该程序，源代码（*.pgc）首先通过嵌入式SQL预处理器，将源代码转换成一个普通C语言程序（*.C文件），然后再通过编译器处理，将嵌入式逻辑转化为.O文件。转换过的ecpg应用通过嵌入式SQL库（ecpglib）调用libpq库中的函数，与GaussDB服务器使用普通的前端/后端协议通信。

ecpg的核心优势如下：

• 开发效率：通过SQL与C的深度融合，消除繁琐的API调用逻辑，代码量更少，维护更直观。
• 数据安全：ecpg的预处理器能够自动处理C程序与数据库之间的数据交换逻辑，确保数据类型在传输过程中的精确映射。这种机制有效规避了手动处理数据转换时的潜在风险，并通过参数化处理天然抵御SQL注入攻击。
• 提前预警：不同于运行时才触发报错的传统API，ecpg预处理器能够对嵌入的SQL语句进行静态语法分析。这使得开发者在构建阶段即可识别大部分语法错误，从而降低了调试成本并提升了软件的鲁棒性。

ecpg程序在编写时需遵循特定的语法规范，以区分SQL逻辑与C语言逻辑：

• 嵌入式SQL语句遵循普通SQL代码的大小写敏感规则，并且允许嵌套的C语言代码风格注释（SQL标准的一部分）。
• 程序的C语言部分遵循C语言程序的标准，不支持嵌套注释。

基于ecpg开发详细教程请参见基于ecpg开发。