PGAdapter 会话管理命令

Spanner PGAdapter 支持会话管理语句, 让您能够修改连接的状态和行为, 事务,并高效地执行批量语句。存在以下情况的所有声明: 都可以用于任何客户端或驱动程序, 会连接到 PGAdapter。

如需了解详情,请参阅支持的 PostgreSQL 驱动程序的完整列表 和 ORM。通过 以下命令适用于 PostgreSQL 方言数据库。

如需详细了解如何使用 PGAdapter,请参阅启动 PGAdapter

连接语句

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

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 first_name, last_name
FROM singers
ORDER BY last_name;

SELECT first_name, last_name
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 will
-- start a new read-only transaction.
COMMIT;

自动提交

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

注意:在以下情况下,您通常无需修改此变量的值: 将 PostgreSQL 驱动程序与 PGAdapter 结合使用。这些司机 通过执行 BEGINCOMMIT 自动为您管理交易 。您可以在使用如下命令行工具时关闭 autocommit: psql 以防止提交意外的数据修改 。

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

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

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

▶ 示例:自动提交(点击即可展开)
。 以下示例展示了如何使用 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 | WORK])及之前 事务内执行任何语句。

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

此设置默认为启用状态。如果您有以下需求,我们建议您关闭此设置: 您的应用已经重试被中止的事务。

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(点击即可展开)
。 以下示例展示了如何执行 使用 PGAdapter 的分区 DML

-- 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 表示未设置超时值。如果 语句超时值已设置,处理时间超过 指定的超时值会导致超时错误并使 交易。

受支持的时间单位包括:

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

DEFAULT 为 0 秒,表示没有超时。不含int8 单位表示 int8 ms。例如,以下命令同时设置了 语句超时设置为 2 秒。

SET STATEMENT_TIMEOUT TO 2000;
SET STATEMENT_TIMEOUT TO '2s';

事务期间的语句超时会使事务失效, 已失效事务中的后续语句(ROLLBACK 除外)会失败。

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]D [[H]H:[M]M:[S]S[.DDDDDD]][timezone]

设置 MAX_STALENESSEXACT_STALENESS 值所支持的时间单位包括:

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

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

▶ 示例:只读过时(点击即可展开)
。 以下示例展示了如何使用自定义过时执行查询 与 PGAdapter 结合使用。

-- 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 will return results that are up to
-- 10 seconds stale.
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is however 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 first_name, last_name
FROM singers
ORDER BY last_name;

SELECT title, singer_id
FROM albums
ORDER BY title;

COMMIT;

-- Read staleness can also be an exact timestamp.
SET SPANNER.READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.OPTIMIZER_VERSION

STRING 类型的属性,用于指示 优化器版本。版本为 数字或“LATEST”。

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

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

默认值为 ''

▶ 示例:优化工具版本(点击即可展开)
。 以下示例展示了如何使用 优化器版本, PGAdapter 结合使用。

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.OPTIMIZER_STATISTICS_PACKAGE

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

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

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

默认值为 ''

▶ 示例:优化工具统计信息包(点击展开)
。 以下示例展示了如何使用 优化器统计信息软件包,其中包含 PGAdapter 结合使用。

-- 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 first_name, last_name
FROM singers
ORDER BY last_name;

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.RETURN_COMMIT_STATS

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

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

默认值为 false

▶ 示例:提交统计信息(点击展开)
。 以下示例展示了如何查看事务的提交统计信息 与 PGAdapter 结合使用。

