JDBC 工作階段管理指令 (PostgreSQL)

Spanner JDBC 驅動程式 (Java 資料庫連線) 支援工作階段管理陳述式，可讓您修改連線狀態、執行交易，以及有效率地執行批次陳述式。

下列指令適用於 PostgreSQL 方言資料庫。

注意： 您只能搭配 Spanner JDBC 驅動程式使用工作階段管理陳述式。Simba 建立的用戶端程式庫、Google Cloud CLI 或 JDBC 驅動程式，無法使用工作階段管理陳述式。

連線陳述式

下列陳述式會變更或顯示目前連線的屬性。

SPANNER.READONLY

布林值，指出連線是否處於唯讀模式。預設值為 false。

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

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

▶ 範例：唯讀交易 (按一下即可展開)

以下範例說明如何使用這項屬性，在 Spanner 中執行唯讀交易。

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

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

SELECT Title
FROM Albums
ORDER BY Title;

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

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

AUTOCOMMIT

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

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

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

如果 AUTOCOMMIT 設為 false，執行 COMMIT 或 ROLLBACK 後，系統會自動啟動新的交易。您執行的第一個陳述式會啟動交易。

▶ 範例：自動提交 (按一下即可展開)

以下範例說明如何使用 autocommit 屬性。

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

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

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

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

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

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

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

SPANNER.RETRY_ABORTS_INTERNALLY

布林值，指出連線是否會自動重試已中止的交易。預設為 true。

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

只有在交易開始後 (請參閱BEGIN TRANSACTION)，且交易中執行任何陳述式之前，您才能變更這項屬性的值。

將 SPANNER.RETRY_ABORTS_INTERNALLY 設為 true 時，連線會保留連線傳回給用戶端應用程式的所有資料的總和檢查碼。如果交易遭 Spanner 中止，可使用這項功能重試交易。

預設值為 true。如果應用程式已重試已中止的交易，建議將此值設為 false。

SPANNER.AUTOCOMMIT_DML_MODE

STRING 屬性，指出資料操縱語言 (DML) 陳述式的自動提交模式。

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

可能的值為：

• 在 TRANSACTIONAL 模式下，驅動程式會將 DML 陳述式做為個別的不可分割交易執行。驅動程式會建立新交易、執行 DML 陳述式，並在執行成功時修訂交易，或在發生錯誤時復原交易。
• 在 PARTITIONED_NON_ATOMIC 模式下，驅動程式會將 DML 陳述式做為分區更新陳述式執行。分區更新陳述式可以做為一系列交易執行，每筆交易涵蓋受影響的資料列子集。分割陳述式會提供弱化的語意，以換取更佳的擴充性和效能。

預設為 TRANSACTIONAL。

▶ 範例：分區 DML (按一下即可展開)

下列範例說明如何使用 Spanner JDBC 驅動程式執行分割 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 表示 0 秒，相當於沒有逾時。如果 int8 數字沒有單位，則表示毫秒。如果已設定陳述式逾時值，超過指定逾時值的陳述式會導致 java.sql.SQLTimeoutException 錯誤，並使交易失效。

支援的時間單位如下：

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

預設值為 0，表示沒有逾時。

交易期間的陳述式逾時會導致交易失效，失效交易中的所有後續陳述式 (ROLLBACK 除外) 都會失敗，且 Spanner JDBC 驅動程式會擲回 java.sql.SQLTimeoutException。

SPANNER.READ_ONLY_STALENESS

STRING 類型的屬性，表示 Spanner 在 AUTOCOMMIT 模式下用於唯讀交易和查詢的唯讀過時設定。

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

staleness_type:

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

唯讀陳舊值會套用至所有後續唯讀交易，以及 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：奈秒

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

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

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

以下範例說明如何使用 Spanner JDBC 驅動程式，透過自訂陳舊值執行查詢。

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

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title, SingerId
FROM Albums
ORDER BY Title;

COMMIT;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_VERSION

類型為 STRING 的屬性，表示最佳化工具版本。版本可以是整數或 'LATEST'。

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

設定連線中所有後續陳述式要使用的最佳化工具版本。如果最佳化工具版本設為 '' (空字串)，Spanner 會使用最新版本。如果未設定最佳化工具版本，Spanner 會使用資料庫層級設定的最佳化工具版本。

預設為 ''。

▶ 範例：最佳化工具版本 (按一下即可展開)

以下範例說明如何使用 Spanner JDBC 驅動程式，透過特定最佳化工具版本執行查詢。

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_STATISTICS_PACKAGE

STRING 類型的屬性，指出這個連線目前使用的最佳化工具統計資料套件。

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

設定最佳化工具統計資料套件，供連線上的所有後續陳述式使用。<package> 必須是有效的套件名稱。如未設定最佳化工具統計資料套件，Spanner 會使用資料庫層級設定的最佳化工具統計資料套件。

預設為 ''。

▶ 範例：最佳化工具統計資料套件 (按一下即可展開)

以下範例說明如何使用 Spanner JDBC 驅動程式，透過特定最佳化工具統計資料套件執行查詢。

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.RETURN_COMMIT_STATS

