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

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

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

注意： 您只能搭配 Spanner JDBC 驅動程式使用工作階段管理陳述式。工作階段管理陳述式無法在用戶端程式庫、Google Cloud CLI 或 Simba 建立的 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

SET TRANSACTION { READ ONLY | READ WRITE }

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

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

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

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

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

SET SESSION CHARACTERISTICS

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 陳述式。執行 RUN BATCH 時，系統會在本機緩衝 DDL 陳述式，並以一批次的形式傳送至 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 長，因為它只適用於匯出或掃描整個資料庫等大量作業。

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

您可以使用 SET SPANNER.DATA_BOOST_ENABLED 陳述式，在目前連線中啟用 Data Boost。

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 }

設定此連線是否應使用 Data Boost 進行分割查詢。

預設為 false。

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

以下範例說明如何搭配使用 Data Boost 和 Spanner JDBC 驅動程式執行查詢。

-- 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 驅動程式用來執行區隔作業的 worker 執行緒數量。這個值用於：

• 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 方言資料庫。