-- 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 {TO|=} {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

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

默认值为 'NULL'

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

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

如需了解详情,请参阅 Priority

事务语句

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

交易隔离级别

SHOW [ VARIABLE ] TRANSACTION ISOLATION LEVEL

返回一个结果集,其中包含 STRING 类型的一行和一列。通过 返回的值始终为 serializable,因为这是唯一受支持的值 Spanner PostgreSQL 方言数据库的隔离级别。

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

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

▶ 示例:阅读时间戳(点击即可展开)
。 以下示例展示了如何查看 使用 PGAdapter 进行的只读操作。

-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows 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 first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows 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 first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows 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 上次读写事务的提交时间戳 投入。只有当您在提交读写事务之后、执行任何后续 SELECTDML 或架构更改语句之前执行此语句时,此语句才会返回时间戳。否则,结果为 NULL

▶ 示例:提交时间戳(点击即可展开)
。 以下示例展示了如何查看 读写操作。

-- 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=int8) 表示其中应用的变更数量 已提交的事务。在 模拟器。

只有当 SET RETURN_COMMIT_STATS 为 设置为 true

▶ 示例:提交响应(点击即可展开)
。 以下示例展示了如何查看 读写操作。

-- 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 }]

启动新事务。关键字 TRANSACTIONWORK 是可选的, 等效,没有任何作用。

  • 使用 COMMITROLLBACK 终止事务。
  • 如果您启用了 AUTOCOMMIT 模式,则此语句会暂时将连接退出 AUTOCOMMIT 模式。当事务结束时,连接将返回 AUTOCOMMIT 模式。
  • 如果未指定 READ ONLYREAD WRITE,则事务模式为 取决于会话的默认事务模式。默认值为 使用 SET SESSION CHARACTERISTICS AS TRANSACTION 命令进行设置。

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

▶ 示例:开始交易(点击即可展开)
。 以下示例展示了如何使用以下代码启动不同类型的事务: PGAdapter 结合使用。

-- This starts a transaction using the current defaults of this connection.
-- The value of SPANNER.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 SPANNER.READONLY to TRUE to use read-only transactions by default.
SET SPANNER.READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

-- Use the 'READ WRITE' or 'READ ONLY' qualifier in the BEGIN statement to
-- override the current default of the connection.
SET SPANNER.READONLY=FALSE;
BEGIN READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

提交 [交易 |单位]

COMMIT [TRANSACTION | WORK]

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

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

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

