新增特性

该文档主要描述本驱动基于原驱动基础上新增的特性

自动 savepoint

前提： connect.autocommit=False 关闭自动提交时，该特性才会生效

当不开启自动提交时，用户需显式的调用 connect.commit() 来提交，在提交之前的所有sql都将视为同一个事务，如果执行某个 SQL 报错时，再调用 rollback 时会将所有未提交的操作都回滚掉。

用户可以通过设置 connect.autosavepoint=True (默认为 False) 来启用自动创建 savepoint 功能。当启用该参数后，在未提交前每执行一个 SQL，都会自动创建一个 savepoint（一个事务中仅保留一个savepoint），如果执行 SQL 报错时，驱动会自动回滚当前报错的SQL，而不会回滚所有操作，用户捕获到SQL执行报错后，仍旧可以调用 connect.commit() 来提交报错SQL之前的所有的操作。

以下为四种设置方式任选一种即可：

在字符串中设置 autosavepoint 参数时，'', '0', 'off', 'false', 'n', 'no' 这些值会被视为 False, 其他值均会视为 True

# 第一种：在 URL 形式的DSN中设置参数
conn = psycopg2.connect("postgres://user:password@ip1:port,ip2:port:.../dbname?autosavepoint=true")

# 第二种：在键值对形式的DSN中添加
conn = psycopg2.connect("user=username host=ip dbname=xxx autosavepoint=true")

# 第三种：连接时传递参数
conn = psycopg2.connect(user=username，host=ip, dbname=xxx, autosavepoint=True)

# 第四种：创建连接后设置
conn = psycopg2.connect(user=username，host=ip, dbname=xxx)
conn.autosavepoint = True

新增占位符

扩展了原有的占位符，默认使用 % 作为占位符，现在可以使用美元符号 $ 作为占位符。

示例：

import psycopg2 as pg
conn = pg.connect(database = 'testdb' ...)
cursor = conn.cursor()

cursor.execute("delete from map")

for i in range(0, 10):
    cursor.execute("insert into map values($1, $2)", [i, i + 1], place_holder = '$')

cursor.execute("select * from map")
print(cursor.fetchall())

cursor.execute("select key from map where key > $2 and value > $1", [3, 5], place_holder = '$')
print(cursor.fetchall())

for i in range(0, 10):
    if i % 2 == 1:
        cursor.execute("delete from map where key = $1 and value = $2", [i, i + 1], place_holder = '$')

cursor.execute("select * from map")
print(cursor.fetchall())

特别的，新增的占位符参数 place_holder 可以作为一个参数传入类似 execute 这样的函数，默认值是百分号。也就是说如果要使用美元符号作为占位符，那么必须指定参数 place_holder = '$'。

要强调的一点是，占位符同一时刻只有一个可以生效，例如当设定 place_holder = '%' 时，所有的美元符号都将作为普通字符而不是转义字符处理。反之亦然。

当使用 % 作为占位符是，SQL 中如果要包含 % 字符，需使用 %% 转义，同样的，当 place_holder = '$' 时要输出一个美元符号，就需要使用 $$ 进行转义。

extras 模块新增批处理函数

extras.execute_prepared_batch
extras.execute_params_batch

使用示例：

相比提交单条数据，批量提交时需使用二维数据作为数据参数

注意：由于这两个批处理接口都是提交给服务端进行解析和绑定变量，所以 SQL 中的占位符需要是数据库中支持的格式，需使用 $1, $2 这样的格式进行指定。

execute_prepared_batch

# 创建一个 prepare statement: prep
cur.execute("prepare prep as insert into test values ($1, $2)")
# 执行 prep 这个函数，将批量参数传递进去
execute_prepared_batch(cur, "prep", [[1, '1'], [2, '2'], [3, '3']])

execute_params_batch

# 无需提前创建  prepare statement, 直接将 sql 和数据一起提交
execute_params_batch(cur, "insert into t3 values ($1, $2)", [[1, '1'], [2, '2'], [3, '3']])