JDBC 会话管理命令 (GoogleSQL)

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

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

连接语句

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

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;

AUTOCOMMIT

一个布尔值，用于指示连接是否处于自动提交模式。默认为 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 = TRUE;

-- 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：纳秒

仅当没有活跃事务时，您才能修改此属性的值。

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

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

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

@{RPC_PRIORITY=PRIORITY_LOW} SELECT * FROM Albums

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

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

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

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（类型为 TIMESTAMP）表示最近一次事务提交的时间。
MUTATION_COUNT（类型为 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 来更改事务模式。

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

▶ 示例：BEGIN TRANSACTION（点击可展开）

以下示例展示了如何使用 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 之间没有语义差异。

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

▶ 示例：COMMIT TRANSACTION（点击可展开）

以下示例展示了如何使用 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 之间没有语义差异。

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

▶ 示例：ROLLBACK TRANSACTION（点击可展开）

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

▶ 示例：SET TRANSACTION（点击可展开）

以下示例展示了如何使用 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 会成功返回。

ABORT BATCH [TRANSACTION]

清除当前 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;

START BATCH DML 和 RUN 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 驱动程序执行 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

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 'partition-token'

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。

定向读取语句

一个类型为 STRING 的属性，用于为后续语句设置定向读取选项。

SHOW VARIABLE DIRECTED_READ
SET DIRECTED_READ='{"includeReplicas":{"replicaSelections":[{"location":"<location-name>"}]}}'

如需了解详情，请参阅定向读取。

Savepoint 命令

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

Spanner JDBC 驱动程序会模拟savepoint，以支持依赖于这些savepoint的框架处理嵌套事务。通过跟踪事务中语句返回的结果的运行校验和来模拟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 驱动程序中启用和停用 Savepoint 支持。

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 方言数据库。

JDBC 会话管理命令 (GoogleSQL) 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

连接语句

READONLY

▶ 示例：只读事务（点击可展开）

AUTOCOMMIT

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

RETRY_ABORTS_INTERNALLY

AUTOCOMMIT_DML_MODE

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

STATEMENT_TIMEOUT

READ_ONLY_STALENESS

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

OPTIMIZER_VERSION

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

OPTIMIZER_STATISTICS_PACKAGE

▶ 示例：优化器统计信息软件包（点击可展开）

RETURN_COMMIT_STATS

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

RPC_PRIORITY

标签

STATEMENT_TAG

▶ 示例：语句标记（点击展开）

TRANSACTION_TAG

▶ 示例：事务标记（点击可展开）

事务语句

READ_TIMESTAMP

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

COMMIT_TIMESTAMP

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

COMMIT_RESPONSE

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

BEGIN [TRANSACTION]

▶ 示例：BEGIN TRANSACTION（点击可展开）

COMMIT [TRANSACTION]

▶ 示例：COMMIT TRANSACTION（点击可展开）

ROLLBACK [TRANSACTION]

▶ 示例：ROLLBACK TRANSACTION（点击可展开）

SET TRANSACTION

▶ 示例：SET TRANSACTION（点击可展开）

批量语句

START BATCH DDL

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

RUN BATCH

ABORT BATCH [TRANSACTION]

▶ 示例：取消 DDL 批处理（点击可展开）

START BATCH DML 和 RUN BATCH

▶ 示例：DML 批处理（点击可展开）

Data Boost 和分区查询语句

DATA_BOOST_ENABLED

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

AUTO_PARTITION_MODE

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

RUN PARTITIONED QUERY

PARTITION <SQL>

▶ 示例：对查询进行分区（点击可展开）

RUN PARTITION 'partition-token'

MAX_PARTITIONED_PARALLELISM

定向读取语句

Savepoint 命令

SAVEPOINT_SUPPORT

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

后续步骤

JDBC 会话管理命令 (GoogleSQL)