類型為 BOOL 的屬性，指出是否應傳回此連線交易的統計資料。執行 SHOW SPANNER.COMMIT_RESPONSE 指令即可查看傳回的統計資料。

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

預設為 false。

▶ 範例：提交統計資料 (按一下即可展開)

以下範例說明如何使用 Spanner JDBC 驅動程式，查看交易的提交統計資料。

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

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

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

SPANNER.RPC_PRIORITY

類型為 STRING 的屬性，表示 Spanner 要求的相對優先順序。優先順序會做為 Spanner 排程器的提示，但無法保證執行順序。

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

'NULL' 表示要求中不應包含任何提示。

預設為 'NULL'。

您也可以使用陳述式提示指定 RPC 優先順序：

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

詳情請參閱「Priority」。

標記

下列陳述式會管理要求和交易標記。

SPANNER.STATEMENT_TAG

類型為 STRING 的屬性，其中包含下一個陳述式的要求標記。

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

為下一個要執行的陳述式設定要求標記。每個陳述式只能設定一個標記。標記不會跨越多個陳述式，必須以陳述式為單位設定。如要移除要求標記，請將其設為空字串 ('')。

預設為 ''。

您可以為同一份對帳單設定交易代碼和對帳單代碼。

您也可以使用陳述式提示新增陳述式標記：

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

詳情請參閱「解決要求標記和交易標記問題」。

▶ 範例：陳述式標記 (點選即可展開)

以下範例說明如何使用 Spanner JDBC 驅動程式設定陳述式標記。

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

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

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

SPANNER.TRANSACTION_TAG

類型為 STRING 的屬性，內含下一個交易的交易標記。

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

為要執行的目前交易設定交易標記。每筆交易只能設定一個標記。代碼不會跨越多筆交易，必須針對每筆交易設定。將交易代碼設為空字串 ('')，即可移除交易代碼。交易代碼必須在交易中執行任何陳述式之前設定。

預設為 ''。

您可以為同一份對帳單設定交易代碼和對帳單代碼。

詳情請參閱「解決要求標記和交易標記問題」。

▶ 範例：交易標記 (按一下即可展開)

以下範例說明如何使用 Spanner JDBC 驅動程式設定交易標記。

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

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

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

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

COMMIT;

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

交易對帳單

下列陳述式會管理及提交 Spanner 交易。

交易隔離等級

SHOW [VARIABLE] TRANSACTION ISOLATION LEVEL

傳回結果集，其中包含一個資料列和一個 STRING 類型的資料欄。傳回值一律為 serializable。

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

傳回結果集，其中包含一個資料列和一個 TIMESTAMP 型別的資料欄，內含最近一次唯讀交易的讀取時間戳記。只有在唯讀交易仍處於有效狀態且已執行至少一項查詢，或是在唯讀交易提交後且新交易開始前，這項陳述式才會傳回時間戳記。否則結果為 NULL。

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

以下範例說明如何使用 Spanner JDBC 驅動程式，查看唯讀作業的上次讀取時間戳記。

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

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT Title
FROM Albums
ORDER BY Title;

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

COMMIT;

SPANNER.COMMIT_TIMESTAMP

SHOW [VARIABLE] SPANNER.COMMIT_TIMESTAMP

傳回結果集，其中包含一個資料列和一個 TIMESTAMP 類型的資料欄，內含 Spanner 認可的最後一筆讀寫交易的認可時間戳記。只有在您提交讀寫交易後，以及執行任何後續的 SELECT、DML 或結構定義變更陳述式之前，執行這項陳述式時，才會傳回時間戳記。否則結果為 NULL。

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

以下範例說明如何使用 Spanner JDBC 驅動程式，查看寫入作業的最後修訂時間戳記。

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

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

SPANNER.COMMIT_RESPONSE

SHOW [VARIABLE] SPANNER.COMMIT_RESPONSE

傳回的結果集包含一列和兩欄：

• COMMIT_TIMESTAMP (type=TIMESTAMP) 指出最近一次交易的提交時間。
• MUTATION_COUNT (type=INT64) 表示在已提交的交易中套用了多少變異。在模擬器上執行時，這個值一律為空白。

只有在交易提交前將 SET SPANNER.RETURN_COMMIT_STATS 設為 true 時，才能取得突變計數。

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

以下範例說明如何使用 Spanner JDBC 驅動程式，查看寫入作業的最後一次提交回應。

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

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

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

{ START | BEGIN } [ TRANSACTION | WORK ]

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

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

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

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

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

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

COMMIT [TRANSACTION | WORK]

COMMIT [ TRANSACTION | WORK ]

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

• 提交讀寫交易後，這項交易的所有更新都會對其他交易顯示，並釋放交易在 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 READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

{ ABORT | ROLLBACK } [TRANSACTION | WORK]

{ ABORT | ROLLBACK } [TRANSACTION | WORK]

執行目前交易的 ROLLBACK。關鍵字 TRANSACTION 和 WORK 是選用項目，兩者等效，且沒有任何作用。

• 執行讀寫交易的 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 READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

設定交易

SET TRANSACTION { READ ONLY | READ WRITE }

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

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

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

