JDBC 会话管理命令 (GoogleSQL)

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

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

注意 ：会话管理语句只能用于 Spanner JDBC 驱动程序。会话管理语句在客户端库、Google Cloud CLI 或 Simba 创建的 JDBC 驱动程序中不适用。

连接语句

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

READONLY

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

SHOW VARIABLE READONLY
SET READONLY = { true | false }

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

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

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

SET 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 VARIABLE 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 = { true | false }

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

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

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

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

-- The default value for AUTOCOMMIT is true.
SHOW VARIABLE 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;

RETRY_ABORTS_INTERNALLY

指示连接是否自动重试已中止的事务的布尔值。默认值为 true。

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }

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

当您将 RETRY_ABORTS_INTERNALLY 设置为 true 时，连接会保留其返回到客户端应用的所有数据的校验和。如果 Spanner 取消事务，此字段用于重试事务。

默认值为 true。如果您的应用已经重试中止的事务，我们建议您将此值设置为 false。

AUTOCOMMIT_DML_MODE

STRING 属性，表示数据操纵语言 (DML) 语句的自动提交模式。

SHOW VARIABLE AUTOCOMMIT_DML_MODE
SET AUTOCOMMIT_DML_MODE = { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }

可能的值包括：

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

默认值为 TRANSACTIONAL。

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

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

-- Change autocommit DML mode to use Partitioned DML.
SET 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 AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';

STATEMENT_TIMEOUT

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

SHOW VARIABLE STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT = { '<INT64>{ s | ms | us | ns }' | NULL }

INT64 值是一个整数，后跟表示时间单位的后缀。值 NULL 表示未设置超时值。如果已设置语句超时值，则所用时间超过指定超时值的语句将导致 java.sql.SQLTimeoutException 错误并使事务失效。

受支持的时间单位包括：

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

默认值为 NULL，表示未设置超时值。

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

READ_ONLY_STALENESS

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

SHOW VARIABLE READ_ONLY_STALENESS
SET READ_ONLY_STALENESS = staleness_type

staleness_type:

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

只读过时值适用于所有后续只读事务以及 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 模式下的查询。

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

以下示例展示了如何通过 Spanner JDBC 驱动程序使用自定义过时值执行查询。

-- Set the read-only staleness to MAX_STALENESS 10 seconds.
SET 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 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 READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_VERSION

一个类型为 STRING 的属性，表示优化器版本。版本可以是整数，也可以是“LATEST”。

SHOW VARIABLE OPTIMIZER_VERSION
SET OPTIMIZER_VERSION = { 'version'|'LATEST'|'' }

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

默认值为 ''。

▶ 示例：优化器版本（点击展开）

以下示例展示了如何通过 Spanner JDBC 驱动程序使用特定的优化器版本执行查询。

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the latest optimizer version.
SET 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 OPTIMIZER_VERSION = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_STATISTICS_PACKAGE

一个类型为 STRING 的属性，表示此连接当前使用的优化器统计信息软件包。

SHOW VARIABLE OPTIMIZER_STATISTICS_PACKAGE
SET OPTIMIZER_STATISTICS_PACKAGE = { '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 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 OPTIMIZER_STATISTICS_PACKAGE = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

RETURN_COMMIT_STATS

一个类型为 BOOL 的属性，用于指示是否应为此连接上的事务返回统计信息。您可以执行 SHOW VARIABLE COMMIT_RESPONSE 命令来查看返回的统计信息。

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }

默认值为 false。

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

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

-- Enable the returning of commit stats.
SET 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 VARIABLE COMMIT_RESPONSE;

RPC_PRIORITY

一个类型为 STRING 的属性，表示 Spanner 请求的相对优先级。优先级充当对 Spanner 调度器的提示，但不保证执行顺序。

SHOW VARIABLE RPC_PRIORITY
SET RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

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

默认值为 'NULL'。

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

标记

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

STATEMENT_TAG

一个类型为 STRING 的属性，其中包含下一个语句的请求标记。

SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'

