JDBC 会话管理命令 (PostgreSQL)

Spanner JDBC 驱动程序（Java 数据库连接）支持会话 管理语句，允许您修改连接状态、 执行事务，以及高效地执行批量语句。

以下命令适用于 PostgreSQL 方言数据库。

注意 ：会话管理语句只能与 Spanner JDBC 驱动程序。会话管理 语句在客户端库、Google Cloud CLI 或 JDBC 中不起作用 驱动程序。

连接语句

以下语句会更改或显示当前连接的属性。

SPANNER.READONLY

指示连接是否处于只读模式的布尔值。通过 默认值为 false。

SHOW [VARIABLE] SPANNER.READONLY
SET SPANNER.READONLY {TO|=} { true | false }

您只能在没有有效属性时更改此属性的值 交易。

▶ 示例：只读交易（点击展开）

以下示例展示了如何使用此属性以只读模式执行 Spanner 中的事务。

SET SPANNER.READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;

-- The following two queries both use the read-only transaction.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title
FROM Albums
ORDER BY Title;

-- This shows the read timestamp that was used for the two queries.
SHOW SPANNER.READ_TIMESTAMP;

-- This marks the end of the read-only transaction. The next statement starts
-- a new read-only transaction.
COMMIT;

自动提交

指示连接是否处于自动提交模式的布尔值。通过 默认值为 true。

SHOW [VARIABLE] AUTOCOMMIT
SET AUTOCOMMIT {TO|=} { true | false }

只有在没有有效属性时，才能更改此属性的值 交易。

当 AUTOCOMMIT 设置为 false 时，系统会自动启动新事务 在执行 COMMIT 或 ROLLBACK 之后。您执行的第一个语句 启动事务。

▶ 示例：自动提交（点击即可展开）

以下示例展示了如何使用 autocommit 属性。

-- The default value for AUTOCOMMIT is true.
SHOW AUTOCOMMIT;

-- This insert statement is automatically committed after it is executed, as
-- the connection is in autocommit mode.
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);

-- Turning off autocommit means that a new transaction is automatically started
-- when the next statement is executed.
SET AUTOCOMMIT = FALSE;
-- The following statement starts a new transaction.
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);

-- This statement uses the same transaction as the previous statement.
INSERT INTO T (id, col_a, col_b) VALUES (3, 300, 3);

-- Commit the current transaction with the two INSERT statements.
COMMIT;

-- Transactions can also be executed in autocommit mode by executing the BEGIN
-- statement.
SET AUTOCOMMIT = FALSE;

-- Execute a transaction while in autocommit mode.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (4, 400, 4);
INSERT INTO T (id, col_a, col_b) VALUES (5, 500, 5);
COMMIT;

SPANNER.RETRY_ABORTS_INTERNALLY

指示连接是否已取消自动重试的布尔值 交易。默认值为 true。

SHOW [VARIABLE] SPANNER.RETRY_ABORTS_INTERNALLY
SET SPANNER.RETRY_ABORTS_INTERNALLY {TO|=} { true | false }

只有在交易开始后，您才能更改此属性的值 （请参阅 BEGIN TRANSACTION）及之前 事务内执行任何语句。

当您将 SPANNER.RETRY_ABORTS_INTERNALLY 设置为 true 时，连接会保持 连接返回给客户端应用的所有数据的校验和。这个 用于在事务被 Spanner 取消时重试。

默认值为 true。如果存在以下情况，我们建议将此值设为 false： 您的应用已经重试被中止的事务。

SPANNER.AUTOCOMMIT_DML_MODE

一个 STRING 属性，用于指示以下应用的自动提交模式 数据操纵语言 (DML) 语句。

SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }

可能的值包括：

• 在 TRANSACTIONAL 模式下，驱动程序将 DML 语句作为单独的原子化事务执行。驱动程序会创建新事务、执行 DML 语句，并在成功执行后提交事务，或在发生错误时回滚事务。
• 在 PARTITIONED_NON_ATOMIC 模式下，驱动程序将 DML 语句作为分区更新语句执行。A 已分区 更新语句可以作为一系列交易来运行，每个交易都涵盖一个 一部分受影响的行。分区语句提供 削弱语义，以换取更好的可伸缩性和性能。

