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;

AUTOCOMMIT

布林值，指出連線是否處於自動提交模式。預設值為 true。

NOTE：使用 PGAdapter 的 PostgreSQL 驅動程式時，通常不需要修改這個變數的值。這些驅動程式會在必要時執行 BEGIN 和 COMMIT，自動為您管理交易。使用 psql 等指令列工具時，您可以關閉 autocommit，避免系統自動提交資料修改作業。

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

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 陳述式做為分區更新陳述式執行。分割更新陳述式可以做為一系列交易執行，每筆交易涵蓋受影響的列子集。分割陳述式會提供弱化的語意，以換取更佳的擴充性和效能。

預設為 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 }' }

唯讀陳舊值會套用至所有後續唯讀交易，以及 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_STALENESS 和 EXACT_STALENESS 值時，支援的時間單位如下：

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

只有在沒有進行中的交易時，才能修改這項屬性的值。

注意： 您只能在 AUTOCOMMIT 模式下，對查詢使用 MIN_READ_TIMESTAMP 和 MAX_STALENESS 值。

▶ 範例：唯讀陳舊 (按一下即可展開)

以下範例說明如何使用 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 類型的屬性，指出這個連線使用的目前最佳化工具統計資料套件。

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 修訂的最後一筆讀寫交易的修訂時間戳記。只有在您提交讀寫交易後，以及執行任何後續的 SELECT、DML 或結構定義變更陳述式之前，執行這項陳述式時，才會傳回時間戳記。否則結果為 NULL。

▶ 範例：修訂時間戳記 (按一下即可展開)

以下範例說明如何使用 PGAdapter 查看寫入作業的最後一次提交時間戳記。

-- 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 時，才能取得變動計數。

▶ 範例：提交回應 (按一下即可展開)

以下範例說明如何使用 PGAdapter 查看寫入作業的最後一次提交回應。

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

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

開始新的交易。TRANSACTION 和 WORK 關鍵字為選用項目，兩者等效且無效。

• 使用 COMMIT 或 ROLLBACK 終止交易。
• 如果已啟用AUTOCOMMIT 模式，這項陳述式會暫時將連線移出 AUTOCOMMIT 模式。交易結束時，連線會返回 AUTOCOMMIT 模式。
• 如未指定 READ ONLY 或 READ WRITE，交易模式會由工作階段的預設交易模式決定。這項預設值是使用 SET SESSION CHARACTERISTICS AS TRANSACTION 指令設定。

只有在沒有進行中的交易時，才能執行這項陳述式。

▶ 範例：BEGIN 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]

COMMIT [TRANSACTION | WORK]

修訂目前的交易。關鍵字 TRANSACTION 和 WORK 是選用項目，兩者等效，不會產生任何影響。

• 提交讀寫交易後，其他交易就能看到這項交易的所有更新，且系統會釋放交易在 Spanner 上的所有鎖定。
• 提交唯讀交易會結束目前的唯讀交易。 後續任何陳述式都會啟動新交易。對於唯讀交易，COMMIT 和 ROLLBACK 之間沒有語意差異。

只有在有效交易期間，才能執行這項陳述式。

▶ 範例：COMMIT TRANSACTION (按一下即可展開)

以下範例說明如何使用 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。關鍵字 TRANSACTION 和 WORK 是選用項目，兩者等效，且沒有任何作用。

• 執行讀寫交易的 ROLLBACK 會清除所有緩衝的突變，在 Spanner 上復原交易，並釋放交易持有的所有鎖定。
• 執行唯讀交易的 ROLLBACK 會結束目前的唯讀交易。後續任何陳述式都會啟動新的交易。 在連線的唯讀交易中，COMMIT 和 ROLLBACK 的語意沒有差異。

只有在有效交易期間，才能執行這項陳述式。

▶ 範例：ROLLBACK TRANSACTION (按一下即可展開)

以下範例說明如何使用 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 { READ ONLY | READ WRITE }

設定目前交易的交易模式。

只有在 AUTOCOMMIT 為 false 時，或您已執行 BEGIN [TRANSACTION | WORK] 啟動交易，但尚未在交易中執行任何陳述式時，才能執行這項陳述式。

這項陳述式只會為目前的交易設定交易模式。交易提交或回滾時，下一個交易會使用連線的預設模式。(請參閱SET SESSION CHARACTERISTICS)。

注意： 如果連線處於 READ ONLY 模式，就無法將交易模式設為 READ WRITE。

▶ 範例：設定交易 (按一下即可展開)