为要执行的下一个语句设置请求标记。每个语句只能设置一个标记。该标记不能跨越多个语句，而是必须针对每个语句进行设置。可以通过将请求标记设置为空字符串 ('') 来移除该标记。

默认值为 ''。

您可以为同一语句设置交易标记和语句标记。

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

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

以下示例展示了如何使用 Spanner JDBC 驱动程序设置语句标记。

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

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

TRANSACTION_TAG

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

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

设置要执行的当前交易的交易代码。每笔交易只能设置一个标记。该代码不能跨多笔交易，必须针对每笔交易进行设置。可以将交易代码设为空字符串 ('') 以将其移除。交易代码必须在交易中执行任何语句之前设置。

默认值为 ''。

您可以为同一语句设置交易标记和语句标记。

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

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

以下示例展示了如何使用 Spanner JDBC 驱动程序设置事务标记。

BEGIN;
-- Set the transaction tag for the current transaction.
SET 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 STATEMENT_TAG = 'select-statement';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

-- Set another tag for the next statement.
SET 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 VARIABLE TRANSACTION_TAG;

事务语句

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

READ_TIMESTAMP

SHOW VARIABLE 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 VARIABLE READ_TIMESTAMP;

-- Set a non-deterministic read-only staleness and execute the same query.
SET 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 VARIABLE READ_TIMESTAMP;

-- The read timestamp of a read-only transaction can also be retrieved.
SET 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 VARIABLE 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 VARIABLE READ_TIMESTAMP;

COMMIT;

COMMIT_TIMESTAMP

SHOW VARIABLE 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 VARIABLE COMMIT_TIMESTAMP;

COMMIT_RESPONSE

SHOW VARIABLE COMMIT_RESPONSE

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

• COMMIT_TIMESTAMP (type=TIMESTAMP) 指示最新事务的提交时间。
• MUTATION_COUNT (type=INT64) 指示在提交的事务中应用了多少个变更。在模拟器上执行时，此值始终为空。

只有在事务提交之前 SET RETURN_COMMIT_STATS 设置为 true 时，变更计数才可用。

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

以下示例展示了如何查看使用 Spanner JDBC 驱动程序执行的写入操作的最后一次提交响应。

-- Enable returning commit stats in addition to the commit timestamp.
SET 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 VARIABLE COMMIT_RESPONSE;

BEGIN [TRANSACTION]

BEGIN [TRANSACTION]

启动新事务。关键字 TRANSACTION 是可选的。

• 使用 COMMIT 或 ROLLBACK 终止事务。
• 如果您启用了 AUTOCOMMIT 模式，则此语句会暂时将连接退出 AUTOCOMMIT 模式。当事务结束时，连接将返回 AUTOCOMMIT 模式。
• 事务模式取决于此连接的当前 READONLY 设置。此值通过使用 SET READONLY = {TRUE | FALSE} 命令进行设置。
• 要更改事务模式，可以在执行 BEGIN [TRANSACTION] 之后直接执行 SET TRANSACTION READ ONLY 或 SET TRANSACTION READ WRITE。

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

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

以下示例展示了如何使用 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;

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

COMMIT [TRANSACTION]

COMMIT [TRANSACTION]

提交当前事务。关键字 TRANSACTION 是可选的。

• 提交读写事务会使此事务的所有更新对其他事务可见，并释放对 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;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

ROLLBACK [TRANSACTION]

ROLLBACK [TRANSACTION]

对当前事务执行 ROLLBACK。关键字 TRANSACTION 是可选的。

• 对读写事务执行 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;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

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

只有在 AUTOCOMMIT 为 false 时，或者已通过执行 BEGIN [TRANSACTION] 启动事务但尚未执行该事务中的任何语句时，才能执行此语句。

此语句仅设置当前事务的事务模式。当事务提交或回滚时，下一个事务会使用连接的默认模式（请参阅 SET READONLY）。

注意 ：如果连接处于 READ ONLY 模式，则不能将事务模式设置为 READ WRITE。

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

以下示例展示了如何使用 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;