默认值为 TRANSACTIONAL。

▶ 示例：分区 DML（点击即可展开）

以下示例展示了如何执行 分区 DML（使用 Spanner JDBC 驱动程序。

-- Change autocommit DML mode to use Partitioned DML.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'PARTITIONED_NON_ATOMIC';

-- Delete all singers that have been marked as inactive.
-- This statement is executed using Partitioned DML.
DELETE
FROM singers
WHERE active=false;

-- Change DML mode back to standard `TRANSACTIONAL`.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';

STATEMENT_TIMEOUT

STRING 类型的属性，用于指示语句的当前超时值。

SHOW [VARIABLE] STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT {TO|=} { '<int8>{ s | ms | us | ns }' | <int8> | DEFAULT }

int8 值是一个整数，后跟表示时间的后缀 单位。DEFAULT 表示 0 秒，相当于没有超时。一个 没有单位的 int8 数字表示毫秒。如果设置了语句超时值 超过指定超时值的语句将会导致 java.sql.SQLTimeoutException 错误，并让交易失效。

受支持的时间单位包括：

• s：秒
• ms：毫秒
• us：微秒
• ns：纳秒

默认值为 0，表示没有超时。

事务期间的语句超时会使事务失效， 失效事务中的后续语句（ROLLBACK 除外）失败， Spanner JDBC 驱动程序抛出 java.sql.SQLTimeoutException。

SPANNER.READ_ONLY_STALENESS

STRING 类型的属性，指示当前的 只读过时设置 Spanner 在 AUTOCOMMIT 中用于只读事务和查询 模式。

SHOW [VARIABLE] SPANNER.READ_ONLY_STALENESS
SET SPANNER.READ_ONLY_STALENESS {TO|=} staleness_type

staleness_type:

{ 'STRONG' 
  | 'MIN_READ_TIMESTAMP timestamp'
  | 'READ_TIMESTAMP timestamp'
  | 'MAX_STALENESS <int8>{ s | ms | us | ns }'
  | 'EXACT_STALENESS <int8>{ s | ms | us | ns }' }

read-only staleness 值适用于所有 后续只读事务以及 AUTOCOMMIT 模式下的所有查询。

默认值为 STRONG。

时间戳边界选项如下所示：

• STRONG 告知 Spanner 对 强读：
• MAX_STALENESS 定义 Spanner 用于执行特定操作的时间间隔 执行 有界限过时读取、 相对于now()。
• MIN_READ_TIMESTAMP 定义了 Spanner 执行以下操作的绝对时间 执行 有界限过时读取。
• EXACT_STALENESS 定义 Spanner 用于执行特定操作的时间间隔 执行 精确过时读取、 相对于now()。
• READ_TIMESTAMP 定义了 Spanner 执行以下操作的绝对时间 执行精确的过时读取

时间戳必须采用以下格式：

YYYY-[M]M-[D]DT[[H]H:[M]M:[S]S[.DDDDDD]][timezone]

设置 MAX_STALENESS 和 EXACT_STALENESS 值所支持的时间单位包括：

• s：秒
• ms：毫秒
• us：微秒
• ns：纳秒

只有在没有有效属性时，才能修改此属性的值 交易。

注意 ：您只能将值 MIN_READ_TIMESTAMP 和 MAX_STALENESS 用于 AUTOCOMMIT 模式下的查询。

▶ 示例：只读过时（点击即可展开）

以下示例展示了如何使用自定义过时执行查询 值。

-- Set the read-only staleness to MAX_STALENESS 10 seconds.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 10s';

-- Execute a query in auto-commit mode. This returns results that are up to
-- 10 seconds stale.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is only allowed for queries in autocommit mode.
-- Change the staleness to EXACT_STALENESS and start a read-only transaction.
SET SPANNER.READ_ONLY_STALENESS = 'EXACT_STALENESS 10s';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title, SingerId
FROM Albums
ORDER BY Title;

COMMIT;

