1.概述

pycouxdb是Python语⾔的uxdb数据库接⼝。它的主要优势在于完全⽀持Python DB API 2.0，以及安全的多线程⽀持。它适⽤于随时创建、销毁⼤量游标的、和产⽣⼤量并发INSERT、UPDATE操作的多线程数据库应⽤。

2.快速启动

2.1.安装

  1. 下载驱动程序

  2. 解压驱动文件

    [uxdb@localhost uxdb-python-UX-UXSQL]$ ll
total 120
-rwxr-xr-x. 1 uxdb uxdb   475 Apr 26  2023 AUTHORS
drwxr-xr-x. 9 uxdb uxdb   182 Jan  4 01:50 build
drwxr-xr-x. 2 uxdb uxdb   132 Jan  4 01:50 dist
drwxr-xr-x. 3 uxdb uxdb   132 Jan  4 01:50 doc
-rwxr-xr-x. 1 uxdb uxdb   157 Apr 26  2023 INSTALL
drwxr-xr-x. 2 uxdb uxdb   235 Jan  4 01:50 lib
-rwxr-xr-x. 1 uxdb uxdb  2240 Apr 26  2023 LICENSE
-rwxr-xr-x. 1 uxdb uxdb  2545 Apr 26  2023 Makefile
-rwxr-xr-x. 1 uxdb uxdb   399 Apr 26  2023 MANIFEST.in
-rwxr-xr-x. 1 uxdb uxdb 50040 Apr 26  2023 NEWS
-rwxr-xr-x. 1 uxdb uxdb  4760 Apr 26  2023 PKG-INFO
drwxr-xr-x. 2 uxdb uxdb  4096 Jan  4 01:50 pycouxdb
drwxr-xr-x. 2 uxdb uxdb    90 Jan  4 01:50 pycouxdb.egg-info
-rwxr-xr-x. 1 uxdb uxdb  2164 Apr 26  2023 README.md
drwxr-xr-x. 2 uxdb uxdb   122 Jan  4 01:50 scripts
-rwxr-xr-x. 1 uxdb uxdb   170 Apr 26  2023 setup.cfg
-rwxr-xr-x. 1 uxdb uxdb 22822 Apr 26  2023 setup.py
drwxr-xr-x. 3 uxdb uxdb  4096 Jan  4 01:50 tests
[uxdb@localhost uxdb-python-UX-UXSQL]$

  3. 安装python驱动

    python setup.py install  

    [uxdb@localhost uxdb-python-UX-UXSQL]$ sudo python setup.py install
[sudo] password for uxdb: 
/usr/lib64/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'project_urls'
  warnings.warn(msg)
/usr/lib64/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'python_requires'
  warnings.warn(msg)
running install
running bdist_egg
running egg_info
writing pycouxdb.egg-info/PKG-INFO
writing dependency_links to pycouxdb.egg-info/dependency_links.txt
writing top-level names to pycouxdb.egg-info/top_level.txt

Error: ux_config executable not found.

ux_config is required to build pycouxdb from source. Please add the directory
containing ux_config to the $PATH or specify the full executable path with the:

    python setup.py build_ext --ux-config /path/to/ux_config build

or with the ux_config option in setup.cfg.

If you prefer to avoid building pycouxdb from source, please install the PyPI
'pycouxdb-binary' package instead.