批量语句

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

START BATCH DDL

START BATCH DDL

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

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

▶ 示例：DDL 批量处理（点击展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序执行 DDL 批次。

-- 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  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

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

-- 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 语句应用于数据库。

取消批量 [交易]

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

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

▶ 示例：取消 DDL 批次（点击展开）

以下示例展示了如何使用 Spanner JDBC 驱动程序取消 DDL 批处理。

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

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

CREATE TABLE Albums (
  AlbumId  INT64 NOT NULL,
  Title    STRING(MAX),
  SingerId INT64,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
) PRIMARY KEY (AlbumId);

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

启动 BATCH DML 和运行批处理

以下语句同时批处理两个 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 驱动程序执行 DML 批处理。

-- 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 的延迟时间比标准查询 API 长，因为它仅适用于批量操作（如导出或扫描整个数据库）。

借助 Data Boost，您可以执行分析查询和数据导出，对预配的 Spanner 实例上的现有工作负载几乎没有影响。Data Boost 仅支持分区查询。

您可以使用 SET DATA_BOOST_ENABLED 语句启用 Data Boost。

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

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

以下各部分分别介绍了上述几种方法。

DATA_BOOST_ENABLED

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

SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

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

以下示例展示了如何搭配使用 Data Boost 与 Spanner JDBC 驱动程序进行查询。

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

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

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

AUTO_PARTITION_MODE

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

SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}

• 如果您希望连接对执行的所有查询使用分区查询，请将此变量设置为 true。
• 如果您希望连接对所有查询使用 Data Boost，还要将 DATA_BOOST_ENABLED 设置为 true。

默认值为 false。

▶ 示例：投放（点击展开）

此示例使用 Data Boost 的 Spanner JDBC 驱动程序执行两个查询

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

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

运行分区查询

RUN PARTITIONED QUERY <sql>

在 Spanner 上将查询作为分区查询执行。确保将 DATA_BOOST_ENABLED 设置为 true，以使用 Data Boost 执行查询：

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

Spanner JDBC 驱动程序在内部对查询进行分区并并行执行分区。系统会将这些结果合并到一个结果集中并返回给应用。您可以使用变量 MAX_PARTITIONED_PARALLELISM 设置执行分区的工作器线程数量。

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

PARTITION <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';

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

RUN PARTITION“分区令牌”

RUN PARTITION 'partition-token'

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

MAX_PARTITIONED_PARALLELISM

一个类型为 INT64 的属性，指示 Spanner JDBC 驱动程序用于执行分区的工作器线程数。此值用于：

• AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

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

默认值为 0。

Savepoint 命令

以下语句用于在事务中启用和停用模拟的 savepoint。您可以通过调用 java.sql.Connection#setSavepoint() 方法来创建 Savepoint。

Spanner JDBC 驱动程序会模拟保存点来支持依赖这些保存点进行嵌套事务的框架。系统会通过跟踪事务中的语句所返回结果的运行校验和来模拟 Savepoint。回滚到 Savepoint 时，Spanner JDBC 驱动程序会回滚事务，然后重新尝试该事务，直到设置 Savepoint 为止。系统会将重试的校验和与初始事务的校验和进行比较，以验证是否返回了相同的结果。

SAVEPOINT_SUPPORT

SHOW VARIABLE SAVEPOINT_SUPPORT
SET SAVEPOINT_SUPPORT = { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }

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

• DISABLED：所有 Savepoint 命令都已停用并将失败。
• FAIL_AFTER_ROLLBACK：Savepoint 命令已启用。回滚到 Savepoint 会回滚整个事务。如果您在回滚到 Savepoint 后尝试使用事务，则事务会失败。
• ENABLED：所有 Savepoint 命令都已启用。回滚到 Savepoint 会回滚事务，并会对 Savepoint 执行重试操作。如果截至 Savepoint 的事务使用的底层数据已更改，则此操作将失败并显示 AbortedDueToConcurrentModificationException 错误。

默认值为 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 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 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 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 连接到 GoogleSQL 方言数据库。