华为云用户手册

audit_database_process 参数说明：该参数决定是否对数据库的启动、停止、切换和恢复进行审计。 该参数属于SIGHUP类型参数，请参考表1中对应设置方法进行设置。 取值范围：整型，0、1。 0表示关闭数据库启动、停止、切换和恢复的审计功能。 1表示开启数据库启动、停止、切换和恢复的审计功能。 默认值：1 数据库启动时DN走备升主流程，因此DN启动时审计日志中类型为system_switch。

ecpg预处理以及编译执行 准备嵌入式SQL-C源程序，以.pgc为后缀名，ecpg负责将其转换成可被编译器编译的C语言程序。 生成的C语言程序被编译器编译为可执行文件，运行该可执行文件实现客户端程序访问数据库。示例可参考常用示例章节。 ecpg预处理以及编译处理过程 预处理：ecpg -I $GAUSSHOME/include -o test.c test.pgc ecpg预处理的参数选项如下： ecpg [OPTION]... 其中OPTION参数选项如下： -o OUTFILE：预处理嵌入式SQL-C程序将结果写入OUTFILE，OUTFILE为C语言文件。 -I DIRECTORY：头文件的搜索路径。 -c：预处理嵌入式SQL-C程序自动生成C语言文件。 --version：查看ecpg当前版本。 编译：gcc -I $GAUSSHOME/include/ecpg -I $GAUSSHOME/inlcude/libpq -L $GAUSSHOME/lib -lecpg -lpq test.c -o test 执行：./test ecpg作为编译预处理工具，若在预处理或编译过程中出现找不到头文件或者函数实现的报错信息，可以根据需要指定头文件，或者链接动态库。 ecpg需要gcc、ld等编译预处理工具，建议gcc使用7.3.0版本。 ecpg依赖的其他动态库和头文件，常见的位于$GAUSSHOME/include/libpq, $GAUSSHOME/include。 编译过程中常见的动态库依赖：-lpq、-lpq_ce、-lpthread。若开发过程中需要使用libpq通信库，则需要连接-lpq和-lpq_ce；若开发过程中需要使用多线程连接，则需要连接-lpthread。 父主题： 基于ecpg开发

执行SQL语句 创建一个表： EXEC SQL CREATE TABLE foo (number integer, ascii char(16));EXEC SQL CREATE UNIQUE INDEX num1 ON foo(number); 插入一行： EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad'); 删除一行： EXEC SQL DELETE FROM foo WHERE number = 9999; 更新表数据： EXEC SQL UPDATE foo SET ascii = 'foobar' WHERE number = 9999; 单行查询数据： EXEC SQL SELECT number INTO :FooBar FROM foo WHERE ascii = 'doodad'; 展示运行时参数： EXEC SQL SHOW search_path INTO :foo; :foo形式的记号是宿主变量，即指向C程序中的变量，可参考宿主变量章节。 父主题： 执行SQL命令

连接数据库 使用如下语句连接数据库： EXEC SQL CONNECT TO target [AS connection-name] [USER user-name]; target可以通过如下方法声明，斜体部分为变量，请根据实际情况进行修改： dbname[@hostname][:port] tcp:postgresql://hostname[:port][/dbname][?options] unix:postgresql://hostname[:port][/dbname][?options] 一个包含上述形式之一的SQL字符串 声明连接用户名的方法有以下方式： username/password username SQLIDENTIFIED BY password username USING password 如上所述，参数username以及password可以是一个SQL标识符、一个SQL字符串或一个对字符变量的引用。 connection_name表示连接名，如果一个程序只使用一个连接，则可以省略它。最近打开的连接成为当前连接。 示例： EXEC SQL CONNECT TO mydb@sql.mydomain.com; EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john; EXEC SQL BEGIN DECLARE SECTION; const char *target = "mydb@sql.mydomain.com"; const char *user = "john"; const char *passwd = "secret"; EXEC SQL END DECLARE SECTION; ... EXEC SQL CONNECT TO :target USER :user USING :passwd; /* 或者 EXEC SQL CONNECT TO :target USER :user/:passwd; */ 最后一种形式引用了字符变量，在宿主变量中将介绍如何在SQL语句中引用C语言变量。 连接目标的格式未在SQL标准中说明，因此若要开发可移植的应用，可使用上述最后一个例子的方法将连接目标字符串封装在某个变量里。 若连接语句中指定了ip-port，则必须指定username/password，该规则由 GaussDB Kernel内核通信认证所决定。若不指定ip-port，则通过本地$PGPORT(UDS协议)进行通信。 若客户连接时使用ssl安全协议，则需要使用tcp:postgresql://hostname[:port][/dbname][?options]连接格式，在options选项中配置sslmode=disable\require。 父主题： 管理数据库连接