以下範例說明如何使用 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 ONLY 或 READ 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 執行 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 (
  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

將目前 DDL 批次中的所有緩衝 DDL 陳述式傳送至資料庫，等待 Spanner 執行這些陳述式，並結束目前的 DDL 批次。

如果 Spanner 無法執行至少一個 DDL 陳述式，RUN BATCH會針對 Spanner 無法執行的第一個 DDL 陳述式傳回錯誤。否則，RUN BATCH 會順利傳回。

注意： 如果批次中的 DDL 陳述式傳回錯誤，Spanner 可能仍會將同一批次中先前的 DDL 陳述式套用至資料庫。

ABORT BATCH

清除目前 DDL 批次中的所有緩衝 DDL 陳述式，並結束批次。

只有在 DDL 批次處於啟用狀態時，您才能執行這項陳述式。無論批次是否已緩衝處理 DDL 陳述式，您都可以使用 ABORT BATCH。系統會中止批次中所有先前的 DDL 陳述式。

▶ 範例：中止 DDL 批次 (按一下即可展開)

以下範例說明如何使用 PGAdapter 中止 DDL 批次。

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

Savepoint 指令

PGAdapter 中的儲存點會經過模擬。回溯至儲存點會回溯整個交易，並重試交易，直到設定儲存點為止。如果交易在儲存點之前使用的基礎資料已變更，這項作業就會失敗並傳回 AbortedDueToConcurrentModificationException 錯誤。

啟用存檔點支援功能後，建立及發布存檔點一律會成功。

下列陳述式可在交易中啟用及停用模擬儲存點。

SPANNER.SAVEPOINT_SUPPORT

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

類型為 STRING 的屬性，表示目前的 SAVEPOINT_SUPPORT 設定。可能的值包括：

• DISABLED：所有儲存點指令都會停用，且無法執行。
• FAIL_AFTER_ROLLBACK：已啟用儲存點指令。復原至儲存點會復原整筆交易。如果回溯至儲存點後嘗試使用交易，作業就會失敗。
• ENABLED：所有儲存點指令都會啟用。復原至儲存點會復原交易，並對儲存點執行重試。如果交易在儲存點之前使用的基礎資料已變更，這項作業就會失敗並顯示 AbortedDueToConcurrentModificationException 錯誤。

預設值為 ENABLED。

只有在沒有進行中的交易時，才能執行這項陳述式。

SAVEPOINT savepoint_name

SAVEPOINT savepoint-name;

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;

ROLLBACK TO savepoint_name

ROLLBACK TO savepoint_name

將目前交易回溯至具有指定名稱的儲存點。

在所有情況下，我們無法保證都能成功復原至儲存點。 復原至儲存點會復原整個交易，並重試交易，直到設定儲存點為止。如果交易在儲存點之前使用的基礎資料已變更，這項作業就會失敗並傳回 AbortedDueToConcurrentModificationException。

RELEASE [SAVEPOINT] savepoint_name

RELEASE savepoint_name

從目前的交易中移除儲存點。無法再用來執行 ROLLBACK TO savepoint_name 陳述式。

預先準備的陳述式

下列陳述式會建立及執行預先準備的陳述式。

準備

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

準備這個連線的陳述式。Spanner 會剖析及驗證陳述式，並將其儲存在 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

DEALLOCATE statement_name

從這個連線中移除預先準備好的陳述式。

複製

PGAdapter 支援部分 PostgreSQL COPY 指令。

COPY table_name FROM STDIN

COPY table_name FROM STDIN [BINARY]

將資料從「stdin」複製到 Spanner。相較於執行 INSERT 陳述式，使用 COPY 將大型資料集匯入 Spanner 的效率更高。

COPY 可與 SPANNER.AUTOCOMMIT_DML_MODE 結合，執行非不可拆分的交易。這樣一來，交易就能執行的變動次數，就會超出標準交易變動次數上限。

▶ 範例：複製 (點選即可展開)

下列範例說明如何使用 PGAdapter 將資料複製到 Spanner，以及從 Spanner 複製資料。

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 支援」。

COPY table_name TO STDOUT [BINARY]

COPY table_name TO STDOUT [BINARY]

將資料表或查詢中的資料複製到 stdout。

Data Boost 和分區查詢陳述式

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 執行查詢 (按一下即可展開)

以下範例說明如何使用 PGAdapter，透過 Data Boost 執行查詢。

-- 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。
• 如要讓連線對所有查詢使用 Data Boost，請將 SPANNER.DATA_BOOST_ENABLED 設為 true。

預設為 false。

▶ 範例：執行 (按一下即可展開)

這個範例使用 Data Boost，透過 PGAdapter 執行兩項查詢

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，以便使用 Data Boost 執行查詢：

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

PGAdapter 會在內部將查詢分區，並平行執行分區。結果會合併為一個結果集，並傳回應用程式。您可以使用 SPANNER.MAX_PARTITIONED_PARALLELISM 變數，設定執行分區的工作站執行緒數量。

PARTITION <SQL>

PARTITION <sql>

建立要對 Spanner 執行查詢的分區清單，並傳回這些分區權杖清單。每個分割區權杖都可使用 RUN PARTITION 'partition-token' 指令，在相同或另一個 PGAdapter 執行個體的個別連線上執行。

▶ 範例：分割區查詢 (按一下即可展開)

下列範例說明如何分割查詢，然後使用 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 'partition-token'

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。

後續步驟

• 進一步瞭解如何啟動 PGAdapter。
• 如要查看支援的 PostgreSQL 驅動程式和 ORM 完整清單，請參閱這篇文章。