-- Set the read staleness to an exact timestamp.
SET SPANNER.READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_VERSION

STRING 类型的属性，用于指示 优化器版本。版本为 可以是整数或“LATEST”。

SHOW [VARIABLE] SPANNER.OPTIMIZER_VERSION
SET SPANNER.OPTIMIZER_VERSION {TO|=} { 'version'|'LATEST'|'' }

设置要用于 上的以下所有语句的优化器版本 连接。如果优化器版本设置为 ''（空字符串），则 Spanner 使用最新版本。如果未设置优化器版本 Spanner 使用在数据库中设置的优化器版本 。

默认值为 ''。

▶ 示例：优化工具版本（点击即可展开）

以下示例展示了如何使用 优化器版本 Spanner JDBC 驱动程序。

-- Set the optimizer version to 5 and execute a query.
SET SPANNER.OPTIMIZER_VERSION = '5';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the latest optimizer version.
SET SPANNER.OPTIMIZER_VERSION = 'LATEST';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Revert back to using the default optimizer version that has been set for the
-- database.
SET SPANNER.OPTIMIZER_VERSION = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_STATISTICS_PACKAGE

STRING 类型的属性，指示当前的 优化工具统计信息软件包 此连接所使用的 IP 地址。

SHOW [VARIABLE] SPANNER.OPTIMIZER_STATISTICS_PACKAGE
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE {TO|=} { 'package'|'' }

设置优化器统计信息包，以便在 连接。<package> 必须是有效的软件包名称。如果没有优化器 统计信息包设置后，Spanner 会使用优化器统计信息 在数据库级别设置的软件包

默认值为 ''。

▶ 示例：优化工具统计信息包（点击展开）

以下示例展示了如何使用 优化器统计信息软件包，其中包含 Spanner JDBC 驱动程序。

-- Show the available optimizer statistics packages in this database.
SELECT * FROM INFORMATION_SCHEMA.SPANNER_STATISTICS;

-- Set the optimizer statistics package and execute a query.
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the default optimizer statistics package.
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.RETURN_COMMIT_STATS

BOOL 类型的属性，用于指明是否应针对 数据。您可以查看返回的统计信息，只需执行 SHOW SPANNER.COMMIT_RESPONSE 命令。

SHOW [VARIABLE] SPANNER.RETURN_COMMIT_STATS
SET SPANNER.RETURN_COMMIT_STATS {TO|=} { true | false }

默认值为 false。

▶ 示例：提交统计信息（点击展开）

以下示例展示了如何查看事务的提交统计信息 Spanner JDBC 驱动程序。

-- Enable the returning of commit stats.
SET SPANNER.RETURN_COMMIT_STATS = true;

-- Execute a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);
COMMIT;

-- View the commit response with the transaction statistics for the last
-- transaction that was committed.
SHOW SPANNER.COMMIT_RESPONSE;

SPANNER.RPC_PRIORITY

一个类型为 STRING 的属性，用于表示以下对象的相对优先级： Spanner 请求。优先级作为提示 Spanner 调度器，并不保证执行顺序。

SHOW [VARIABLE] SPANNER.RPC_PRIORITY
SET SPANNER.RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

'NULL' 表示请求中不应包含任何提示。

默认值为 'NULL'。

您还可以使用语句提示来指定 RPC 优先级：

/*@RPC_PRIORITY=PRIORITY_LOW*/ SELECT * FROM Albums

如需了解详情，请参阅 Priority。

标记

以下语句用于管理请求代码和交易代码。

SPANNER.STATEMENT_TAG

一个类型为 STRING 的属性，其中包含下一个 声明。

SHOW [VARIABLE] SPANNER.STATEMENT_TAG
SET SPANNER.STATEMENT_TAG {TO|=} 'tag-name'

设置要执行的下一个语句的请求标记。仅一个 标签。代码不会跨多个语句；它 必须针对每条语句进行设置。将请求标记设置为 空字符串 ('')。

默认值为 ''。

您可以为同一对账单同时设置交易标记和对账单标记。

您还可以使用语句提示来添加语句标记：

