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
接続が autocommit モードかどうかを示すブール値。デフォルト値は true です。
注: 通常、PGAdapter で PostgreSQL ドライバを使用する場合、この変数の値を変更する必要はありません。これらのドライバは、必要に応じて BEGIN と COMMIT を実行することで、トランザクションを自動的に管理します。psql などのコマンドライン ツールを使用する場合は、autocommit をオフにして、誤ってデータが変更されて自動的に commit されるのを防ぐことができます。
SHOW [VARIABLE] AUTOCOMMIT
SET AUTOCOMMIT {TO|=} { true | false }
このプロパティの値を変更できるのは、アクティブなトランザクションが存在しない場合のみです。
AUTOCOMMIT が false に設定されている場合、COMMIT または ROLLBACK を実行すると、新しいトランザクションが自動的に開始されます。実行する最初のステートメントによって、トランザクションが開始されます。
▶ 例: 自動 commit（クリックして展開）
次の例は、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
データ操作言語（DML）ステートメントの自動 commit モードを示す STRING プロパティ。
SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }
使用できる値は次のとおりです。
TRANSACTIONALモードでは、ドライバが DML ステートメントを独立したアトミック トランザクションとして実行します。ドライバが新しいトランザクションを作成し、DML ステートメントが実行し、実行時にトランザクションを commit するか、エラーが発生した場合にトランザクションをロールバックします。PARTITIONED_NON_ATOMICモードでは、ドライバが DML ステートメントをパーティション化更新ステートメントとして実行します。パーティション化更新ステートメントは一連のトランザクションの 1 つとして実行でき、各トランザクションは影響を受ける行のサブセットをカバーします。パーティション化ステートメントは、スケーラビリティとパフォーマンスを向上させる代わりに、セマンティクスが緩和されます。
デフォルトは 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
AUTOCOMMIT モードで読み取り専用トランザクションとクエリに Spanner が使用する現在の読み取り専用のステイルネス設定を示す STRING 型のプロパティ。
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: ナノ秒
このプロパティの値を変更できるのは、アクティブなトランザクションがない場合に限られます。
▶ 例: 読み取り専用のステイルネス（クリックして拡大）
次の例は、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 です。
▶ 例: commit 統計情報（クリックして展開）
次の例は、PGAdapter を使用してトランザクションの commit 統計情報を表示する方法を示しています。
-- 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
Spanner リクエストの相対的な優先度を示す STRING 型のプロパティ。優先度は 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 トランザクションを管理して commit します。
TRANSACTION ISOLATION LEVEL
SHOW [ VARIABLE ] TRANSACTION ISOLATION LEVEL
STRING 型の 1 行と 1 列の結果セットを返します。返される値は常に serializable です。これは、Spanner PostgreSQL 言語データベースでサポートされている唯一の分離レベルであるためです。
SPANNER.READ_TIMESTAMP
SHOW [VARIABLE] SPANNER.READ_TIMESTAMP
最新の読み取り専用トランザクションの読み取りタイムスタンプが含まれる TIMESTAMP 型の 1 行と 1 列の結果セットを返します。このステートメントがタイムスタンプを返すのは、読み取り専用トランザクションがまだアクティブで、少なくとも 1 つのクエリを実行した場合、または読み取り専用トランザクションが commit されてから新しいトランザクションが開始されるまでの間のみです。それ以外の場合、結果は 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
Spanner が commit した最後に読み取り / 書き込みトランザクションの commit タイムスタンプが含まれる TIMESTAMP 型の 1 行と 1 列の結果セットを返します。このステートメントは、読み取り / 書き込みトランザクションを commit した後、後続の SELECT、DML、またはスキーマ変更ステートメントを実行する前にだけタイムスタンプを返します。それ以外の場合、結果は NULL です。
▶ 例: commit タイムスタンプ（クリックして展開）
次の例は、PGAdapter を使用した書き込みオペレーションの最後の commit タイムスタンプを表示する方法を示しています。
-- 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
1 行と 2 列の結果セットを返します。
COMMIT_TIMESTAMP（type=TIMESTAMP）最新のトランザクションが commit された日時を示します。MUTATION_COUNT（type=int8）commit されたトランザクションで適用されたミューテーションの数を示します。この値は、エミュレータで実行すると常に空になります。
ミューテーション数は、トランザクションが commit される前に SET RETURN_COMMIT_STATS が true に設定されている場合にのみ取得できます。
▶ 例: commit レスポンス（クリックして展開）
次の例は、PGAdapter を使用した書き込みオペレーションの最後の commit レスポンスを表示する方法を示しています。
-- 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]
現在のトランザクションを commit します。キーワード TRANSACTION と WORK はオプションで同等であり、影響はありません。
- 読み取り / 書き込みトランザクションを commit すると、このトランザクションのすべての更新が他のトランザクションに表示され、Spanner でのトランザクションのすべてのロックが解除されます。
- 読み取り専用トランザクションを commit すると、現在の読み取り専用トランザクションが終了します。後続のステートメントで、新しいトランザクションが開始されます。読み取り専用トランザクションの
COMMITとROLLBACKにはセマンティックの違いがありません。
このステートメントは、アクティブなトランザクションがある間にのみ実行できます。
▶ 例: COMMIT TRANSACTION（クリックして展開）
次の例は、PGAdapter を使用してトランザクションを commit する方法を示しています。
-- 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
SET TRANSACTION { READ ONLY | READ WRITE }
現在のトランザクションのトランザクション モードを設定します。
このステートメントを実行できるのは、AUTOCOMMIT が false の場合、または BEGIN [TRANSACTION | WORK] を実行してトランザクションを開始し、トランザクションでまだステートメントを実行していない場合のみです。
このステートメントは、現在のトランザクションのトランザクション モードのみを設定します。トランザクションが commit またはロールバックすると、次のトランザクションは接続のデフォルト モードを使用します。 詳しくは、SET SESSION CHARACTERISTICSを参照してください。
▶ 例: SET TRANSACTION（クリックして展開）
次の例は、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
SET SESSION CHARACTERISTICS AS TRANSACTION { READ ONLY | READ WRITE }
セッション内のトランザクションのデフォルト トランザクション モードを READ ONLY または READ WRITE に設定します。このステートメントは、アクティブなトランザクションが存在しない場合にのみ許可されます。
この設定は SET TRANSACTION コマンドでオーバーライドできます。
▶ 例: SET SESSION CHARACTERISTICS（クリックして展開）
次の例は、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'
実行する次のステートメントにリクエスト タグを設定します。1 つのステートメントに設定できるタグは 1 つのみです。タグが複数のステートメントを適用対象とすることはありません。タグはステートメント単位で設定する必要があります。リクエスト タグを削除するには、空の文字列（''）を設定します。
デフォルトは '' です。
同じステートメントに対してトランザクション タグとステートメント タグの両方を設定できます。
ステートメント ヒントを使用してステートメント タグを追加することもできます。
/*@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'
実行される直近のトランザクション用のトランザクション タグを設定します。1 つのトランザクションに設定できるタグは 1 つのみです。タグが複数のトランザクションを適用対象とすることはありません。タグはトランザクションごとに設定する必要があります。トランザクション タグを削除するには、空の文字列（''）に設定します。トランザクション タグは、トランザクションでステートメントが実行される前に設定する必要があります。
デフォルトは '' です。
同じステートメントに対してトランザクション タグとステートメント タグの両方を設定できます。
詳細については、リクエスト タグとトランザクション タグによるトラブルシューティングをご覧ください。
▶ 例: トランザクション タグ（クリックして展開）
次の例は、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 の実行時に 1 つのバッチとして Spanner に送信されます。複数の DDL ステートメントを 1 つのバッチとして実行すると、通常はステートメントを個別に実行するよりも高速になります。
このステートメントは、アクティブなトランザクションが存在していない場合にのみ実行できます。
▶ 例: 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
RUN BATCH
現在の DDL バッチでバッファリングされたすべての DDL ステートメントをデータベースに送信し、Spanner がこれらのステートメントを実行するのを待機して、現在の DDL バッチを終了します。
Spanner が少なくとも 1 つの DDL ステートメントを実行できない場合は、RUN BATCH が Spanner で実行できない最初の DDL ステートメントに対してエラーを返します。それ以外の場合は、RUN BATCH は正常に動作します。
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
次のステートメントは 2 つの DML ステートメントをまとめてバッチ処理し、1 回の呼び出しでサーバーに送信します。DML バッチは、トランザクションの一部として、または自動 commit モードで実行できます。
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;
セーブポイント コマンド
PGAdapter のセーブポイントはエミュレートされます。セーブポイントにロールバックすると、トランザクション全体がロールバックされ、セーブポイントが設定されたポイントまで再試行されます。セーブポイントまでのトランザクションで使用された基盤となるデータが変更されている場合、このオペレーションは AbortedDueToConcurrentModificationException エラーで失敗します。
セーブポイントのサポートが有効になっている場合、セーブポイントの作成と解放は常に成功します。
次のステートメントは、トランザクションでエミュレートされたセーブポイントを有効または無効にします。
SPANNER.SAVEPOINT_SUPPORT
SHOW [VARIABLE] SPANNER.SAVEPOINT_SUPPORT
SET SPANNER.SAVEPOINT_SUPPORT = { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }
現在の SAVEPOINT_SUPPORT 構成を示す STRING タイプのプロパティ。指定できる値は次のとおりです。
DISABLED: すべてのセーブポイント コマンドが無効になり、失敗します。FAIL_AFTER_ROLLBACK: セーブポイント コマンドが有効になっています。セーブポイントにロールバックすると、トランザクション全体がロールバックされます。セーブポイントにロールバックした後にトランザクションの使用を試みると、オペレーションは失敗します。ENABLED: すべての savepoint コマンドが有効になっています。セーブポイントにロールバックすると、トランザクションがロールバックされ、セーブポイントへの再試行が実行されます。セーブポイントまでのトランザクションで使用された基盤となるデータが変更されている場合、このオペレーションはAbortedDueToConcurrentModificationExceptionエラーで失敗します。
デフォルト値は ENABLED です。
このステートメントは、アクティブなトランザクションが存在していない場合にのみ実行できます。
SAVEPOINT savepoint_name
SAVEPOINT savepoint-name;
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 との間でデータをコピーする方法を示しています。
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 インスタンス上の既存のワークロードへの影響がほぼゼロの状態で、分析クエリとデータ エクスポートを実行できます。Data Boost はパーティション分割クエリでのみサポートされています。
Data Boost は SET SPANNER.DATA_BOOST_ENABLED ステートメントを使用して有効にできます。
PGAdapter は、パーティション分割されたクエリを実行するための次の 3 つの代替手段をサポートしています。
SET SPANNER.AUTO_PARTITION_MODE = trueRUN PARTITIONED QUERY sql- 複数の
RUN PARTITION 'partition-token'が続くPARTITION sql
以下の各セクションでは、これらの方法について説明します。
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 で 2 つのクエリを実行します。
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
RUN PARTITIONED QUERY <sql>
Spanner でパーティション分割クエリとしてクエリを実行します。Data Boost でクエリを実行するには、SPANNER.DATA_BOOST_ENABLED が true に設定されていることを確認します。
SET SPANNER.DATA_BOOST_ENABLED = true
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers
PGAdapter は内部でクエリをパーティション分割し、パーティションを並列に実行します。結果は 1 つの結果セットに統合され、アプリケーションに返されます。パーティションを実行するワーカー スレッドの数は、変数 SPANNER.MAX_PARTITIONED_PARALLELISM で設定できます。
PARTITION <SQL>
PARTITION <sql>
Spanner に対してクエリを実行するパーティションのリストを作成し、パーティション トークンのリストをそれらに返します。各パーティション トークンは、RUN PARTITION 'partition-token' コマンドを使用して、同じ PGAdapter インスタンスまたは別の 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
PGAdapter がパーティションの実行に使用するワーカー スレッドの数を示す bigint 型のプロパティ。この値は次の場合に使用されます。
SPANNER.AUTO_PARTITION_MODE = trueRUN PARTITIONED QUERY sql
SHOW SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM {TO|=} <bigint>
PGAdapter がパーティションの実行に使用できるワーカー スレッドの最大数を設定します。この値を 0 に設定すると、PGAdapter に対して、クライアント マシンの CPU コア数を最大値として使用するように指示されます。
デフォルトは 0 です。
次のステップ
- PGAdapter を起動する方法の詳細を確認する。
- サポートされている PostgreSQL ドライバと ORM の完全なリストを見る。