For further information please check the 'doc/src/install.rst' file (also at
<http://initd.org/pycouxdb/docs/install.html>)

[uxdb@localhost uxdb-python-UX-UXSQL]$

    如果没有配置uxdbhome路径，会有上图ux-config文件路径提示。

    指定ux_config路径，重新安装一次(必须事先安装uxdb，否则无此文件)。

    python setup.py build_ext --ux-config
/home/uxdb/uxdbinstall/dbsql/bin/ux_config install

  4. 测试 启动python，引入pycouxdb库，没有报错即可正常使用。

    [uxdb@localhost uxdb-python-UX-UXSQL]$python
Python 2.7.5 (default,Nov 14 2023,16:14:06)
[GCC4.8.520150623(Red Hat4.8.5-44)]on linux2
Type "help","copyright","credits"or "license"for more information.
>>>import pycouxdb

2.2.测试连接

conn = pycouxdb.connect(database=database, user=user, password=password, host=host, port=port)

连接后无异常提示，即连接成功。

3.入门

表 连接参数

参数名说明说明
database数据库
user用户
password密码
host主机ip地址默认localhost
port端口
sslmode是否使用SSL默认为prefer可选参数为disable、allow、prefer、 require、verify-ca、verify-full
connect_timeout连接最长等待时间，单位秒0值或未指定均为无限等待，最小值为2

下面代码按序执行。

import pycouxdb    // 1. 引入pycouxdb库
conn = pycouxdb.connect(database="uxdb", user="uxdb", password=password, host="127.0.0.1", port="52025") // 2. 连接uxdb
cursor = conn.cursor() // 3. 获取游标
cursor.execute(sql) // 4. 使用sql语句
cursor.fetchall() // 5. 获取结果
cursor.close() // 6. 关闭游标
conn.close() // 7. 关闭连接

4.其他指令

cursor.commit()    // 提交
cursor.rollback()  // 回滚
cursor.fetchone()  // 获取首个结果
cursor.fetchall()  // 获取全部结果

5.常见问题

  1. error: command 'gcc' failed with exit status 1
    需要安装python依赖库。 
    pip install python-devel
  2. libuxsql.so.5: cannot open shared object file: No such file or directory
    需要将libuxsql.so文件放在系统依赖库目录下，或将uxdb的依赖库所在目录加入到LD_LIBRARY_PATH变量中。

6.接口介绍

6.1.模块级接口

6.1.1.connect

  • 功能

    建立数据库连接（支持 DSN 串/关键字参数、连接工厂、游标工厂、async 异步连接）

  • 函数

    connect(dsn, connection_factory, cursor_factory, kwargs)

  • 参数

    表 connect 参数说明

    名称描述
    dsn（输入）DSN 连接串（可选），如 "host=... port=... dbname=... user=... password=..."。
    connection_factory（输入）连接工厂类（可选）。
    cursor_factory（输入）游标工厂类（可选）。
    kwargs（输入）其他关键字参数（可选），如 host、port、dbname、user、password、sslmode。

  • 返回值

    返回 connection 连接对象。

6.1.2.Binary

  • 功能

    构造二进制值对象（bytea）

  • 函数

    Binary(buffer)

  • 参数

    表 Binary 参数说明

    名称描述
    buffer（输入）要包装的字节数据（bytes/bytearray）。

  • 返回值

    返回 Binary 二进制值对象。

6.1.3.Date

  • 功能

    构造日期对象

  • 函数

    Date(year, month, day)

  • 参数

    表 Date 参数说明

    名称描述
    year（输入）年。
    month（输入）月。
    day（输入）日。

  • 返回值

    返回 date 日期对象。

6.1.4.Time

  • 功能

    构造时间对象

  • 函数

    Time(hour, minute, second)

  • 参数

    表 Time 参数说明

    名称描述
    hour（输入）时。
    minute（输入）分。
    second（输入）秒。

  • 返回值

    返回 time 时间对象。

6.1.5.Timestamp

  • 功能

    构造时间戳对象

  • 函数

    Timestamp(year, month, day, hour, minute, second)

  • 参数

    表 Timestamp 参数说明

    名称描述
    year（输入）年。
    month（输入）月。
    day（输入）日。
    hour（输入）时。
    minute（输入）分。
    second（输入）秒。

  • 返回值

    返回 datetime 时间戳对象。

6.1.6.DateFromTicks

  • 功能

    由 Unix 时间戳构造日期

  • 函数

    DateFromTicks(ticks)

  • 参数

    表 DateFromTicks 参数说明

    名称描述
    ticks（输入）Unix 时间戳。

  • 返回值

    返回 date 日期对象。

6.1.7.TimeFromTicks

  • 功能

    由 Unix 时间戳构造时间

  • 函数

    TimeFromTicks(ticks)

  • 参数

    表 TimeFromTicks 参数说明

    名称描述
    ticks（输入）Unix 时间戳。

  • 返回值

    返回 time 时间对象。

6.1.8.TimestampFromTicks

  • 功能

    由 Unix 时间戳构造时间戳

  • 函数

    TimestampFromTicks(ticks)

  • 参数

    表 TimestampFromTicks 参数说明

    名称描述
    ticks（输入）Unix 时间戳。

  • 返回值

    返回 datetime 时间戳对象。

6.1.9.STRING / BINARY / NUMBER / DATETIME / ROWID

  • 功能

    DB-API 2.0 类型对象常量

  • 参数：无。

  • 返回值

    该组为 DB-API 2.0 类型对象常量，用于标识列值类型。

6.1.10.apilevel / threadsafety / paramstyle

  • 功能

    DB-API 2.0 元信息（apilevel=2.0, threadsafety=2, paramstyle=pyformat）

  • 参数：无。

  • 返回值

    该组为 DB-API 2.0 元信息：apilevel 为 "2.0"，threadsafety 为 2，paramstyle 为 "pyformat"。

6.1.11.version / libuxsql_version

  • 功能

    驱动版本与底层 uxsql 客户端库版本

  • 参数：无。

  • 返回值

    该组为版本字符串，分别表示驱动版本与底层 uxsql 客户端库版本。

6.1.12.extensions / extras / pool / sql / tz

  • 功能

    子模块入口

  • 参数：无。

  • 返回值

    该组为子模块入口，分别对应类型适配、扩展工具、连接池、SQL 组合与时区模块。

6.1.13.psycopg2（官方模块名）

  • 功能

    官方 psycopg2 的导入名；本驱动改名 pycouxdb，不提供 psycopg2 名称兼容

  • 注意

    不支持

  • 参数：无。

  • 返回值

    官方 psycopg2 的导入名，本驱动不支持该名称。

6.2.异常接口

6.2.1.Warning

  • 功能

    DB-API 警告基类

  • 参数：无。

  • 返回值

    DB-API 2.0 警告异常类。

6.2.2.Error

  • 功能

    DB-API 异常基类

  • 参数：无。

  • 返回值

    所有异常的基类。

6.2.3.InterfaceError

  • 功能

    接口错误

  • 参数：无。

  • 返回值

    接口错误异常类。

6.2.4.DatabaseError

  • 功能

    数据库错误基类

  • 参数：无。

  • 返回值

    数据库错误异常基类。

6.2.5.DataError

  • 功能

    数据错误

  • 参数：无。

  • 返回值

    数据处理错误异常类。

6.2.6.OperationalError

  • 功能

    操作错误

  • 参数：无。

  • 返回值

    数据库操作错误异常类（如连接断开）。

6.2.7.IntegrityError

  • 功能

    完整性约束错误

  • 参数：无。

  • 返回值

    完整性约束错误异常类。

6.2.8.InternalError

  • 功能

    内部错误

  • 参数：无。

  • 返回值

    数据库内部错误异常类。

6.2.9.ProgrammingError

  • 功能

    编程错误

  • 参数：无。

  • 返回值

    编程错误异常类（如 SQL 语法错误）。

6.2.10.NotSupportedError

  • 功能

    不支持特性错误

  • 参数：无。

  • 返回值

    不支持的操作异常类。

6.2.11.QueryCanceledError

  • 功能

    查询被取消异常（扩展）

  • 参数：无。

  • 返回值

    查询被取消异常类。

6.2.12.TransactionRollbackError

  • 功能

    事务回滚异常（扩展）

  • 参数：无。

  • 返回值

    事务回滚异常类。

6.2.13.errors.lookup

  • 功能

    按 SQLSTATE 查找对应的异常类

  • 函数

    errors.lookup(sqlstate)

  • 参数

    表 lookup 参数说明

    名称描述
    sqlstate（输入）SQLSTATE 错误码字符串。

  • 返回值

    返回对应的异常类。

6.3.connection 方法

6.3.1.cursor

  • 功能

    创建游标

  • 函数

    connection.cursor(name, cursor_factory, withhold, scrollable)

  • 参数

    表 cursor 参数说明

    名称描述
    name（输入）服务器端游标名（可选）。
    cursor_factory（输入）游标工厂类（可选）。
    withhold（输入）是否 WITH HOLD（可选）。
    scrollable（输入）是否可滚动（可选）。

  • 返回值

    返回 cursor 游标对象。

6.3.2.close

  • 功能

    关闭连接

  • 函数

    connection.close()

  • 参数：无。

  • 返回值

    无返回值，关闭连接。

6.3.3.commit

  • 功能

    提交事务

  • 函数

    connection.commit()

  • 参数：无。

  • 返回值

    无返回值，提交当前事务。

6.3.4.rollback

  • 功能

    回滚事务

  • 函数

    connection.rollback()

  • 参数：无。

  • 返回值

    无返回值，回滚当前事务。

6.3.5.xid

  • 功能

    构造两阶段事务 ID

  • 函数

    connection.xid(format_id, gtrid, bqual)

  • 参数

    表 xid 参数说明

    名称描述
    format_id（输入）分布式事务格式 ID。
    gtrid（输入）全局事务 ID。
    bqual（输入）分支限定符。

  • 返回值

    返回 Xid 事务标识对象。

6.3.6.tpc_begin

  • 功能

    开始两阶段事务

  • 函数

    connection.tpc_begin(xid)

  • 参数

    表 tpc_begin 参数说明

    名称描述
    xid（输入）Xid 事务标识对象（可选，缺省使用当前事务的 XID）。

  • 返回值

    无返回值。

6.3.7.tpc_prepare

  • 功能

    准备两阶段事务

  • 函数

    connection.tpc_prepare(xid)

  • 参数

    表 tpc_prepare 参数说明

    名称描述
    xid（输入）Xid 事务标识对象（可选，缺省使用当前事务的 XID）。

  • 返回值

    无返回值，准备两阶段提交。

6.3.8.tpc_commit

  • 功能

    提交两阶段事务

  • 函数

    connection.tpc_commit(xid)

  • 参数

    表 tpc_commit 参数说明

    名称描述
    xid（输入）Xid 事务标识对象（可选）。

  • 返回值

    无返回值。

6.3.9.tpc_rollback

  • 功能

    回滚两阶段事务

  • 函数

    connection.tpc_rollback(xid)

  • 参数

    表 tpc_rollback 参数说明

    名称描述
    xid（输入）Xid 事务标识对象（可选）。

  • 返回值

    无返回值。

6.3.10.tpc_recover

  • 功能

    恢复待处理的两阶段事务

  • 函数

    connection.tpc_recover()

  • 参数：无。

  • 返回值

    返回待恢复事务的 Xid 列表。

6.3.11.set_session

  • 功能

    设置会话参数（isolation_level/readonly/deferrable/autocommit）

  • 函数

    connection.set_session(kwargs)

  • 参数

    表 set_session 参数说明

    名称描述
    kwargs（输入）会话参数，如 isolation_level、readonly、deferrable、autocommit。

  • 返回值

    无返回值。

6.3.12.set_isolation_level

  • 功能

    设置事务隔离级别

  • 函数

    connection.set_isolation_level(level)

  • 参数

    表 set_isolation_level 参数说明

    名称描述
    level（输入）事务隔离级别。

  • 返回值

    无返回值。

6.3.13.set_client_encoding

  • 功能

    设置客户端编码

  • 函数

    connection.set_client_encoding(encoding)

  • 参数

    表 set_client_encoding 参数说明

    名称描述
    encoding（输入）客户端编码名，如 UTF8。

  • 返回值

    无返回值。

6.3.14.get_transaction_status

  • 功能

    获取事务状态

  • 函数

    connection.get_transaction_status()

  • 参数：无。

  • 返回值

    返回事务状态（int）。

6.3.15.get_parameter_status

  • 功能

    获取服务器参数状态

  • 函数

    connection.get_parameter_status(parameter)

  • 参数

    表 get_parameter_status 参数说明

    名称描述
    parameter（输入）服务器参数名，如 server_version。

  • 返回值

    返回参数值字符串。

6.3.16.get_dsn_parameters

  • 功能

    获取连接参数（返回 ConnectionInfo）

  • 函数

    connection.get_dsn_parameters()

  • 参数：无。

  • 返回值

    返回 ConnectionInfo 连接信息对象。

6.3.17.get_backend_pid

  • 功能

    获取后端进程 PID

  • 函数

    connection.get_backend_pid()

  • 参数：无。

  • 返回值

    返回后端进程 PID（int）。

6.3.18.lobject

  • 功能

    创建大对象

  • 函数

    connection.lobject(oid, mode, new_oid, new_file, lobject_factory)

  • 参数

    表 lobject 参数说明

    名称描述
    oid（输入）大对象 OID（可选，0 表示新建）。
    mode（输入）访问模式（可选）。
    new_oid（输入）新建时指定的 OID（可选）。
    new_file（输入）从文件导入内容（可选）。
    lobject_factory（输入）大对象工厂类（可选）。

  • 返回值

    返回 lobject 大对象。

6.3.19.reset

  • 功能

    重置连接

  • 函数

    connection.reset()

  • 参数：无。

  • 返回值

    无返回值，重置连接。

6.3.20.poll

  • 功能

    轮询异步操作状态

  • 函数

    connection.poll(async_status)

  • 参数

    表 poll 参数说明

    名称描述
    async_status（输入）异步操作状态（可选）。

  • 返回值

    返回轮询状态常量：POLL_OK（操作完成）、POLL_READ / POLL_WRITE（需等待可读/可写）、POLL_ERROR（发生错误）。

6.3.21.fileno

  • 功能

    获取连接 socket 文件描述符

  • 函数

    connection.fileno()

  • 参数：无。

  • 返回值

    返回连接底层 socket 文件描述符。

6.3.22.isexecuting

  • 功能

    判断是否有命令正在执行

  • 函数

    connection.isexecuting()

  • 参数：无。

  • 返回值

    当前正在执行命令返回 True，否则返回 False。

6.3.23.cancel

  • 功能

    取消当前执行的命令

  • 函数

    connection.cancel()

  • 参数：无。

  • 返回值

    无返回值，取消当前正在执行的命令。

6.3.24.get_native_connection

  • 功能

    获取底层原生连接指针

  • 函数

    connection.get_native_connection()

  • 参数：无。

  • 返回值

    返回底层 uxsql 连接对象。

6.3.25.enter

  • 功能

    上下文管理器入口

  • 函数

    connection.__enter__()

  • 参数：无。

  • 返回值

    返回连接对象自身（上下文管理器入口）。

6.3.26.exit

  • 功能

    上下文管理器出口

  • 函数

    connection.__exit__(exc_type, exc_val, exc_tb)

  • 参数

    表 exit 参数说明

    名称描述
    exc_type（输入）异常类型。
    exc_val（输入）异常值。
    exc_tb（输入）回溯对象。

  • 返回值

    无返回值。

6.4.connection 属性

6.4.1.autocommit

  • 功能

    自动提交模式开关

  • 参数：无。

  • 返回值

    该属性为 bool 类型，表示是否自动提交。

6.4.2.isolation_level

  • 功能

    事务隔离级别

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示当前事务隔离级别。

6.4.3.readonly

  • 功能

    只读事务状态

  • 参数：无。

  • 返回值

    该属性为 bool 类型，表示是否只读。

6.4.4.deferrable

  • 功能

    可延迟约束状态

  • 参数：无。

  • 返回值

    该属性为 bool 类型，表示事务是否可延迟。

6.4.5.info

  • 功能

    连接信息（ConnectionInfo 对象）

  • 参数：无。

  • 返回值

    该属性为 ConnectionInfo 对象，提供连接与诊断信息。

6.4.6.closed

  • 功能

    连接是否已关闭

  • 参数：无。

  • 返回值

    该属性为 int 类型（0/1/2），表示连接关闭状态。

6.4.7.encoding

  • 功能

    客户端编码

  • 参数：无。

  • 返回值

    该属性为 str 类型，表示客户端编码。

6.4.8.notices

  • 功能

    服务器 NOTICE 消息列表

  • 参数：无。

  • 返回值

    该属性为 list 类型，元素为服务器返回的 NOTICE 消息字符串。

6.4.9.notifies

  • 功能

    异步通知列表

  • 参数：无。

  • 返回值

    该属性为 list 类型，元素为 Notify 通知对象（含 pid、channel、payload 属性）。

6.4.10.dsn

  • 功能

    连接字符串

  • 参数：无。

  • 返回值

    该属性为 str 类型，表示连接的 DSN 串。

6.4.11.async

  • 功能

    是否异步连接

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示异步连接状态。

6.4.12.async_

  • 功能

    async 的别名

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示异步连接状态（兼容名）。

6.4.13.status

  • 功能

    连接/事务状态

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示连接/事务状态常量（STATUS_READY、STATUS_BEGIN、STATUS_IN_TRANSACTION、STATUS_PREPARED 等）。

6.4.14.cursor_factory

  • 功能

    默认游标工厂

  • 参数：无。

  • 返回值

    该属性表示默认游标工厂类。

6.4.15.string_types

  • 功能

    文本类型转换器集合

  • 参数：无。

  • 返回值

    该属性为字符串类型（str 等）元组，用于标识文本类型。

6.4.16.binary_types

  • 功能

    二进制类型转换器集合

  • 参数：无。

  • 返回值

    该属性为二进制类型（bytes/bytearray 等）元组，用于标识二进制类型。

6.4.17.protocol_version

  • 功能

    协议版本

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示协议版本。

6.4.18.server_version

  • 功能

    服务器版本

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示服务器版本号。

6.4.19.uxconn_ptr

  • 功能

    底层连接指针（原生属性）

  • 参数：无。

  • 返回值

    该属性表示底层 uxsql 连接指针。

6.5.cursor 方法

6.5.1.close

  • 功能

    关闭游标

  • 函数

    cursor.close()

  • 参数：无。

  • 返回值

    无返回值，关闭游标。

6.5.2.execute

  • 功能

    执行 SQL（带参数）

  • 函数

    cursor.execute(query, vars)

  • 参数

    表 execute 参数说明

    名称描述
    query（输入）要执行的 SQL 语句。
    vars（输入）参数序列或字典（可选）。

  • 返回值

    无返回值，执行查询。

6.5.3.executemany

  • 功能

    批量执行同一 SQL

  • 函数

    cursor.executemany(query, vars_list)

  • 参数

    表 executemany 参数说明

    名称描述
    query（输入）SQL 语句。
    vars_list（输入）参数序列的列表。

  • 返回值

    无返回值，批量执行。

6.5.4.fetchone

  • 功能

    取下一行

  • 函数

    cursor.fetchone()

  • 参数：无。

  • 返回值

    返回下一行元组，无更多行返回 None。

6.5.5.fetchmany

  • 功能

    取多行

  • 函数

    cursor.fetchmany(size)

  • 参数

    表 fetchmany 参数说明

    名称描述
    size（输入）要获取的行数（可选，默认 arraysize）。

  • 返回值

    返回行列表。

6.5.6.fetchall

  • 功能

    取全部行

  • 函数

    cursor.fetchall()

  • 参数：无。

  • 返回值

    返回所有剩余行列表。

6.5.7.callproc

  • 功能

    调用存储过程

  • 函数

    cursor.callproc(procname, parameters)

  • 参数

    表 callproc 参数说明

    名称描述
    procname（输入）存储过程/函数名。
    parameters（输入）参数序列（可选）。

  • 返回值

    返回输入参数序列（可能被修改）。

6.5.8.nextset

  • 功能

    推进到下一结果集

  • 函数

    cursor.nextset()

  • 参数：无。

  • 返回值

    推进到下一结果集，有则返回 True，否则返回 None。

6.5.9.setinputsizes

  • 功能

    声明输入参数类型

  • 函数

    cursor.setinputsizes(sizes)

  • 参数

    表 setinputsizes 参数说明

    名称描述
    sizes（输入）类型或长度序列。

  • 返回值

    无返回值。

6.5.10.setoutputsize

  • 功能

    声明输出列大小

  • 函数

    cursor.setoutputsize(size, column)

  • 参数

    表 setoutputsize 参数说明

    名称描述
    size（输入）输出大小。
    column（输入）列索引（可选）。

  • 返回值

    无返回值。

6.5.11.scroll

  • 功能

    滚动游标位置

  • 函数

    cursor.scroll(value, mode)

  • 参数

    表 scroll 参数说明

    名称描述
    value（输入）移动的行数。
    mode（输入）模式（可选）：relative 或 absolute。

  • 返回值

    无返回值。

6.5.12.cast

  • 功能

    将值转换为指定 SQL 类型

  • 函数

    cursor.cast(oid, s)

  • 参数

    表 cast 参数说明

    名称描述
    oid（输入）目标类型 OID。
    s（输入）要转换的字符串。

  • 返回值

    返回转换为目标类型的 Python 对象。

6.5.13.mogrify

  • 功能

    返回 SQL 语句绑定参数后的文本（不执行）

  • 函数

    cursor.mogrify(query, vars)

  • 参数

    表 mogrify 参数说明

    名称描述
    query（输入）SQL 语句。
    vars（输入）参数（可选）。

  • 返回值

    返回替换参数后的 SQL 字符串。

6.5.14.copy_from

  • 功能

    从文件 COPY 导入表

  • 函数

    cursor.copy_from(file, table, sep, null, size, columns)

  • 参数

    表 copy_from 参数说明

    名称描述
    file（输入）文件对象。
    table（输入）目标表名。
    sep（输入）分隔符（可选）。
    null（输入）NULL 表示（可选）。
    size（输入）缓冲大小（可选）。
    columns（输入）列名序列（可选）。

  • 返回值

    无返回值。

6.5.15.copy_to

  • 功能

    COPY 导出表到文件

  • 函数

    cursor.copy_to(file, table, sep, null, columns)

  • 参数

    表 copy_to 参数说明

    名称描述
    file（输入）文件对象。
    table（输入）表名。
    sep（输入）分隔符（可选）。
    null（输入）NULL 表示（可选）。
    columns（输入）列名序列（可选）。

  • 返回值

    无返回值。

6.5.16.copy_expert

  • 功能

    执行自定义 COPY 命令

  • 函数

    cursor.copy_expert(sql, file, size)

  • 参数

    表 copy_expert 参数说明

    名称描述
    sql（输入）COPY 语句。
    file（输入）文件对象。
    size（输入）缓冲大小（可选）。

  • 返回值

    无返回值。

6.5.17.enter

  • 功能

    上下文管理器入口

  • 函数

    cursor.__enter__()

  • 参数：无。

  • 返回值

    返回游标自身。

6.5.18.exit

  • 功能

    上下文管理器出口

  • 函数

    cursor.__exit__(exc_type, exc_val, exc_tb)

  • 参数

    表 exit 参数说明

    名称描述
    exc_type（输入）异常类型。
    exc_val（输入）异常值。
    exc_tb（输入）回溯对象。

  • 返回值

    无返回值。

6.6.cursor 属性

6.6.1.rowcount

  • 功能

    上次命令读取/影响的行数

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示最近一次操作影响的行数。

6.6.2.arraysize

  • 功能

    fetchmany 默认取行数

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示 fetchmany 默认获取的行数。

6.6.3.itersize

  • 功能

    迭代每次网络往返取行数

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示服务器端游标每次获取的行数。

6.6.4.description

  • 功能

    结果列描述（DB-API 2.0）

  • 参数：无。

  • 返回值

    该属性为列描述元组列表，每个元素为 (name, type_code, display_size, internal_size, precision, scale, null_ok)。

6.6.5.lastrowid

  • 功能

    最后插入行的 OID

  • 参数：无。

  • 返回值

    该属性为最后插入行的 OID 或 None。

6.6.6.rownumber

  • 功能

    当前行位置

  • 参数：无。

  • 返回值

    该属性为 int 类型，表示当前结果集的行号。

6.6.7.connection

  • 功能

    所属连接

  • 参数：无。

  • 返回值

    该属性为关联的 connection 对象。

6.6.8.name

  • 功能

    服务器端游标名

  • 参数：无。

  • 返回值

    该属性为 str 类型，表示游标名。

6.6.9.statusmessage

  • 功能

    上次命令的返回消息

  • 参数：无。

  • 返回值

    该属性为 str 类型，表示最近一次命令的状态消息。

6.6.10.query

  • 功能

    上次执行的 SQL 文本

  • 参数：无。

  • 返回值

    该属性为 str 类型，表示最近执行的查询语句。

6.6.11.row_factory

  • 功能

    行工厂

  • 参数：无。

  • 返回值

    该属性为行工厂类，用于构造结果行。

6.6.12.tzinfo_factory

  • 功能

    时区工厂

  • 参数：无。

  • 返回值

    该属性为时区工厂类，用于构造 tzinfo 对象。

6.6.13.typecaster

  • 功能

    类型转换器

  • 参数：无。

  • 返回值

    该属性为类型转换器对象。

6.6.14.string_types

  • 功能

    文本类型转换器集合

  • 参数：无。

  • 返回值

    该属性为字符串类型（str 等）元组，用于标识文本类型。

6.6.15.binary_types

  • 功能

    二进制类型转换器集合

  • 参数：无。

  • 返回值

    该属性为二进制类型（bytes/bytearray 等）元组，用于标识二进制类型。

6.6.16.closed

  • 功能

    游标是否已关闭

  • 参数：无。

  • 返回值

    该属性为 bool 类型，表示游标是否已关闭。

6.7.大对象 lobject 接口

6.7.1.read

  • 功能

    读取大对象数据

  • 函数

    lobject.read(size)

  • 参数

    表 read 参数说明

    名称描述
    size（输入）要读取的字节数（可选，-1 表示全部）。

  • 返回值

    返回读取的字节数据。

6.7.2.write

  • 功能

    写入大对象数据

  • 函数

    lobject.write(s)

  • 参数

    表 write 参数说明

    名称描述
    s（输入）要写入的字节数据。

  • 返回值

    返回写入的字节数。

6.7.3.seek

  • 功能

    定位读写偏移

  • 函数

    lobject.seek(offset, whence)

  • 参数

    表 seek 参数说明

    名称描述
    offset（输入）偏移量。
    whence（输入）基准位置（可选，0/1/2）。

  • 返回值

    返回新的偏移位置。

6.7.4.tell

  • 功能

    获取当前偏移

  • 函数

    lobject.tell()

  • 参数：无。

  • 返回值

    返回当前偏移位置。

6.7.5.close

  • 功能

    关闭大对象

  • 函数

    lobject.close()

  • 参数：无。

  • 返回值

    无返回值，关闭大对象。

  • 功能

    删除大对象

  • 函数

    lobject.unlink()

  • 参数：无。

  • 返回值

    无返回值，删除大对象。

6.7.7.export

  • 功能

    导出大对象到文件

  • 函数

    lobject.export(filename)

  • 参数

    表 export 参数说明

    名称描述
    filename（输入）导出文件路径。

  • 返回值

    无返回值。

6.7.8.truncate

  • 功能

    截断大对象

  • 函数

    lobject.truncate(len)

  • 参数

    表 truncate 参数说明

    名称描述
    len（输入）截断后的字节数（可选，默认 0）。

  • 返回值

    无返回值。

6.7.9.oid / mode / closed

  • 功能

    大对象属性（OID/打开模式/是否关闭）

  • 参数：无。

  • 返回值

    该组属性分别表示大对象 OID、访问模式与是否关闭。

6.8.类型适配接口（extensions）

6.8.1.adapt

  • 功能

    PEP-246 适配对象

  • 函数

    extensions.adapt(obj, protocol)

  • 参数

    表 adapt 参数说明

    名称描述
    obj（输入）要适配的对象。
    protocol（输入）适配协议（可选）。

  • 返回值

    返回适配后的对象。

6.8.2.register_adapter

  • 功能

    注册类型适配器

  • 函数

    extensions.register_adapter(cls, adapter)

  • 参数

    表 register_adapter 参数说明

    名称描述
    cls（输入）源类型。
    adapter（输入）适配器。

  • 返回值

    无返回值。

6.8.3.register_type

  • 功能

    注册类型转换器

  • 函数

    extensions.register_type(cls, conn_or_curs)

  • 参数

    表 register_type 参数说明

    名称描述
    cls（输入）类型对象。
    conn_or_curs（输入）连接或游标（可选）。

  • 返回值

    无返回值。

6.8.4.new_type

  • 功能

    创建类型转换器

  • 函数

    extensions.new_type(oids, name, adapter)

  • 参数

    表 new_type 参数说明

    名称描述
    oids（输入）OID 元组。
    name（输入）类型名。
    adapter（输入）转换函数。

  • 返回值

    返回新的类型对象。

6.8.5.new_array_type

  • 功能

    创建数组类型转换器

  • 函数

    extensions.new_array_type(oids, name, base_type)

  • 参数

    表 new_array_type 参数说明

    名称描述
    oids（输入）数组 OID 元组。
    name（输入）类型名。
    base_type（输入）元素类型对象。

  • 返回值

    返回新的数组类型对象。

6.8.6.make_dsn

  • 功能

    将关键字参数转换为连接串

  • 函数

    extensions.make_dsn(kwargs)

  • 参数

    表 make_dsn 参数说明

    名称描述
    kwargs（输入）连接参数，如 host、port、dbname、user、password。

  • 返回值

    返回构造的 DSN 字符串。

6.8.7.parse_dsn

  • 功能

    解析连接串

  • 函数

    extensions.parse_dsn(dsn)

  • 参数

    表 parse_dsn 参数说明

    名称描述
    dsn（输入）DSN 字符串。

  • 返回值

    返回解析后的参数字典。

6.8.8.quote_ident

  • 功能

    引用 SQL 标识符

  • 函数

    extensions.quote_ident(str, scope)

  • 参数

    表 quote_ident 参数说明

    名称描述
    str（输入）要转义的标识符。
    scope（输入）作用域（可选）。

  • 返回值

    返回转义并加引号的标识符。

6.8.9.encrypt_password

  • 功能

    加密密码

  • 函数

    extensions.encrypt_password(password, user, scope, algorithm)

  • 参数

    表 encrypt_password 参数说明

    名称描述
    password（输入）明文密码。
    user（输入）用户名。
    scope（输入）作用域（可选）。
    algorithm（输入）加密算法（可选），如 md5、scram-sha-256。

  • 返回值

    返回加密后的密码字符串。

6.8.10.set_wait_callback

  • 功能

    设置异步等待回调

  • 函数

    extensions.set_wait_callback(callback)

  • 参数

    表 set_wait_callback 参数说明

    名称描述
    callback（输入）回调函数。

  • 返回值

    返回之前的回调函数。

6.8.11.get_wait_callback

  • 功能

    获取异步等待回调

  • 函数

    extensions.get_wait_callback()

  • 参数：无。

  • 返回值

    返回当前等待回调函数。

6.8.12.libuxsql_version

  • 功能

    获取底层客户端库版本

  • 函数

    extensions.libuxsql_version()

  • 参数：无。

  • 返回值

    返回底层 uxsql 库版本（int）。

6.8.13.ISQLQuote

  • 功能

    SQL 适配器协议基类

  • 参数

    表 ISQLQuote 参数说明

    名称描述
    sql（输入）要引用的 SQL 片段。

  • 返回值

    返回 SQL 引用片段。

6.8.14.SQL_IN

  • 功能

    序列适配器（生成 tuple IN 列表）

  • 参数：无。

  • 返回值

    该常量为 IN 子句适配器对象。

6.8.15.NoneAdapter

  • 功能

    None→NULL 适配器

  • 参数：无。

  • 返回值

    该常量为 None 适配器对象。

6.8.16.AsIs

  • 功能

    原样输出 SQL 值包装器

  • 参数

    表 AsIs 参数说明

    名称描述
    obj（输入）要原样引用的对象。

  • 返回值

    返回 AsIs 对象。

6.8.17.Binary

  • 功能

    二进制值适配器

  • 参数

    表 Binary 参数说明

    名称描述
    buffer（输入）字节数据。

  • 返回值

    返回 Binary 对象。

6.8.18.Boolean

  • 功能

    布尔值适配器

  • 参数

    表 Boolean 参数说明

    名称描述
    value（输入）布尔值。

  • 返回值

    返回 Boolean 对象。

6.8.19.Float

  • 功能

    浮点值适配器

  • 参数

    表 Float 参数说明

    名称描述
    value（输入）浮点值。

  • 返回值

    返回 Float 对象。

6.8.20.Int

  • 功能

    整数值适配器

  • 参数

    表 Int 参数说明

    名称描述
    value（输入）整数值。

  • 返回值

    返回 Int 对象。

6.8.21.QuotedString

  • 功能

    引用字符串适配器

  • 参数

    表 QuotedString 参数说明

    名称描述
    value（输入）字符串值。

  • 返回值

    返回 QuotedString 对象。

6.8.22.DateFromPy / TimeFromPy / TimestampFromPy / IntervalFromPy

  • 功能

    Python 日期/时间对象适配器

  • 参数

    表 DateFromPy / TimeFromPy / TimestampFromPy / IntervalFromPy 参数说明

    名称描述
    obj（输入）Python 日期/时间对象。

  • 返回值

    返回对应的 SQL 表示对象。

6.8.23.connection / cursor / lobject

  • 功能

    连接/游标/大对象基类（供子类化）

  • 参数：无。

  • 返回值

    该组为子模块入口类型（connection、cursor、lobject）。

6.8.24.string_types / binary_types

  • 功能

    类型转换器集合

  • 参数：无。

  • 返回值

    该组为字符串/二进制类型元组。

6.8.25.encodings

  • 功能

    字符编码映射表

  • 参数：无。

  • 返回值

    该属性为编码映射字典。

6.8.26.adapters

  • 功能

    适配器注册表

  • 参数：无。

  • 返回值

    该属性为已注册的适配器字典。

6.8.27.JSON / JSONARRAY / JSONB / JSONBARRAY

  • 功能

    默认 JSON/JSONB 类型转换器

  • 参数：无。

  • 返回值

    该组为 JSON/JSONB 默认类型转换器对象。

6.9.扩展工具接口（extras）

6.9.1.DictConnection

  • 功能

    字典行连接工厂

  • 参数：无。

  • 返回值

    该类型为字典游标连接类。

6.9.2.DictCursor

  • 功能

    字典行游标

  • 参数：无。

  • 返回值

    该类型为字典游标类，结果行以字典返回。

6.9.3.DictRow

  • 功能

    字典行对象

  • 参数：无。

  • 返回值

    该类型为字典行类。

6.9.4.RealDictConnection

  • 功能

    OrderedDict 行连接工厂

  • 参数：无。

  • 返回值

    该类型为 RealDict 游标连接类。

6.9.5.RealDictCursor

  • 功能

    OrderedDict 行游标

  • 参数：无。

  • 返回值

    该类型为 RealDict 游标类，结果行以真实字典返回。

6.9.6.RealDictRow

  • 功能

    OrderedDict 行对象

  • 参数：无。

  • 返回值

    该类型为 RealDict 行类。

6.9.7.NamedTupleConnection

  • 功能

    namedtuple 行连接工厂

  • 参数：无。

  • 返回值

    该类型为命名元组游标连接类。

6.9.8.NamedTupleCursor

  • 功能

    namedtuple 行游标

  • 参数：无。

  • 返回值

    该类型为命名元组游标类，结果行以命名元组返回。

6.9.9.LoggingConnection

  • 功能

    SQL 日志连接

  • 参数：无。

  • 返回值

    该类型为带 SQL 日志的连接类。

6.9.10.LoggingCursor

  • 功能

    SQL 日志游标

  • 参数：无。

  • 返回值

    该类型为带 SQL 日志的游标类。

6.9.11.MinTimeLoggingConnection

  • 功能

    慢查询日志连接（按耗时过滤）

  • 参数：无。

  • 返回值

    该类型为记录慢查询日志的连接类。

6.9.12.MinTimeLoggingCursor

  • 功能

    慢查询日志游标

  • 参数：无。

  • 返回值

    该类型为记录慢查询日志的游标类。

6.9.13.LogicalReplicationConnection

  • 功能

    逻辑复制连接工厂

  • 参数：无。

  • 返回值

    该类型为逻辑复制连接类。

6.9.14.PhysicalReplicationConnection

  • 功能

    物理复制连接工厂

  • 参数：无。

  • 返回值

    该类型为物理复制连接类。

6.9.15.ReplicationCursor

  • 功能

    复制游标（create/drop_replication_slot、start_replication 等）

  • 参数：无。

  • 返回值

    该类型为复制游标类。

6.9.16.StopReplication

  • 功能

    停止复制异常

  • 参数：无。

  • 返回值

    该类型为停止复制异常类。

6.9.17.UUID_adapter

  • 功能

    UUID 类型适配器

  • 参数：无。

  • 返回值

    该常量为 UUID 适配器对象。

6.9.18.register_uuid

  • 功能

    注册 UUID 类型转换与适配

  • 函数

    extras.register_uuid(conn_or_curs)

  • 参数

    表 register_uuid 参数说明

    名称描述
    conn_or_curs（输入）连接或游标（可选）。

  • 返回值

    无返回值，注册 UUID 类型适配。

6.9.19.Inet

  • 功能

    inet/cidr 值对象

  • 参数：无。

  • 返回值

    该常量为 Inet 类型对象。

6.9.20.register_inet

  • 功能

    注册 inet 类型转换与适配

  • 函数

    extras.register_inet(conn_or_curs)

  • 参数

    表 register_inet 参数说明

    名称描述
    conn_or_curs（输入）连接或游标（可选）。

  • 返回值

    无返回值，注册 Inet 类型适配。

6.9.21.HstoreAdapter

  • 功能

    hstore 类型适配器

  • 参数：无。

  • 返回值

    该常量为 hstore 适配器对象。

6.9.22.register_hstore

  • 功能

    注册 hstore 类型转换与适配

  • 函数

    extras.register_hstore(conn_or_curs, globally)

  • 参数

    表 register_hstore 参数说明

    名称描述
    conn_or_curs（输入）连接或游标（可选）。
    globally（输入）是否全局注册（可选）。

  • 返回值

    无返回值，注册 hstore 类型适配。

6.9.23.CompositeCaster

  • 功能

    复合类型转换器

  • 参数：无。

  • 返回值

    该类型为复合类型转换器类。

6.9.24.register_composite

  • 功能

    注册复合类型转换

  • 函数

    extras.register_composite(name, conn_or_curs, globally, factory)

  • 参数

    表 register_composite 参数说明

    名称描述
    name（输入）复合类型名。
    conn_or_curs（输入）连接或游标（可选）。
    globally（输入）是否全局注册（可选）。
    factory（输入）转换工厂（可选）。

  • 返回值

    无返回值，注册复合类型适配。

6.9.25.Json

  • 功能

    JSON 值包装器

  • 参数：无。

  • 返回值

    该常量为 Json 适配器对象。

6.9.26.register_json

  • 功能

    注册 JSON 类型转换

  • 函数

    extras.register_json(conn_or_curs, globally, loads)

  • 参数

    表 register_json 参数说明

    名称描述
    conn_or_curs（输入）连接或游标（可选）。
    globally（输入）是否全局注册（可选）。
    loads（输入）JSON 解析函数（可选）。

  • 返回值

    无返回值，注册 json 类型适配。

6.9.27.register_default_json

  • 功能

    注册默认 JSON 类型转换

  • 函数

    extras.register_default_json(conn_or_curs, globally, loads)

  • 参数

    表 register_default_json 参数说明

    名称描述
    conn_or_curs（输入）连接或游标（可选）。
    globally（输入）是否全局注册（可选）。
    loads（输入）JSON 解析函数（可选）。

  • 返回值

    无返回值，注册默认 json 类型适配。

6.9.28.register_default_jsonb

  • 功能

    注册默认 JSONB 类型转换

  • 函数

    extras.register_default_jsonb(conn_or_curs, globally, loads)

  • 参数

    表 register_default_jsonb 参数说明

    名称描述
    conn_or_curs（输入）连接或游标（可选）。
    globally（输入）是否全局注册（可选）。
    loads（输入）JSON 解析函数（可选）。

  • 返回值

    无返回值，注册默认 jsonb 类型适配。

6.9.29.Range

  • 功能

    range 值对象

  • 参数：无。

  • 返回值

    该常量为 Range 类型对象。

6.9.30.NumericRange / DateRange / DateTimeRange / DateTimeTZRange

  • 功能

    常用 range 子类

  • 参数：无。

  • 返回值

    该组为 range 子类型对象。

6.9.31.register_range

  • 功能

    注册 range 类型转换

  • 函数

    extras.register_range(pgrange, pyrange, conn_or_curs, globally)

  • 参数

    表 register_range 参数说明

    名称描述
    pgrange（输入）PG range 类型名。
    pyrange（输入）Python range 类型。
    conn_or_curs（输入）连接或游标（可选）。
    globally（输入）是否全局注册（可选）。

  • 返回值

    无返回值，注册 range 类型适配。

6.9.32.RangeAdapter

  • 功能

    range 适配器

  • 参数：无。

  • 返回值

    该类型为 Range 适配器类。

6.9.33.RangeCaster

  • 功能

    range 转换器

  • 参数：无。

  • 返回值

    该类型为 Range 转换器类。

6.9.34.execute_batch

  • 功能

    批量执行 SQL（多条语句）

  • 函数

    extras.execute_batch(cur, sql, argslist, page_size)

  • 参数

    表 execute_batch 参数说明

    名称描述
    cur（输入）游标对象。
    sql（输入）SQL 语句。
    argslist（输入）参数列表。
    page_size（输入）每批行数（可选，默认 100）。

  • 返回值

    无返回值，分批执行 SQL。

6.9.35.execute_values

  • 功能

    批量 VALUES 插入（高效导入）

  • 函数

    extras.execute_values(cur, sql, argslist, template, page_size)

  • 参数

    表 execute_values 参数说明

    名称描述
    cur（输入）游标对象。
    sql（输入）SQL 语句（含 %s 占位）。
    argslist（输入）参数列表。
    template（输入）VALUES 模板（可选）。
    page_size（输入）每批行数（可选）。

  • 返回值

    无返回值，批量执行 INSERT/UPDATE。

6.9.36.wait_select

  • 功能

    select 等待回调（协程库支持）

  • 函数

    extras.wait_select(conn)

  • 参数

    表 wait_select 参数说明

    名称描述
    conn（输入）连接对象。

  • 返回值

    无返回值，阻塞等待连接可读写。

6.10.连接池接口（pool）

6.10.1.PoolError

  • 功能

    连接池异常

  • 参数：无。

  • 返回值

    连接池异常类。

6.10.2.AbstractConnectionPool

  • 功能

    连接池基类

  • 参数：无。

  • 返回值

    连接池抽象基类。

6.10.3.SimpleConnectionPool

  • 功能

    简单连接池（非线程安全）

  • 参数

    表 SimpleConnectionPool 参数说明

    名称描述
    minconn（输入）最小连接数。
    maxconn（输入）最大连接数。
    args（输入）连接参数。
    kwargs（输入）连接关键字参数。

  • 返回值

    返回连接池对象。

6.10.4.ThreadedConnectionPool

  • 功能

    线程安全连接池

  • 参数

    表 ThreadedConnectionPool 参数说明

    名称描述
    minconn（输入）最小连接数。
    maxconn（输入）最大连接数。
    args（输入）连接参数。
    kwargs（输入）连接关键字参数。

  • 返回值

    返回线程安全连接池对象。

6.11.SQL 组合接口（sql）

6.11.1.Composable

  • 功能

    可组合 SQL 对象基类

  • 参数：无。

  • 返回值

    SQL 组合对象基类。

6.11.2.Composed

  • 功能

    组合序列对象

  • 参数

    表 Composed 参数说明

    名称描述
    seq（输入）Composable 序列。

  • 返回值

    返回组合后的 Composable 对象。

6.11.3.SQL

  • 功能

    SQL 片段对象

  • 参数

    表 SQL 参数说明

    名称描述
    string（输入）SQL 片段字符串。

  • 返回值

    返回 SQL 组合对象。

6.11.4.Identifier

  • 功能

    标识符对象

  • 参数

    表 Identifier 参数说明

    名称描述
    strings（输入）标识符组成部分。

  • 返回值

    返回标识符组合对象。

6.11.5.Literal

  • 功能

    字面量对象

  • 参数

    表 Literal 参数说明

    名称描述
    obj（输入）要作为字面量的对象。

  • 返回值

    返回字面量组合对象。

6.11.6.Placeholder

  • 功能

    占位符对象

  • 参数

    表 Placeholder 参数说明

    名称描述
    name（输入）占位符名（可选）。

  • 返回值

    返回占位符组合对象。

6.12.时区接口（tz）

6.12.1.FixedOffsetTimezone

  • 功能

    固定偏移时区

  • 参数

    表 FixedOffsetTimezone 参数说明

    名称描述
    offset（输入）固定偏移量（可选）。
    name（输入）时区名（可选）。

  • 返回值

    返回固定偏移时区对象。

6.12.2.LocalTimezone

  • 功能

    本地时区

  • 参数：无。

  • 返回值

    返回本地时区对象。

6.12.3.ZERO

  • 功能

    零偏移常量

  • 参数：无。

  • 返回值

    该常量为零偏移时区对象。

6.13.逻辑复制接口

6.13.1.connection.start_replication

  • 功能

    开始复制（复制连接方法）

  • 函数

    connection.start_replication(slot_name, start_lsn, timeline, options)

  • 参数

    表 start_replication 参数说明

    名称描述
    slot_name（输入）复制槽名。
    start_lsn（输入）起始 LSN（可选）。
    timeline（输入）时间线（可选）。
    options（输入）复制选项（可选）。

  • 返回值

    无返回值，启动逻辑复制。

6.13.2.ReplicationCursor.start_replication_expert

  • 功能

    按自定义命令启动复制

  • 函数

    ReplicationCursor.start_replication_expert(command, decode, status_interval)

  • 参数

    表 start_replication_expert 参数说明

    名称描述
    command（输入）自定义复制命令。
    decode（输入）是否解码（可选）。
    status_interval（输入）状态反馈间隔（可选）。

  • 返回值

    无返回值，按自定义命令启动复制。

6.13.3.ReplicationCursor.consume_stream

  • 功能

    消费复制流

  • 函数

    ReplicationCursor.consume_stream(consume, decode)

  • 参数

    表 consume_stream 参数说明

    名称描述
    consume（输入）消费回调函数。
    decode（输入）是否解码（可选）。

  • 返回值

    无返回值，持续消费复制流。

6.13.4.ReplicationCursor.read_message

  • 功能

    读取复制消息

  • 函数

    ReplicationCursor.read_message()

  • 参数：无。

  • 返回值

    返回下一条复制消息（ReplicationMessage），无消息时阻塞等待。

6.13.5.ReplicationCursor.send_feedback

  • 功能

    发送复制状态反馈

  • 函数

    ReplicationCursor.send_feedback(write_lsn, flush_lsn, apply_lsn, reply, force)

  • 参数

    表 send_feedback 参数说明

    名称描述
    write_lsn（输入）已写入 LSN（可选）。
    flush_lsn（输入）已刷盘 LSN（可选）。
    apply_lsn（输入）已应用 LSN（可选）。
    reply（输入）是否请求回复（可选）。
    force（输入）是否强制发送（可选）。

  • 返回值

    无返回值，发送复制状态反馈。

6.13.6.ReplicationMessage

  • 功能

    复制消息对象（cursor/payload/data_size/data_start/wal_end）

  • 参数：无。

  • 返回值

    该类型为复制消息对象，含 cursor、payload、data_size、data_start、wal_end 属性。

6.14.诊断与连接信息对象

6.14.1.ConnectionInfo.ssl_attribute

  • 功能

    查询 SSL 属性

  • 函数

    ConnectionInfo.ssl_attribute(n)

  • 参数

    表 ssl_attribute 参数说明

    名称描述
    n（输入）SSL 属性索引。

  • 返回值

    返回 SSL 属性值。

6.14.2.ConnectionInfo.parameter_status

  • 功能

    查询参数状态

  • 函数

    ConnectionInfo.parameter_status(name)

  • 参数

    表 parameter_status 参数说明

    名称描述
    name（输入）服务器参数名。

  • 返回值

    返回参数状态值。

6.14.3.ConnectionInfo 属性

  • 功能

    dbname/user/password/host/port/options/dsn_parameters/status/transaction_status/protocol_version/server_version/error_message/socket/backend_pid/used_password/needs_password/ssl_in_use/ssl_attribute_names

  • 参数：无。

  • 返回值

    该组属性包括 dbname、user、password、host、port、options、dsn_parameters、status、transaction_status、protocol_version、server_version、error_message、socket、backend_pid、used_password、needs_password、ssl_in_use、ssl_attribute_names 等连接信息。

6.14.4.Diagnostics 属性

  • 功能

    severity/severity_nonlocalized/sqlstate/message_primary/message_detail/message_hint/statement_position/internal_position/internal_query/context/schema_name/table_name/column_name/datatype_name/constraint_name/source_file/source_line/source_function

  • 参数：无。

  • 返回值

    该组属性包括 severity、severity_nonlocalized、sqlstate、message_primary、message_detail、message_hint、statement_position、internal_position、internal_query、context、schema_name、table_name、column_name、datatype_name、constraint_name、source_file、source_line、source_function 等诊断信息。

6.14.5.Notify 属性

  • 功能

    pid/channel/payload

  • 参数：无。

  • 返回值

    该组属性包括 pid、channel、payload，表示一条 LISTEN/NOTIFY 通知。

6.14.6.Xid

  • 功能

    两阶段事务 ID（format_id/gtrid/bqual/prepared/owner/database + from_string）

  • 参数：无。

  • 返回值

    该类型为两阶段事务 ID 对象，含 format_id、gtrid、bqual、prepared、owner、database 属性及 from_string 方法。

6.14.7.Column 属性

  • 功能

    name/type_code/display_size/internal_size/precision/scale/null_ok

  • 参数：无。

  • 返回值

    该组属性包括 name、type_code、display_size、internal_size、precision、scale、null_ok，表示结果集列描述。

Copyright © 2026 UXSINO版权所有