/*@STATEMENT_TAG='my-tag'*/ SELECT * FROM Albums

如需了解详情，请参阅 使用请求代码和交易代码排查问题。

▶ 示例：语句代码（点击展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序。

-- Set the statement tag that should be included with the next statement.
SET SPANNER.STATEMENT_TAG = 'tag1';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- The statement tag property is cleared after each statement execution.
SHOW SPANNER.STATEMENT_TAG;
-- Set another tag for the next statement.
SET SPANNER.STATEMENT_TAG = 'tag2';
SELECT Title
FROM Albums
ORDER BY Title;

-- Set a statement tag with a query hint.
/*@STATEMENT_TAG='tag3'*/
SELECT TrackNumber, Title
FROM Tracks
WHERE AlbumId=1 AND SingerId=1
ORDER BY TrackNumber;

SPANNER.TRANSACTION_TAG

一个类型为 STRING 的属性，其中包含下一笔交易的代码 交易。

SHOW [VARIABLE] SPANNER.TRANSACTION_TAG
SET SPANNER.TRANSACTION_TAG {TO|=} 'tag-name'

设置要执行的当前事务的事务代码。仅一个 可以按交易设置代码代码不会跨越多个交易；它 必须针对每笔交易进行设置。可通过执行以下操作移除交易代码： 并将其设置为空字符串 ('')。交易代码必须在 所有语句都已在事务中执行。

默认值为 ''。

您可以为同一对账单同时设置交易标记和对账单标记。

如需了解详情，请参阅 使用请求代码和交易代码排查问题。

▶ 示例：交易代码（点击展开）

下例显示了如何使用 Spanner JDBC 驱动程序。

BEGIN;
-- Set the transaction tag for the current transaction.
SET SPANNER.TRANSACTION_TAG = 'transaction-tag-1';

-- Set the statement tag that should be included with the next statement.
-- The statement will include both the statement tag and the transaction tag.
SET SPANNER.STATEMENT_TAG = 'select-statement';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- The statement tag property is cleared after each statement execution.
SHOW SPANNER.STATEMENT_TAG;

-- Set another tag for the next statement.
SET SPANNER.STATEMENT_TAG = 'insert-statement';
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

-- The transaction tag property is cleared when the transaction finishes.
SHOW SPANNER.TRANSACTION_TAG;

事务语句

以下语句用于管理和提交 Spanner 事务。

交易隔离级别

SHOW [VARIABLE] TRANSACTION ISOLATION LEVEL

返回一个结果集，其中包含 STRING 类型的一行和一列。已发回 值始终为 serializable。

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

返回一个结果集，其中包含 TIMESTAMP 类型的一行和一列，该结果集包括最近一次只读事务的读取时间戳。只有在只读事务仍处于活跃状态并且已执行至少一个查询时，或者只有在紧接着已提交只读事务之后且新事务启动之前，此语句才会返回时间戳。否则，结果为 NULL。

▶ 示例：阅读时间戳（点击即可展开）

以下示例展示了如何查看 Spanner JDBC 驱动程序的只读操作。

-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp that was used for the previous query.
SHOW SPANNER.READ_TIMESTAMP;

-- Set a non-deterministic read-only staleness and execute the same query.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 20s';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp that was used for the previous query. The timestamp
-- is determined by Spanner, and is guaranteed to be no less than
-- 20 seconds stale.
SHOW SPANNER.READ_TIMESTAMP;

-- The read timestamp of a read-only transaction can also be retrieved.
SET SPANNER.READ_ONLY_STALENESS = 'STRONG';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp of the current read-only transaction. All queries in
-- this transaction will use this read timestamp.
SHOW SPANNER.READ_TIMESTAMP;

SELECT Title
FROM Albums
ORDER BY Title;

-- The read timestamp is the same as for the previous query, as all queries in
-- the same transaction use the same read timestamp.
SHOW SPANNER.READ_TIMESTAMP;

COMMIT;

SPANNER.COMMIT_TIMESTAMP

SHOW [VARIABLE] SPANNER.COMMIT_TIMESTAMP