参数说明 参数 参数说明 ctx 表示给定的上下文。 query 被执行的SQL语句。 args 被执行SQL语句需要绑定的参数。支持按位置绑定和按名称绑定，详情见如下示例。 opts 事务隔离级别和事务访问模式，其中事务隔离级别（opts.Isolation）支持范围为sql.LevelReadUncommitted,sql.LevelReadCommitted,sql.LevelRepeatableRead,sql.LevelSerializable。事务访问模式（opts.ReadOnly）支持范围为true（read only）和false（read write）。

type ColumnType type ColumnType如下表所示。 方法 描述 返回值 (ci *ColumnType)DatabaseTypeName() 返回列类型的数据库系统名称。返回空字符串表示该驱动类型名字并未被支持。 error (ci *ColumnType)DecimalSize() 返回小数类型的范围和精度。 返回值ok的值为false时，说明给定的类型不可用或者不支持。 precision, scale int64, ok bool (ci *ColumnType)Length() 返回数据列类型长度。返回值ok的值为false时，说明给定的类型不存在长度。 length int64, ok bool (ci *ColumnType)ScanType() 返回一种Go类型，该类型能够在Rows.scan进行扫描时使用。 reflect.Type (ci *ColumnType)Name() 返回数据列的名字。 string 父主题： Go接口参考

ecpg组件介绍 ecpg支持平台 表1 ecpg支持平台 操作系统 平台 EulerOS V2.0SP5 x86_64位 EulerOS V2.0SP9 ARM64位 ecpg组件 ecpg：一个用于对嵌入式SQL-C进行预处理的可执行二进制文件。 libecpg：为ecpg提供连接、执行SQL、事务等实现的动态库，包括libecpg.so、libecpg.so.6和libecpg.so.6.4，在C语言程序编译执行时通过“-lecpg”参数引用。 libpgtypes：ecpg提供的用于实现数值、日期、时间戳、区间类型数据操作运算的动态库，包括libpgtypes.so、libecpg.so.6和libecpg.so.6.4，在C语言程序编译执行时通过“-lpgtypes”参数引用。 ecpg组件的获取路径 ecpg二进制获取路径：$GAUSSHOME/bin ecpg依赖动态库路径：$GAUSSHOME/lib ecpg所需头文件路径：$GAUSSHOME/include/ecpg 父主题： 基于ecpg开发

参数 表1 数据库连接参数 参数名称 参数说明 host 主机IP地址，也可通过环境变量${PGHOST}来指定。 port 主机服务器的端口号，也可通过环境变量${PGPORT}来指定。 dbname 数据库名，也可通过环境变量${PGDATABASE}来指定。 user 要连接的用户名，也可通过环境变量${PGUSER}来指定。 password 要连接用户对应的连接密码。 connect_timeout 用于连接服务器操作的超时值，也可通过环境变量${PGCONNECT_TIMEOUT}来指定。 sslmode 启用SSL加密的方式，也可通过环境变量${PGSSLMODE}来指定。 参数取值范围： disable：不使用ssl安全连接。 allow：如果数据库服务器要求使用，则可以使用SSL安全加密连接，但不验证数据库服务器的真实性。 prefer：如果数据库支持，那么首选使用SSL安全加密连接，但不验证数据库服务器的真实性。 require：必须使用SSL安全连接，但是只做了 数据加密 ，而并不验证数据库服务器的真实性。 verify-ca：必须使用SSL安全连接，并验证服务器是否具有由可信任的证书机构签发的证书。 verify-full：必须使用SSL安全连接，并且验证服务器是否具有由可信任的证书机构签发的证书，以及验证服务器主机名是否与证书中的一致 sslkey 指定用于客户端证书的密钥位置，如果需要走SSL连接，并且该参数未指定，可通过设置环境变量${PGSSLKEY}来指定。 sslcert 指定客户端SSL证书的文件名，或者通过设置环境变量${PGSSLCERT}来指定。 sslrootcert 指定一个包含SSL证书机构（CA）证书的文件名称，或者通过设置环境变量${PGSSLROOTCERT}来指定。 sslcrl 指定ssl证书撤销列表（CRL）的文件名。列在这个文件中的证书如果存在，在尝试认证该服务器证书时会被拒绝，从而连接失败。也可通过环境变量${PGSSLCRL}来指定。 sslpassword 指定对秘钥解密成明文的密码短语，当指定该参数的时候表示sslkey是一个加密存储的文件，当前sslkey支持des/aes加密方式。 说明： DES加密算法安全性低，存在安全风险，建议使用更安全的加密算法。 disable_prepared_binary_result 字符串类型，若设置为yes，表示此连接在从预准备语句接收查询结果时不应使用二进制格式。该参数仅用于调试。 取值范围：yes/no。 binary_parameters 字符串类型，该参数表示是否始终以二进制形式发送[]byte。取值范围：yes/no。若该参数设置为yes，建议绑定参数按照[]byte绑定，可以减少内部类型转换。 target_session_attrs 指定数据库的连接类型，该参数用于识别主备节点，也可通过环境变量${PGTARGETSESSIONATTRS}来指定。默认值为“any”，共有六种：any、master、slave、preferSlave、read-write、read-only。 any：尝试连接URL连接串中的任何一个数据节点。 master：尝试连接到URL连接串中的主节点，如果找不到就抛出异常。 slave：尝试连接到URL连接串中的备节点，如果找不到就抛出异常。 preferSlave：尝试连接到URL连接串中的备数据节点（如果有可用的话），否则连接到主数据节点。 read-write：读写模式，表示只能连接主节点。 read-only：只读模式，表示只能连接备节点。 loggerLevel 日志级别，打印相关调试信息，也可通过环境变量${PG LOG GERLEVEL}来指定。 支持trace/debug/info/warn/error/none，级别从高到低。 application_name 设置正在使用连接的GO驱动的名称。缺省值为go-driver，该参数不建议用户配置。 RuntimeParams 要在连接上设置为会话默认值的运行时参数。例如参数名search_path,application_name,timezone等。各参数的详细介绍参见客户端连接缺省设置，可通过show语法查看参数是否设置成功。 enable_ce 密态数据库开关。enable_ce=1表示go驱动支持密态等值查询基本能力，enable_ce=3表示go驱动支持软硬融合全密态模式，不设置或其他值表示不开启密态数据库。 auto_sendtoken 自动传输密钥模式开关。auto_sendtoken=yes表示在DB实例连接池connection初始化时自动触发密钥传输操作，设置为no或不设置表示关闭该模式。注意，该模式无法保证密钥信息及时更新，同时当且仅当设置enable_ce=3时该模式可以被开启。