注意： 如果連線處於 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;

設定工作階段特徵

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

將工作階段中交易的預設交易模式設為 READ ONLY 或 READ WRITE。只有在沒有進行中的交易時，才允許使用這項陳述式。

SET TRANSACTION 指令可以覆寫這項設定。

批次陳述式

下列陳述式會管理 DDL 陳述式批次，並將這些批次傳送至 Spanner。

START BATCH DDL

START BATCH DDL

在連線上啟動批次 DDL 陳述式。批次中的所有後續陳述式都必須是 DDL 陳述式。DDL 陳述式會在本地緩衝處理，並在您執行 RUN BATCH 時，以單一批次的形式傳送至 Spanner。以單一批次執行多個 DDL 陳述式，通常比個別執行陳述式更快。

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

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

以下範例說明如何使用 Spanner JDBC 驅動程式執行 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  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

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

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

執行批次

RUN BATCH

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

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

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

ABORT BATCH

ABORT BATCH

清除目前 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  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

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

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

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 長，因為這項 API 僅適用於大量作業，例如匯出或掃描整個資料庫。

Spanner 適用的 Data Boost 可讓您執行分析查詢和資料匯出作業，對已佈建 Spanner 執行個體的現有工作負載幾乎沒有影響。Data Boost 僅支援分區查詢。

您可以使用 SET SPANNER.DATA_BOOST_ENABLED 陳述式，在目前的連線中啟用資料加速功能。

JDBC 驅動程式支援三種執行分割查詢的替代方案：

• SET SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql 後方附加多個 RUN PARTITION 'partition-token'

以下各節將說明這些方法。

SPANNER.DATA_BOOST_ENABLED

BOOL 類型的屬性，指出這個連線是否應針對已分割的查詢使用 Data Boost。預設值為 false。

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

設定這個連線是否應使用資料加速進行分割查詢。

預設為 false。

▶ 範例：使用 Data Boost 執行查詢 (按一下即可展開)

以下範例說明如何使用 Spanner JDBC 驅動程式，透過 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;

如需完整範例，請參閱 PostgreSQL DataBoostExample。

SPANNER.AUTO_PARTITION_MODE

類型為 BOOL 的屬性，指出連線是否會自動對執行的所有查詢使用分割查詢。

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

• 如要讓連線對所有執行的查詢使用分割查詢，請將這個變數設為 true。
• 如要讓連線對所有查詢使用 Data Boost，請將 SPANNER.DATA_BOOST_ENABLED 設為 true。

預設為 false。

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

這個範例會使用 Data Boost，透過 Spanner JDBC 驅動程式執行兩項查詢。

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

如需完整範例，請參閱 PostgreSQL AutoPartitionModeExample。

執行分區查詢

RUN PARTITIONED QUERY <sql>

在 Spanner 上以分區查詢的形式執行查詢。請確認 SPANNER.DATA_BOOST_ENABLED 已設為 true，以便使用 Data Boost 執行查詢：

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

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

如需完整範例，請參閱 PostgreSQL RunPartitionedQueryExample。

PARTITION <SQL>

PARTITION <sql>

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

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

以下範例說明如何分割查詢，然後使用 Spanner JDBC 驅動程式分別執行每個分割區。

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

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

如需完整範例，請參閱 PostgreSQL PartitionQueryExample。

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

執行先前由 PARTITION 指令傳回的查詢分割區。這個指令可在任何 JDBC 連線執行，只要連線的資料庫與建立分割區權杖的資料庫相同即可。

如需完整範例，請參閱 PostgreSQL PartitionQueryExample。

SPANNER.MAX_PARTITIONED_PARALLELISM

int8 類型的屬性，指出 Spanner JDBC 驅動程式用來執行分割區的工作站執行緒數量。這項值可用於：

• SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

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

設定 Spanner JDBC 驅動程式可用於執行分割區的工作站執行緒數量上限。將這個值設為 0，即可指示 Spanner JDBC 驅動程式將用戶端電腦上的 CPU 核心數設為上限。

預設值為 0。

儲存點指令

下列陳述式可在交易中啟用及停用模擬的儲存點。您可以呼叫 java.sql.Connection#setSavepoint() 方法來建立儲存點。

Spanner JDBC 驅動程式會模擬儲存點，以支援依賴這些儲存點進行巢狀交易的架構。系統會追蹤交易中陳述式傳回結果的執行總和檢查碼，藉此模擬儲存點。復原至儲存點時，Spanner JDBC 驅動程式會復原交易，然後重試交易，直到儲存點設定的位置為止。系統會比較重試的總和檢查碼與初始交易的總和檢查碼，確認傳回的結果相同。

SPANNER.SAVEPOINT_SUPPORT

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

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

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

預設值為 FAIL_AFTER_ROLLBACK。

只有在沒有進行中的交易時，您才能變更這個變數的值。

▶ 範例：儲存點支援 (按一下即可展開)

以下範例說明如何在 Spanner JDBC 驅動程式中啟用及停用儲存點支援。

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

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

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

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

後續步驟

瞭解如何將 JDBC 連線至 PostgreSQL 方言資料庫。