返回一个结果集，其中包含 TIMESTAMP 类型的一行和一列，该行包含 最近一次读写事务的提交时间戳 Spanner 已提交。仅当出现以下情况时，该语句才会返回时间戳： 在提交读写事务之后和执行 任何后续的 SELECT、DML 或架构更改语句。否则， 结果为 NULL。

▶ 示例：提交时间戳（点击即可展开）

以下示例展示了如何查看 Spanner JDBC 驱动程序执行写入操作。

-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);

-- Show the timestamp that the statement was committed.
SHOW SPANNER.COMMIT_TIMESTAMP;

SPANNER.COMMIT_RESPONSE

SHOW [VARIABLE] SPANNER.COMMIT_RESPONSE

返回包含一行和两列的结果集：

• COMMIT_TIMESTAMP (type=TIMESTAMP) 表示最近的 事务已提交。
• MUTATION_COUNT (type=INT64) 表示在 已提交的事务。在 模拟器。

只有当 SET SPANNER.RETURN_COMMIT_STATS 为 设置为 true。

▶ 示例：提交响应（点击即可展开）

以下示例展示了如何查看 Spanner JDBC 驱动程序执行写入操作。

-- Enable returning commit stats in addition to the commit timestamp.
SET SPANNER.RETURN_COMMIT_STATS = true;

-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);

-- Show the timestamp that the statement was committed.
SHOW SPANNER.COMMIT_RESPONSE;

{开始 |开始 } [ 交易 |工作 ]

{ START | BEGIN } [ TRANSACTION | WORK ] [{ READ ONLY | READ WRITE }]

启动新事务。关键字 TRANSACTION 和 WORK 是可选的， 等效，没有任何作用。

• 使用 COMMIT 或 ROLLBACK 终止事务。
• 如果您启用了 AUTOCOMMIT 模式，则此语句会暂时将连接退出 AUTOCOMMIT 模式。当事务结束时，连接将返回 AUTOCOMMIT 模式。
• 如果未指定 READ ONLY 或 READ WRITE，则事务模式为 由会话的默认事务模式决定。默认值为 使用 SET SESSION CHARACTERISTICS AS TRANSACTION 命令进行设置，或按 设置 READONLY 变量。

只有在没有活跃事务的情况下您才能执行此语句。

▶ 示例：开始交易（点击即可展开）

以下示例展示了如何使用以下代码启动不同类型的事务： Spanner JDBC 驱动程序。

-- This starts a transaction using the current defaults of this connection.
-- The value of READONLY determines whether the transaction is a
-- read-write or a read-only transaction.

BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Set READONLY to TRUE to use read-only transactions by default.
SET READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

-- Add 'READ WRITE' or 'READ ONLY' to the 'BEGIN' command to
-- override the current default of the connection.
SET READONLY=FALSE;
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

提交 [交易 |单位]

COMMIT [ TRANSACTION | WORK ]

提交当前事务。关键字“TRANSACTION”和“WORK”是 是可选字段，也是等效属性，它们都没有作用。

• 提交读写事务将对此事务进行所有更新 对其他事务可见，并解除事务在 Spanner。
• 提交只读事务会结束当前的只读事务。任何后续语句都会启动新事务。对于只读事务，COMMIT 和 ROLLBACK 之间没有语义差异。

只有在存在活跃事务的情况下才能执行此语句。

▶ 示例：提交交易（点击即可展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序。

-- Execute a regular read-write transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Execute a read-only transaction. Read-only transactions also need to be
-- either committed or rolled back in the Spanner JDBC driver in order
-- to mark the end of the transaction.
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

{ ABORT |ROLLBACK } [交易 |单位]

{ ABORT | ROLLBACK } [TRANSACTION | WORK]

对当前事务执行 ROLLBACK。关键字“TRANSACTION”和 WORK 是可选且等效的，没有任何作用。

• 对读写事务执行 ROLLBACK 会清除所有已缓冲的数据 变更、回滚 Spanner 上的事务以及进行发布 锁定事务持有的任何锁。
• 对只读事务执行 ROLLBACK 会结束当前的只读事务。任何后续语句都会启动新事务。对于连接上的只读事务，COMMIT 和 ROLLBACK 之间没有语义差异。