基于ecpg开发 ecpg(embedded SQL C preprocessor for GaussDB Kernel）是一种用于C语言程序的嵌入式SQL预处理器。一个嵌入式SQL程序由一种普通编程语言编写的代码（此处为C语言）和SQL命令共同组成。要构建该程序，源代码（*.pgc）首先通过嵌入式SQL预处理器，将源代码转换成一个普通C语言程序（*.c），然后再通过编译器处理。转换过的ecpg应用通过嵌入式SQL库（ecpglib）调用libpq库中的函数，与GaussDB Kernel服务器使用普通的前端/后端协议通信。 嵌入式SQL程序是插入了数据库相关动作的特殊代码的C语言程序。这种特殊代码形式通常如下： EXEC SQL ...; 这些语句在语法上取代了一个C语句，可以出现在全局或者是一个函数中。嵌入式SQL语句遵循普通SQL代码的大小写敏感规则，也允许嵌套的C语言代码风格注释（SQL标准的一部分）。不过，程序的C语言部分遵循C语言程序的标准，不支持嵌套注释。 开发流程 ecpg组件介绍 ecpg预处理以及编译执行 管理数据库连接 执行SQL命令 查询结果集 关闭数据库连接 宿主变量 执行动态SQL语句 错误处理 预处理指令 使用库函数 SQL描述符区域 常用示例 ecpg接口参考 父主题： 应用程序开发教程

参数说明 参数 参数说明 ctx 表示给定的上下文。 query 被执行的SQL语句。 args 被执行SQL语句需要绑定的参数。支持按位置绑定和按名称绑定，详情DB类型中的示例。 Query类接口Query()、QueryContext()、QueryRow()、QueryRowContext()通常用于查询语句，如SELECT语句；操作语句使用Exec()接口执行，若非查询语句通过Query类接口执行，则执行结果可能与预期不符，故不建议使用Query类接口执行非查询语句，例如UPDATE/INSERT等。 使用Query类接口执行查询语句的结果需要通过type Rows中Next()接口获取，若不通过Next()接口获取，可能会产生不可预期的错误。

参数 表1 psycopg2.connect参数 关键字 参数说明 dbname 数据库名称。 user 用户名。 password 密码。 host 数据库IP地址，可指定多IP，IP间以逗号隔开，默认为UNIX socket类型。 port 连接端口号，默认为5432。host为多IP时，如端口号相同，指定一个端口号；否则，端口号与IP一一对应，以逗号隔开。 sslmode ssl模式，ssl连接时用。 sslcert 客户端证书路径，ssl连接时用。 sslkey 客户端密钥路径，ssl连接时用。 sslrootcert 根证书路径，ssl连接时用。 hostaddr 数据库IP地址。 connect_timeout 客户端连接超时时间。 client_encoding 客户端编码格式。 application_name application_name的参数值。 fallback_application_name application_name参数的回退值。 keepalives 控制是否客户端TCP保持连接，默认为1，表示打开；值为0时，表示关闭。若UNIX域套接字连接，则忽略。 options 连接开始时发送给服务器的命令行选项。 keepalives_idle 控制向服务器发送keepalive消息之前不活动的描述，若keepalive被禁用，则忽略此参数。 keepalives_interval 控制未得到服务器确认的keepalive消息应重新传输的描述，若keepalive被禁用，则忽略此参数。 keepalives_count 控制客户端与服务端连接断开之前可能丢失的tcp保持连接的数量。 replication 确认连接使用的是复制协议而不是普通协议。 requiressl 支持sslmode设置。 sslcompression ssl压缩。设置为1，则通过ssl连接发送的数据将被压缩；设置为0，则禁用压缩。若没有建立ssl的连接，则忽略此参数。 sslcrl 证书吊销列表文件路径，验证ssl服务端证书是否可用。 requirepeer 指定服务器的操作系统用户名。 target_session_attrs 设定连接的主机的类型。主机的类型和设定的值一致时才能连接成功。指定多IP时才会校验此参数。target_session_attrs的设置规则如下： any：可以对所有类型的主机进行连接。 read-write：当连接的主机允许可读可写时，才进行连接。 read-only：仅对可读的主机进行连接。 primary（默认值）：仅对主备系统中的主机能进行连接。 standby: 仅对主备系统中的备机进行连接。 prefer-standby：首先尝试找到一个备机进行连接。如果对hosts列表的所有机器都连接失败，那么尝试“any”模式进行连接。

连接参数 表1 连接参数 参数 描述 host 要连接的主机名。如果主机名以斜杠开头，则它声明使用Unix域套接字通讯而不是TCP/IP通讯；该值就是套接字文件所存储的目录。如果没有声明host，那么默认是与位于/tmp目录（或者安装数据库的时候声明的套接字目录）里面的Unix-域套接字连接。在没有Unix域套接字的机器上，默认与localhost连接。 接受以‘,’分割的字符串来指定多个主机名，支持指定多个主机名。 hostaddr 与之连接的主机的IP地址，是标准的IPv4地址格式，比如，172.28.40.9。如果机器支持IPv6，那么也可以使用IPv6的地址。如果声明了一个非空的字符串，那么使用TCP/IP通讯机制。 接受以‘,’分割的字符串来指定多个IP地址，支持指定多个IP地址。 使用hostaddr取代host可以让应用避免一次主机名查找，这一点对于那些有时间约束的应用来说可能是非常重要的。不过，GSSAPI或SSPI认证方法要求主机名（host）。因此，应用下面的规则： 如果声明了不带hostaddr的host那么就强制进行主机名查找。 如果声明中没有host，hostaddr的值给出服务器网络地址；如果认证方法要求主机名，那么连接尝试将失败。 如果同时声明了host和hostaddr，那么hostaddr的值作为服务器网络地址。host的值将被忽略，除非认证方法需要它，在这种情况下它将被用作主机名。 须知： 要注意如果host不是网络地址hostaddr处的服务器名，那么认证很有可能失败。 如果主机名（host）和主机地址都没有，那么libpq将使用一个本地的Unix域套接字进行连接；或者是在没有Unix域套接字的机器上，它将尝试与localhost连接。 port 主机服务器的端口号，或者在Unix域套接字连接时的套接字扩展文件名。 接受以‘,’分割的字符串来指定多个端口号，支持指定多个端口号。 user 要连接的用户名，缺省是与运行该应用的用户操作系统名同名的用户。 dbname 数据库名，缺省和用户名相同。 password 如果服务器要求口令认证，所用的口令。 connect_timeout 连接的最大等待时间，以秒计（用十进制整数字符串书写），0或者不声明表示无穷。不建议把连接超时的值设置得小于2秒。 client_encoding 为这个连接设置client_encoding配置参数。除了对应的服务器选项接受的值，你可以使用auto从客户端中的当前环境中确定正确的编码（Unix系统上是LC_CTYPE环境变量）。 tty 忽略（以前，该参数指定了发送服务器调试输出的位置）。 options 添加命令行选项以在运行时发送到服务器。 application_name 为application_name配置参数指定一个值，表明当前用户身份。 fallback_application_name 为application_name配置参数指定一个后补值。如果通过一个连接参数或PGAPPNAME环境变量没有为application_name给定一个值，将使用这个值。在一般工具程序中，若设置一个默认名，但不希望这个默认名被用户覆盖，可以通过指定一个后补值来实现。 keepalives 控制客户端侧的TCP保持激活是否使用。缺省值是1，意思为打开，但是如果不想要保持激活，你可以更改为0，意思为关闭。通过Unix域套接字做的连接忽略这个参数。 keepalives_idle 在TCP应该发送一个保持激活的信息给服务器之后，控制不活动的秒数。0值表示使用系统缺省。通过Unix域套接字做的连接或者如果禁用了保持激活则忽略这个参数。 keepalives_interval 在TCP保持激活信息没有被应该传播的服务器承认之后，控制秒数。0值表示使用系统缺省。通过Unix域套接字做的连接或者如果禁用了保持激活则忽略这个参数。 keepalives_count 控制TCP发送保持激活信息的次数。0值表示使用系统缺省。通过Unix域套接字做的连接或者如果禁用了保持激活则忽略这个参数。 tcp_user_timeout 在支持TCP_USER_TIMEOUT套接字选项的操作系统上，指定传输的数据在TCP连接被强制关闭之前可以保持未确认状态的最大时长。0值表示使用系统缺省。通过Unix域套接字做的连接忽略这个参数。 rw_timeout 设置客户端连接读写超时时间。 sslmode 启用SSL加密的方式： disable：不使用SSL安全连接。 allow：如果数据库服务器要求使用，则可以使用SSL安全加密连接，但不验证数据库服务器的真实性。 prefer：如果数据库支持，那么首选使用SSL安全加密连接，但不验证数据库服务器的真实性。 require：必须使用SSL安全连接，但是只做了数据加密，而并不验证数据库服务器的真实性。 verify-ca：必须使用SSL安全连接，当前windows ODBC不支持cert方式认证。 verify-full：必须使用SSL安全连接，当前windows ODBC不支持cert方式认证。 sslcompression 如果设置为1（默认），SSL连接之上传送的数据将被压缩（这要求OpenSSL版本为0.9.8或更高）。如果设置为0，压缩将被禁用（这要求OpenSSL版本为1.0.0或更高）。如果建立的是一个没有SSL的连接，这个参数会被忽略。如果使用的OpenSSL版本不支持该参数，它也会被忽略。压缩会占用CUP时间，但是当瓶颈为网络时可以提高吞吐量。如果CPU性能是限制因素，禁用压缩能够改进响应时间和吞吐量。 sslcert 这个参数指定客户端SSL证书的文件名，它替换默认的~/.postgresql/postgresql.crt。如果没有建立SSL连接，这个参数会被忽略。 sslkey 这个参数指定用于客户端证书的密钥位置。它能指定一个会被用来替代默认的~/.postgresql/postgresql.key的文件名，或者它能够指定一个从外部“引擎”（引擎是OpenSSL的可载入模块）得到的密钥。一个外部引擎说明应该由一个冒号分隔的引擎名称以及一个引擎相关的关键标识符组成。如果没有建立SSL连接，这个参数会被忽略。 sslrootcert 这个参数指定一个包含SSL证书机构（CA）证书的文件名称。如果该文件存在，服务器的证书将被验证是由这些机构之一签发。默认值是~/.postgresql/root.crt。 sslcrl 这个参数指定SSL证书撤销列表（CRL）的文件名。列在这个文件中的证书如果存在，在尝试认证该服务器证书时会被拒绝。默认值是~/.postgresql/root.crl。 requirepeer 这个参数指定服务器的操作系统用户，例如requirepeer=postgres。当建立一个Unix域套接字连接时，如果设置了这个参数，客户端在连接开始时检查服务器进程是否运行在指定的用户名之下。如果发现不是，该连接会被一个错误中断。这个参数能被用来提供与TCP/IP连接上SSL证书相似的服务器认证（注意，如果Unix域套接字在/tmp或另一个公共可写的位置，任何用户能启动一个在那里侦听的服务器。使用这个参数来保证你连接的是一个由可信用户运行的服务器）。这个选项只在实现了peer认证方法的平台上受支持。 krbsrvname 当用GSSAPI认证时，要使用的Kerberos服务名。为了让Kerberos认证成功，这必须匹配在服务器配置中指定的服务名。 gsslib 用于GSSAPI认证的GSS库。只用在Windows上。设置为gssapi可强制libpq用GSSAPI库来代替默认的SSPI进行认证。 service 用于附加参数的服务名。它指定保持附加连接参数的pg_service.conf中的一个服务名。这允许应用只指定一个服务名，这样连接参数能被集中维护。 authtype 不再使用“authtype”，因此将其标记为“不显示”。我们将其保留在数组中，以免拒绝旧应用程序中的conninfo字符串，这些应用程序可能仍在尝试设置它。 remote_nodename 指定连接本地节点的远端节点名称。 localhost 指定在一个连接通道中的本地地址。 localport 指定在一个连接通道中的本地端口。 fencedUdfRPCMode 控制fenced UDF RPC协议是使用unix域套接字或特殊套接字文件名。缺省值是0，意思为关闭，使用unix domain socket模式，文件类型为“.s.PGSQL.%d”，但是要使用fenced udf ，文件类型为.s.fencedMaster_unixdomain，可以更改为1，意思为开启。 replication 这个选项决定是否该连接应该使用复制协议而不是普通协议。这是PostgreSQL的复制连接以及pg_basebackup之类的工具在内部使用的协议，但也可以被第三方应用使用。支持下列值，大小写无关： true、on、yes、1：连接进入到物理复制模式。 database：连接进入到逻辑复制模式，连接到dbname参数中指定的数据库。 false、off、no、0：该连接是一个常规连接，这是默认行为。 在物理或者逻辑复制模式中，仅能使用简单查询协议。 backend_version 传递到远端的后端版本号。 prototype 设置当前协议级别，默认：PROTO_TCP。 enable_ce 控制是否允许客户端连接全密态数据库。默认0，如果需要开启密态等值查询基本能力，则修改为1，如果需要开启密态支持客户端排序，则修改为2。 connection_info Connection_info是一个包含driver_name、driver_version、driver_path和os_user的json字符串。 如果不为NULL，使用connection_info忽略connectionExtraInf 如果为NULL，生成与libpq相关的连接信息字符串，当connectionExtraInf为false时connection_info只有driver_name和driver_version。 connectionExtraInf 设置connection_info是否存在扩展信息，默认值为0，如果包含其他信息，则需要设置为1。 target_session_attrs 设定连接的主机的类型。主机的类型和设定的值一致时才能连接成功。指定多IP时才会校验此参数。target_session_attrs的设置规则如下： any：可以对所有类型的主机进行连接。 read-write：当连接的主机允许可读可写时，才进行连接。 read-only：仅对可读的主机进行连接。 primary（默认值）：仅对主备系统中的主机能进行连接。 standby: 仅对主备系统中的备机进行连接。 prefer-standby：首先尝试找到一个备机进行连接。如果对hosts列表的所有机器都连接失败，那么尝试“any”模式进行连接。 父主题： 基于libpq开发

连接数据库（SSL方式） 用户通过psycopy2连接GaussDB Kernel服务器时，可以通过开启SSL加密客户端和服务器之间的通讯。在使用SSL时，默认用户已经获取了服务端和客户端所需要的证书和私钥文件，关于证书等文件的获取请参考Openssl相关文档和命令。 使用*.ini文件（python的configparser包可以解析这种类型的配置文件）保存数据库连接的配置信息。 在连接选项中添加SSL连接相关参数：sslmode，sslcert，sslkey，sslrootcert。 sslmode：可选项见表1。 sslcert：客户端证书路径。 sslkey：客户端密钥路径。 sslrootcert：根证书路径。 使用psycopg2.connect函数获得connection对象。 使用connection对象创建cursor对象。 表1 sslmode的可选项及其描述 sslmode 是否会启用SSL加密 描述 disable 否 不适用SSL安全连接。 allow 可能 如果数据库服务器要求使用，则可以使用SSL安全加密连接，但不验证数据库服务器的真实性。 prefer 可能 如果数据库支持，那么首选使用SSL连接，但不验证数据库服务器的真实性。 require 是 必须使用SSL安全连接，但是只做了数据加密，而并不验证数据库服务器的真实性。 verify-ca 是 必须使用SSL安全连接。 verify-full 是 必须使用SSL安全连接，目前GaussDB Kernel暂不支持。 父主题： 基于Psycopg开发

示例：常用操作 import psycopg2#创建连接对象conn=psycopg2.connect(database="postgres",user="user",password="password",host="localhost",port=port)cur=conn.cursor() #创建指针对象#创建连接对象（SSl连接）conn = psycopg2.connect(dbname="postgres", user="user", password="password", host="localhost", port=port, sslmode="verify-ca", sslcert="client.crt",sslkey="client.key",sslrootcert="cacert.pem")注意： 如果sslcert、sslkey、sslrootcert没有填写，默认取当前用户.postgresql目录下对应的client.crt、client.key、root.crt# 创建表cur.execute("CREATE TABLE student(id integer,name varchar,sex varchar);")#插入数据cur.execute("INSERT INTO student(id,name,sex) VALUES(%s,%s,%s)",(1,'Aspirin','M'))cur.execute("INSERT INTO student(id,name,sex) VALUES(%s,%s,%s)",(2,'Taxol','F'))cur.execute("INSERT INTO student(id,name,sex) VALUES(%s,%s,%s)",(3,'Dixheral','M'))# 获取结果cur.execute('SELECT * FROM student')results=cur.fetchall()print (results)# 关闭连接conn.commit()cur.close()conn.close()psycopg2常用连接方式1. conn = psycopg2.connect(dbname="postgres", user="user", password="password", host="localhost", port=port)2. conn = psycopg2.connect("dbname=postgres user=user password=password host=localhost port=port")3. 使用日志import loggingimport psycopg2from psycopg2.extras import LoggingConnectionlogging.basicConfig(level=logging.DEBUG) # 日志级别logger = logging.getLogger(__name__)db_settings = { "user": "user", "password": "password", "host": "localhost", "database": "postgres", "port": port}# LoggingConnection默认记录所有SQL，可自行实现filter过滤不需要的或敏感的SQL，下面给出了简单的过滤password相关SQL的示例class SelfLoggingConnection(LoggingConnection): def filter(self, msg, curs): if db_setting['password'] in msg.decode(): return b'queries containing the password will not be recorded' return msgconn = psycopg2.connect(connection_factory=SelfLoggingConnection, **db_settings)conn.initialize(logger) LoggingConnection默认记录所有SQL信息，且不会对敏感信息进行脱敏，可通过filter函数自行定义输出的SQL内容。 日志功能是psycopg2为了方便开发者显性调试全量SQL而提供个额外功能，默认情况下不需要使用。 该功能会在pyscopg2执行SQL语句前打印SQL语句，但是，需要在debug日志级别下才会输出。该功能不是默认功能，只是在有特殊需要的时候才使用，没有特别需求，不建议使用。详情参考：https://www.psycopg.org/docs/extras.html?highlight=loggingconnection。 父主题： 基于Psycopg开发

Psycopg接口参考 Psycopg接口是一套提供给用户的API方法，本节将对部分常用接口做具体描述。 psycopg2.connect() connection.cursor() cursor.execute(query,vars_list) curosr.executemany(query,vars_list) connection.commit() connection.rollback() cursor.fetchone() cursor.fetchall() cursor.close() connection.close() 父主题： 基于Psycopg开发

注意事项 在非阻塞连接上发送任何命令或数据之后，调用PQflush。如果返回1，则等待套接字变为读或写就绪。如果为写就绪状态，则再次调用PQflush。如果已经读到，调用PQconsumeInput，然后再次调用PQflush。重复，直到PQflush返回0。(必须检查读就绪，并用PQconsumeInput排出输入，因为服务器可以阻止试图向我们发送数据，例如。通知信息，直到我们读完它才会读我们的数据。)一旦PQflush返回0，就等待套接字准备好，然后按照上面描述读取响应。

基于Psycopg开发 Psycopg是一种用于执行SQL语句的PythonAPI，可以为PostgreSQL、GaussDB Kernel数据库提供统一访问接口，应用程序可基于它进行数据操作。Psycopg2是对libpq的封装，主要使用C语言实现，既高效又安全。它具有客户端游标和服务器端游标、异步通信和通知、支持“COPY TO/COPY FROM”功能。支持多种类型Python开箱即用，适配PostgreSQL数据类型；通过灵活的对象适配系统，可以扩展和定制适配。Psycopg2兼容Unicode和Python 3。 GaussDB Kernel数据库提供了对Psycopg2特性的支持，并且支持psycopg2通过SSL模式连接。 表1 Psycopg支持平台 操作系统 平台 EulerOS 2.5 x86_64位 EulerOS 2.8 ARM64位 Kylin x86_64位 Kylin ARM64位 UnionTech V20 x86_64位 UnionTech V20 ARM64位 psycopg2在编译过程中，会链接（link）GaussDB Kernel的openssl，GaussDB Kernel的openssl与操作系统自带的openssl可能不兼容。如果遇到不兼容现象，例如提示"version 'OPENSSL_1_1_1f' not found"，请使用环境变量LD_LIBRARY_PATH进行隔离，以避免混用操作系统自带的openssl与GaussDB Kernel依赖的openssl。 例如，在执行某个调用psycopg2的应用软件client.py时，将环境变量显性赋予该应用软件： export LD_LIBRARY_PATH=/path/to/gaussdb/libs:$LD_LIBRARY_PATH python client.py 其中，/path/to/pyscopg2/lib 表示GaussDB Kernel依赖的openssl库所在目录，需根据文件实际存储路径修改。 Psycopg包 开发流程 加载驱动 连接数据库 执行SQL语句 处理结果集 关闭连接 连接数据库（SSL方式） 示例：常用操作 Psycopg接口参考 父主题： 应用程序开发教程

加载驱动 在使用驱动之前，需要做如下操作： 先解压版本对应驱动包，使用root用户将psycopg2拷贝到python安装目录下的site-packages文件夹下。 修改psycopg2目录权限为755。 将psycopg2目录添加到环境变量$PYTHONPATH，并使之生效。 对于非数据库用户，需要将解压后的lib目录，配置在LD_LIBRARY_PATH中。 在创建数据库连接之前，需要先加载如下数据库驱动程序： import psycopg2 父主题： 基于Psycopg开发

原型 int PQsendQueryPrepared(PGconn *conn, const char *stmtName, int nParams, const char * const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat);

原型 int PQsendQueryParams(PGconn *conn, const char *command, int nParams, const Oid *paramTypes, const char * const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat);

返回值 PQresultStatus：命令执行结果的枚举，包括： 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627282930 PQresultStatus可以返回下面数值之一：PGRES_EMPTY_QUERY发送给服务器的字串是空的。PGRES_COMMAND_OK成功完成一个不返回数据的命令。PGRES_TUPLES_OK成功执行一个返回数据的查询（比如SELECT或者SHOW）。PGRES_COPY_OUT（从服务器）Copy Out （拷贝出）数据传输开始。PGRES_COPY_INCopy In（拷贝入）（到服务器）数据传输开始。PGRES_BAD_RESPONSE服务器的响应无法理解。PGRES_NONFATAL_ERROR发生了一个非致命错误（通知或者警告）。PGRES_FATAL_ERROR发生了一个致命错误。PGRES_COPY_BOTH拷贝入/出（到和从服务器）数据传输开始。这个特性当前只用于流复制， 所以这个状态不会在普通应用中发生。PGRES_SINGLE_TUPLEPGresult包含一个来自当前命令的结果元组。 这个状态只在查询选择了单行模式时发生

注意事项 PQprepare创建一个为PQexecPrepared执行用的预备语句，本特性支持命令的重复执行，不需要每次都进行解析和规划。PQprepare仅在协议3.0及以后的连接中支持，使用协议2.0时，PQprepare将失败。 该函数从查询字符串创建一个名为stmtName的预备语句，该查询字符串必须包含一个SQL命令。stmtName可以是""来创建一个未命名的语句，在这种情况下，任何预先存在的未命名的语句都将被自动替换；否则，如果在当前会话中已经定义了语句名称，则这是一个错误。如果使用了任何参数，那么在查询中将它们称为$1,$2等。nParams是在paramTypes[]数组中预先指定类型的参数的数量。（当nParams为0时，数组指针可以为NULL） paramTypes[]通过OID指定要分配给参数符号的数据类型。如果paramTypes为NULL ，或者数组中的任何特定元素为零，服务器将按照对非类型化字面字符串的相同方式为参数符号分配数据类型。另外，查询可以使用数字高于nParams的参数符号；还将推断这些符号的数据类型。 通过执行SQLPREPARE语句，还可以创建与PQexecPrepared一起使用的预备语句。此外，虽然没有用于删除预备语句的libpq函数，但是SQL DEALLOCATE语句可用于此目的。

异步命令处理 PQexec函数对普通的同步应用里提交命令已经足够使用。但是它却有几个缺陷，而这些缺陷可能对某些用户很重要： PQexec等待命令结束，而应用可能还有其它的工作要做（比如维护用户界面等），此时PQexec可不想阻塞在这里等待响应。 因为客户端应用在等待结果的时候是处于挂起状态的，所以应用很难判断它是否该尝试结束正在进行的命令。 PQexec只能返回一个PGresult结构。如果提交的命令字符串包含多个SQL命令，除了最后一个PGresult以外都会被PQexec丢弃。 PQexec总是收集命令的整个结果，将其缓存在一个PGresult中。虽然这为应用简化了错误处理逻辑，但是对于包含多行的结果是不切实际的。 不想受到这些限制的应用可以改用下面的函数，这些函数也是构造PQexec的函数：PQsendQuery和PQgetResult。PQsendQueryParams，PQsendPrepare，PQsendQueryPrepared也可以和PQgetResult一起使用。 PQsendQuery PQsendQueryParams PQsendPrepare PQsendQueryPrepared PQflush 父主题： libpq接口参考

原型 PGresult* PQexecPreparedBatch(PGconn* conn, const char* stmtName, int nParams, int nBatchCount, const char* const* paramValues, const int* paramLengths, const int* paramFormats, int resultFormat);

参数 表1 PQexecPreparedBatch参数 关键字 参数说明 conn 连接句柄。 stmtName stmt名称，可以用""或者NULL来引用未命名语句，否则它必须是一个现有预备语句的名字。 nParams 参数个数。 nBatchCount 批量数。 paramValues 参数的实际值。 paramLengths 参数的实际数据长度。 paramFormats 参数的格式（文本或二进制）。 resultFormat 结果的格式（文本或二进制）。

原型 PGresult* PQexecPrepared(PGconn* conn, const char* stmtName, int nParams, const char* const* paramValues, const int* paramLengths, const int* paramFormats, int resultFormat);

参数 表1 PQexecPrepared参数 关键字 参数说明 conn 连接句柄。 stmtName stmt名称，可以用""或者NULL来引用未命名语句，否则它必须是一个现有预备语句的名字。 nParams 参数个数。 paramValues 参数的实际值。 paramLengths 参数的实际数据长度。 paramFormats 参数的格式（文本或二进制）。 resultFormat 结果的格式（文本或二进制）。

原型 PGresult* PQexecParams(PGconn* conn, const char* command, int nParams, const Oid* paramTypes, const char* const* paramValues, const int* paramLengths, const int* paramFormats, int resultFormat);

注意事项 状态可以是多个值之一。但是，在异步连接过程之外只能看到其中两个：CONNECTION_OK和CONNECTION_BAD。与数据库的良好连接状态为CONNECTION_OK。状态表示连接尝试失败CONNECTION_BAD。通常，“正常”状态将一直保持到PQfinish，但通信失败可能会导致状态CONNECTION_BAD过早变为。在这种情况下，应用程序可以尝试通过调用进行恢复PQreset。

原型 PGresult* PQexecParamsBatch(PGconn* conn, const char* command, int nParams, int nBatch, const Oid* paramTypes, const char* const* paramValues, const int* paramLengths, const int* paramFormats, int resultFormat);