▶ 示例:提交交易(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

-- 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 PGAdapter in order to mark the
-- end of the transaction.
BEGIN READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

回滚 [交易 |单位]

ROLLBACK [TRANSACTION | WORK]

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

  • 对读写事务执行 ROLLBACK 会清除所有已缓冲的数据 在 Spanner 上回滚事务,并释放任何 锁定持有的事务。
  • 对只读事务执行 ROLLBACK 会结束当前的只读事务。任何后续语句都会启动新事务。对于连接上的只读事务,COMMITROLLBACK 之间没有语义差异。

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

▶ 示例:回滚交易(点击即可展开)
。 以下示例展示了如何使用如下命令 PGAdapter 结合使用。

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

-- Read-only transactions also need to be either committed or rolled back in
-- PGAdapter 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 first_name, last_name
FROM singers
ORDER BY last_name;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

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

只有在 AUTOCOMMITfalse 时才能执行此语句,或者 如果您是通过执行以下命令来启动事务: BEGIN [TRANSACTION | WORK] 尚未在事务中执行任何语句。

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

▶ 示例:设置交易(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- 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 ONLYREAD WRITE。仅当 有效交易。

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

▶ 示例:设置会话特征(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

-- Set the default transaction mode to read-only.
SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;

-- This will now start a read-only transaction.
BEGIN;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

-- You can override the default transaction mode with the SET TRANSACTION
-- statement.
SET SESSION CHARACTERISTICS AS TRANSACTION READ WRITE;
BEGIN;
SET TRANSACTION READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

SPANNER.STATEMENT_TAG

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

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

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

默认值为 ''

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

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

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

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

▶ 示例:语句代码(点击展开)
。 以下示例展示了如何使用以下代码设置语句标记: PGAdapter 结合使用。

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

-- 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 track_number, title
FROM tracks
WHERE album_id=1 AND singer_id=1
ORDER BY track_number;

SPANNER.TRANSACTION_TAG

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

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

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

默认值为 ''

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

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

▶ 示例:交易代码(点击展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

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 first_name, last_name
FROM singers
ORDER BY last_name;

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

批量语句

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

START BATCH DDL

START BATCH DDL

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

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

▶ 示例:DDL 批次(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

-- 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 (
  id bigint primary key,
  first_name varchar,
  last_name varchar
);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE albums (
  id bigint primary key,
  title varchar,
  singer_id bigint,
  constraint fk_albums_singers foreign key (singer_id) references singers (id)
);

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

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

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

▶ 示例:中止 DDL 批次(点击即可展开)
。 以下示例展示了如何使用以下命令中止 DDL 批次 PGAdapter 结合使用。

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

-- The following statements are buffered locally.
CREATE TABLE singers (
  id bigint primary key,
  first_name varchar,
  last_name varchar
);
CREATE TABLE albums (
  id bigint primary key,
  title varchar,
  singer_id bigint,
  constraint fk_albums_singers foreign key (singer_id) references singers (id)
);

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

START 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 批次(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

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

Savepoint 命令

模拟的是 PGAdapter 中的 Savepoint。回滚到保存点数 备份整个事务,并重试该事务,直到保存点 已设置。此操作将失败,并显示 AbortedDueToConcurrentModificationException 错误。 直到保存点更改为止。

支持 Savepoint 的情况下,始终能成功创建和释放 Savepoint 。

以下语句用于在事务中启用和停用模拟的 Savepoint。

SPANNER.SAVEPOINT_SUPPORT

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

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

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

默认值为 ENABLED

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

SAVEPOINT 保存点名称

SAVEPOINT savepoint-name;

SAVEPOINT 会在当前事务中创建新的 Savepoint。 事务可以回滚到保存点,以撤消 自保存点创建后已执行完毕。

▶ 示例:Savepoint(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

-- Start a transaction and execute an insert statement.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);

-- Set a savepoint and then execute another insert statement.
SAVEPOINT one_row_inserted;
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);

-- Roll back to the savepoint. This will undo all statements that have been
-- executed after the savepoint.
ROLLBACK TO one_row_inserted;

-- This only commits the first insert statement.
COMMIT;

回滚到 Savepoint_name

ROLLBACK TO savepoint_name

将当前事务回滚到具有指定名称的 Savepoint。

无法保证在所有情况下回滚到 Savepoint 都成功。 回滚到 Savepoint 会回滚整个事务并重试 保存节点之前的位置此操作将失败,并显示 AbortedDueToConcurrentModificationException如果基础数据具有 保存时间点之前,事务所使用的任何 ID 都已发生更改。

释放 [SAVEPOINT] 保存点名称

RELEASE savepoint_name

从当前事务中移除 Savepoint。它无法再用于 执行 ROLLBACK TO savepoint_name 语句。

准备好的语句

以下语句用于创建和执行准备好的语句。

准备

PREPARE statement_name [(data_type, ...)] AS statement

准备关于此连接的语句。解析并验证了语句 并存储在内存中的 PGAdapter 中。

▶ 示例:预备语句(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

-- Create a prepared statement that can be used to insert a single row.
PREPARE insert_t AS INSERT INTO T (id, col_a, col_b) VALUES ($1, $2, $3);

-- The prepared statement can be used to insert rows both in autocommit, in a
-- transaction, and in DML batches.

-- Execute in autocommit.
EXECUTE insert_t (1, 100, 1);

-- Execute in transaction.
BEGIN;
EXECUTE insert_t (2, 200, 2);
EXECUTE insert_t (3, 300, 3);
COMMIT;

-- Execute in a DML batch.
START BATCH DML;
EXECUTE insert_t (4, 400, 4);
EXECUTE insert_t (5, 500, 5);
RUN BATCH;

-- Prepared statements can be removed with the DEALLOCATE command.
DEALLOCATE insert_t;

执行

EXECUTE statement_name [(value, ...)]

通过 PREPARE 执行在此连接上创建的语句。

▶ 示例:执行(点击即可展开)
。 以下示例展示了如何使用 PGAdapter 结合使用。

-- Create a prepared statement.
PREPARE my_statement AS insert into my_table (id, value) values ($1, $2);

-- Execute the statement twice with different parameter values.
EXECUTE my_statement (1, 'One');
EXECUTE my_statement (2, 'Two');

取消分配

DEALLOCATE statement_name

从此连接中移除准备好的语句。

复制

PGAdapter 支持 PostgreSQL COPY 命令的子集。

从 STDIN 复制表名称

COPY table_name FROM STDIN [BINARY]

将数据从 stdin 复制到 Spanner。更为高效地使用 COPY:用于将大型数据集导入 Spanner,而不是执行 INSERT 语句。

COPY 可与 SPANNER.AUTOCOMMIT_DML_MODE 结合使用以执行 非原子事务。这允许事务执行更多变更 超过标准事务变更限制。

▶ 示例:复制(点击即可展开)
。 以下示例展示了如何将数据复制到 将 Spanner 与 PGAdapter 结合使用。

create table numbers (number bigint not null primary key, name varchar);

执行原子 COPY 操作:

cat numbers.txt | psql -h /tmp -d test-db -c "copy numbers from stdin;"

执行非原子 COPY 操作:

cat numbers.txt | psql -h /tmp -d test-db \
  -c "set spanner.autocommit_dml_mode='partitioned_non_atomic'; copy numbers from stdin;"

将数据从 PostgreSQL 复制到 Spanner:

psql -h localhost -p 5432 -d my-local-db \
  -c "copy (select i, to_char(i, 'fm000') from generate_series(1, 1000000) s(i)) to stdout binary" \
  | psql -h localhost -p 5433 -d my-spanner-db \
  -c "set spanner.autocommit_dml_mode='partitioned_non_atomic'; copy numbers from stdin binary;"

此示例假定 PostgreSQL 在端口 5432 上运行, PGAdapter 在端口 5433 上运行。

如需查看更多示例,请参阅 PGAdapter - COPY 支持

将 table_name 复制到 STDOUT [BINARY]

COPY table_name TO STDOUT [BINARY]

将表中的数据或查询中的数据复制到 stdout

Data Boost 和分区查询语句

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

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

PGAdapter 支持三种替代方案来执行分区查询:

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

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

SPANNER.DATA_BOOST_ENABLED

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

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

默认值为 false

▶ 示例:使用 Data Boost 执行查询(点击即可展开)
。 以下示例展示了如何使用 Data Boost 和 PGAdapter 结合使用。

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

SPANNER.AUTO_PARTITION_MODE

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

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

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

默认值为 false

▶ 示例:执行(点击即可展开)
。 此示例使用 数据提升

SET SPANNER.AUTO_PARTITION_MODE = true
SET SPANNER.DATA_BOOST_ENABLED = true
SELECT first_name, last_name FROM singers
SELECT singer_id, title FROM albums

运行分区查询

RUN PARTITIONED QUERY <sql>

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

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

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

分区 <SQL>

PARTITION <sql>

创建分区列表以对 Spanner 执行查询 并返回分区令牌列表。每个分区令牌都可以 在同一 PGAdapter 上的单独连接上执行 使用 RUN PARTITION 'partition-token' 命令创建实例。

▶ 示例:分区查询(点击展开)
。 以下示例展示了如何对查询进行分区,然后分别执行 分别使用 PGAdapter 进行分区。

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

RUN PARTITION '分区令牌'

RUN PARTITION 'partition-token'

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

SPANNER.MAX_PARTITIONED_PARALLELISM

bigint 类型的属性,表示工作器线程的数量 PGAdapter 用于执行分区。此值用于:

  • SPANNER.AUTO_PARTITION_MODE = true
  • RUN PARTITIONED QUERY sql
SHOW SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM {TO|=} <bigint>

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

默认值为 0

后续步骤