只有在存在活跃事务的情况下才能执行此语句。

▶ 示例：回滚交易（点击即可展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序。

-- Use ROLLBACK to undo the effects of a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
-- This ensures that the insert statement is not persisted in the database.
ROLLBACK;

-- Read-only transactions also need to be either committed or rolled back in the
-- Spanner JDBC driver in order to mark the end of the transaction.
-- There is no semantic difference between rolling back or committing a
-- read-only transaction.
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

设置当前事务的事务模式。

只有在 AUTOCOMMIT 为 false 时，或者 通过执行 BEGIN [TRANSACTION | WORK] 启动了一个事务，并且尚未 事务中尚未执行任何语句。

此语句仅为当前事务设置事务模式。时间 事务提交或回滚，则下一个事务将使用默认值 模式。 （请参阅 SET SESSION CHARACTERISTICS。）

注意 ：如果连接是READ WRITE READ ONLY 模式。

▶ 示例：设置交易（点击即可展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序。

-- Start a transaction and set the transaction mode to read-only.
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Commit the read-only transaction to mark the end of the transaction.
COMMIT;

-- Start a transaction and set the transaction mode to read-write.
BEGIN;
SET TRANSACTION READ WRITE;

INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

设置会话特征

SET SESSION CHARACTERISTICS AS TRANSACTION { READ ONLY | READ WRITE }

将会话中事务的默认事务模式设置为 READ ONLY 或 READ WRITE。仅当 有效交易。

SET TRANSACTION 命令可以覆盖此设置。

批量语句

以下语句用于管理批量 DDL 语句并发送这些批量 Spanner。

START BATCH DDL

START BATCH DDL

在连接上启动一批 DDL 语句。批处理期间的所有后续语句都必须是 DDL 语句。DDL 语句在本地缓冲 并在执行 RUN BATCH 时作为一个批次发送到 Spanner。 将多个 DDL 语句作为一个批次执行通常比单独运行语句速度快。

只有在没有活跃事务的情况下您才能执行此语句。

▶ 示例：DDL 批次（点击即可展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序。

-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Singers (
  SingerId  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Albums (
  AlbumId  BIGINT NOT NULL PRIMARY KEY,
  Title    VARCHAR,
  SingerId BIGINT,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
);

-- This runs the DDL statements as one batch.
RUN BATCH;

RUN BATCH

RUN BATCH

将当前 DDL 批次中所有已缓冲的 DDL 语句发送到数据库。 等待 Spanner 执行这些语句，并结束 当前 DDL 批次。

如果 Spanner 无法执行至少一个 DDL 语句，请RUN BATCH 针对 Spanner 无法实现的第一个 DDL 语句返回错误 。否则，RUN BATCH 会成功返回。

注意 ：如果批次中的 DDL 语句返回错误，Spanner 可能仍然将同一批次中的上述 DDL 语句应用于 数据库。

ABORT BATCH

ABORT BATCH

清除当前 DDL 批次中所有缓存的 DDL 语句，然后结束该批次。

只有在 DDL 批次处于活跃状态的情况下您才能执行此语句。您可以使用 ABORT BATCH，无论批次是否有缓冲 DDL 语句。该批次中所有前面的 DDL 语句都将被取消。

▶ 示例：中止 DDL 批次（点击即可展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序。

-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;

-- The following statements are buffered locally.
CREATE TABLE Singers (
  SingerId  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Albums (
  AlbumId  BIGINT NOT NULL PRIMARY KEY,
  Title    VARCHAR,
  SingerId BIGINT,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
);

-- This aborts the DDL batch and removes the DDL statements from the buffer.
ABORT BATCH;

启动 BATCH DML 并运行 BATCH

以下语句同时批处理两个 DML 语句，并通过一次调用将其发送到服务器。DML 批处理可以作为事务的一部分执行，也可以在自动提交模式下执行。

START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
RUN BATCH;

▶ 示例：DML 批次（点击即可展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序。

-- Start a DML batch. All following statements must be a DML statement.
START BATCH DML;

-- The following statements are buffered locally.
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');

-- This sends the statements to Spanner.
RUN BATCH;

-- DML batches can also be part of a read/write transaction.
BEGIN;
-- Insert a row using a single statement.
INSERT INTO MYTABLE (ID, NAME) VALUES (3, 'THREE');

-- Insert two rows using a batch.
START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (4, 'FOUR');
INSERT INTO MYTABLE (ID, NAME) VALUES (5, 'FIVE');
RUN BATCH;

-- Rollback the current transaction. This rolls back both the single DML
-- statement and the DML batch.
ROLLBACK;

Data Boost 和分区查询语句

partitionQuery API 将查询划分为较小的部分或分区，并使用多个 并行提取分区。每个分区都由 分区标记。PartitionQuery API 的延迟时间比标准 Query API，因为它仅适用于批量操作，例如导出或 扫描整个数据库。

数据提升 执行分析查询和数据导出，费用接近于零 对已预配 Spanner 实例上现有工作负载的影响。 Data Boost 仅支持分区查询。

您可以使用 SET SPANNER.DATA_BOOST_ENABLED 语句。

JDBC 驱动程序支持使用三种替代方案来执行分区查询：

• SET SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql，后跟多个 RUN PARTITION 'partition-token'

以下各部分分别介绍了这些方法。

SPANNER.DATA_BOOST_ENABLED

BOOL 类型的属性，用于指示此连接是否应使用 针对分区查询的 Data Boost。默认 为 false。

SHOW [VARIABLE] SPANNER.DATA_BOOST_ENABLED
SET SPANNER.DATA_BOOST_ENABLED {TO|=} { true | false }

设置此连接是否应使用 针对分区查询的 Data Boost。

默认值为 false。

▶ 示例：使用 Data Boost 执行查询（点击即可展开）

以下示例展示了如何使用 Data Boost 和 Spanner JDBC 驱动程序。

-- Enable Data Boost on this connection.
SET SPANNER.DATA_BOOST_ENABLED = true;

-- Execute a partitioned query. Data Boost is only used for partitioned queries.
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers;

如需查看完整示例，请参阅 PostgreSQL DataBoostExample。

SPANNER.AUTO_PARTITION_MODE

BOOL 类型的属性，用于指示连接是否自动使用 所有已执行查询的分区查询。

SHOW [VARIABLE] SPANNER.AUTO_PARTITION_MODE
SET SPANNER.AUTO_PARTITION_MODE {TO|=} { true | false}

• 如果您希望该连接使用，请将此变量设置为 true 所有已执行查询的分区查询。
• 此外，若要将 SPANNER.DATA_BOOST_ENABLED 设为 true， Data Boost 可让你 查询。

默认值为 false。

▶ 示例：执行（点击即可展开）

此示例使用 数据提升

SET SPANNER.AUTO_PARTITION_MODE = true
SET SPANNER.DATA_BOOST_ENABLED = true
SELECT FirstName, LastName FROM Singers
SELECT SingerId, Title FROM Albums

如需查看完整示例，请参阅 PostgreSQL AutoPartitionModeExample。

运行分区查询

RUN PARTITIONED QUERY <sql>

在 Spanner 上将查询作为分区查询执行。请确保 SPANNER.DATA_BOOST_ENABLED 设置为 true，可使用 数据提升：

SET SPANNER.DATA_BOOST_ENABLED = true
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers

JDBC 驱动程序在内部对查询进行分区，并在其中执行分区 并行运行。这些结果会合并为一个结果集并返回 应用。可通过以下方法设置执行分区的工作器线程数： 变量 SPANNER.MAX_PARTITIONED_PARALLELISM。

如需查看完整示例，请参阅 PostgreSQL RunPartitionedQueryExample。

分区 <SQL>

PARTITION <sql>

创建分区列表以对 Spanner 执行查询，以及 会返回分区令牌列表。每个分区令牌都可以执行， 使用 RUN PARTITION 'partition-token' 命令。

▶ 示例：分区查询（点击展开）

以下示例展示了如何对查询进行分区，然后分别执行 使用 Spanner JDBC 驱动程序单独进行分区。

-- Partition a query. This returns a list of partition tokens that can be
-- executed either on this connection or on any other connection to the same
-- database.
PARTITION SELECT FirstName, LastName FROM Singers;

-- Run the partitions that were returned from the previous statement.
RUN PARTITION 'partition-token-1';
RUN PARTITION 'partition-token-2';

如需查看完整示例，请参阅 PostgreSQL PartitionQueryExample。

RUN PARTITION '分区令牌'

RUN PARTITION 'partition-token'

执行之前由 PARTITION 返回的查询分区 命令。该命令可以在连接到 与创建分区令牌的数据库相同的数据库。

如需查看完整示例，请参阅 PostgreSQL PartitionQueryExample。

SPANNER.MAX_PARTITIONED_PARALLELISM

int8 类型的属性，指示 用于执行分区的 Spanner JDBC 驱动程序。此值用于：

• SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW [VARIABLE] SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM = <int8>

设置 Spanner JDBC 驱动程序的工作器线程数上限 可用于执行分区。将此值设置为 0 会指示 Spanner JDBC 驱动程序，使用客户端上的 CPU 核心数 最大机器数量

默认值为 0。

Savepoint 命令

以下语句可启用和停用模拟 savepoints 和交易中您可以通过调用 java.sql.Connection#setSavepoint() 方法。

Spanner JDBC 驱动程序模拟保存点，以支持 则依赖于这些 API 进行嵌套事务。Savepoint 通过跟踪 中语句所返回结果的运行校验和 交易。回滚到 Savepoint 时， Spanner JDBC 驱动程序回滚事务，然后重试 一直到设置 Savepoint 为止。该 与初始事务的校验和进行比较，以验证 都返回了相同的结果。

SPANNER.SAVEPOINT_SUPPORT

SHOW [VARIABLE] SPANNER.SAVEPOINT_SUPPORT
SET SPANNER.SAVEPOINT_SUPPORT {TO|=} { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }

一个类型为 STRING 的属性，用于表示当前的 SAVEPOINT_SUPPORT 配置。可能的值包括：

• DISABLED：所有 Savepoint 命令已停用，将会失败。
• FAIL_AFTER_ROLLBACK：已启用 Savepoint 命令。回滚到 Savepoint 将回滚整个事务。如果您尝试 以便在回滚到 Savepoint 后使用该事务。
• ENABLED：所有 Savepoint 命令均已启用。回滚到存档点 将回滚事务，并在保存点重试。这个 如果出现以下情况，操作会失败并显示 AbortedDueToConcurrentModificationException 错误 截至 Savepoint 为止，事务已使用的底层数据 已更改。

默认值为 FAIL_AFTER_ROLLBACK。

您只能在没有有效变量时更改此变量的值 交易。

▶ 示例：支持 Savepoint（点击即可展开）

以下示例展示了如何在 Spanner JDBC 驱动程序。

try (Connection connection =
    DriverManager.getConnection(
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            "my-project", "my-instance", "my-database"))) {
  // Savepoints can only be used when AutoCommit=false.
  connection.setAutoCommit(false);

  // Disables setting a savepoint.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='DISABLED'");
  // The following statement fails because savepoints have been disabled.
  connection.setSavepoint("my_savepoint1");

  // Enables setting a savepoint and releasing a savepoint.
  // Rolling back to a savepoint is disabled.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='FAIL_AFTER_ROLLBACK'");
  Savepoint mySavepoint2 = connection.setSavepoint("my_savepoint2");
  connection.createStatement().execute("insert into my_table (id, value) values (1, 'One')");
  connection.releaseSavepoint(mySavepoint2);
  connection.commit();

  // Enables setting, releasing and rolling back to a savepoint.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='ENABLED'");
  Savepoint mySavepoint3 = connection.setSavepoint("my_savepoint3");
  connection.createStatement().execute("insert into my_table (id, value) values (2, 'Two')");
  connection.rollback(mySavepoint3);
}

后续步骤

了解如何将 JDBC 连接到 PostgreSQL 方言数据库。