Befehle zur JDBC-Sitzungsverwaltung (GoogleSQL)

Der Spanner-JDBC-Treiber (Java Database Connectivity) unterstützt Sitzungsverwaltungsanweisungen, mit denen Sie den Status Ihrer Verbindung ändern, Transaktionen ausführen und Batches von Anweisungen effizient ausführen können.

Die folgenden Befehle gelten für GoogleSQL-Dialekt-Datenbanken.

Hinweis: Sie können Anweisungen zur Sitzungsverwaltung nur mit dem Spanner-JDBC-Treiber verwenden. Anweisungen zur Sitzungsverwaltung funktionieren nicht in den Clientbibliotheken, der Google Cloud CLI oder dem von Simba erstellten JDBC-Treiber.

Verbindungsanweisungen

Mit den folgenden Anweisungen werden die Eigenschaften der aktuellen Verbindung geändert oder aufgerufen.

READONLY

Ein boolescher Wert, der angibt, ob sich die Verbindung im Lesemodus befindet. Der Standardwert von false ist.

SHOW VARIABLE READONLY
SET READONLY = { true | false }

Sie können den Wert dieses Attributs nur ändern, wenn keine aktive Transaktion vorhanden ist.

▶ Beispiel: schreibgeschützte Transaktion (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie mit dieser Eigenschaft schreibgeschützte Transaktionen in Spanner ausführen.

SET 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 VARIABLE READ_TIMESTAMP;

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

AUTOCOMMIT

Ein boolescher Wert, der angibt, ob sich die Verbindung im Autocommit-Modus befindet. Der Standardwert von true ist.

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

Sie können den Wert dieses Attributs nur ändern, wenn keine aktive Transaktion vorhanden ist.

Wenn AUTOCOMMIT auf „false“ gesetzt ist, wird nach der Ausführung von COMMIT oder ROLLBACK automatisch eine neue Transaktion initiiert. Die erste Anweisung, die Sie ausführen, startet die Transaktion.

▶ Beispiel: Autocommit (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie die Property autocommit verwendet wird.

-- The default value for AUTOCOMMIT is true.
SHOW VARIABLE 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;

RETRY_ABORTS_INTERNALLY

Ein boolescher Wert, der angibt, ob abgebrochene Transaktionen bei der Verbindung automatisch wiederholt werden. Der Standardwert ist true.

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }

Sie können den Wert dieses Attributs erst ändern, nachdem eine Transaktion gestartet wurde (siehe BEGIN TRANSACTION) und bevor Anweisungen innerhalb der Transaktion ausgeführt werden.

Wenn Sie RETRY_ABORTS_INTERNALLY auf „true“ setzen, behält die Verbindung eine Prüfsumme aller Daten bei, die die Verbindung an die Clientanwendung zurückgibt. Damit wird die Transaktion wiederholt, wenn sie von Spanner abgebrochen wird.

Der Standardwert ist true. Wir empfehlen, diesen Wert auf false zu setzen, wenn Ihre Anwendung bereits abgebrochene Transaktionen wiederholt.

AUTOCOMMIT_DML_MODE

Ein STRING-Attribut, das den Autocommit-Modus für DML-Anweisungen (Data Manipulation Language) angibt.

SHOW VARIABLE AUTOCOMMIT_DML_MODE
SET AUTOCOMMIT_DML_MODE = { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }

Die möglichen Werte sind:

• Im TRANSACTIONAL-Modus führt der Treiber DML-Anweisungen als separate atomare Transaktionen aus. Der Treiber erstellt eine neue Transaktion, führt die DML-Anweisung aus und lässt danach entweder bei erfolgreicher Ausführung ein Commit oder im Falle eines Fehlers ein Rollback der Transaktion durchführen.
• Im PARTITIONED_NON_ATOMIC-Modus führt der Treiber DML-Anweisungen als partitionierte Aktualisierungsanweisungen aus. Eine partitionierte Update-Anweisung kann als eine Reihe von vielen Transaktionen ausgeführt werden, die jeweils eine Teilmenge der betroffenen Zeilen abdecken. Die partitionierte Anweisung bietet eine abgeschwächte Semantik im Austausch für eine bessere Skalierbarkeit und Leistung.

Der Standardwert ist TRANSACTIONAL.

▶ Beispiel: Partitionierte DML (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie partitionierte DML mit dem Spanner-JDBC-Treiber ausgeführt wird.

-- Change autocommit DML mode to use Partitioned DML.
SET 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 AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';

STATEMENT_TIMEOUT

Eine Eigenschaft vom Typ STRING, die den aktuellen Zeitüberschreitungswert für Anweisungen angibt.

SHOW VARIABLE STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT = { '<INT64>{ s | ms | us | ns }' | NULL }

Der Wert für INT64 besteht aus einer ganzen Zahl gefolgt von einem Suffix, das die Zeiteinheit angibt. Der Wert NULL bedeutet, dass kein Wert für die Zeitüberschreitung festgelegt wurde. Wenn ein Zeitüberschreitungswert in einer Anweisung festgelegt wurde, verursachen Anweisungen, die länger als der angegebene Zeitüberschreitungswert dauern, den Fehler java.sql.SQLTimeoutException und machen die Transaktion ungültig.

Folgende Zeiteinheiten werden unterstützt:

• s: Sekunden
• ms: Millisekunden
• us: Mikrosekunden
• ns: Nanosekunden

Der Standardwert ist NULL, was bedeutet, dass kein Wert für die Zeitüberschreitung festgelegt ist.

Durch das Zeitlimit einer Anweisung während einer Transaktion wird die Transaktion ungültig, alle nachfolgenden Anweisungen in der ungültig gemachten Transaktion (außer ROLLBACK) schlagen fehl und der Spanner-JDBC-Treiber gibt ein java.sql.SQLTimeoutException aus.

READ_ONLY_STALENESS

Ein Attribut vom Typ STRING, das die aktuelle Einstellung für die schreibgeschützte Veralterung angibt, die Spanner für schreibgeschützte Transaktionen und Abfragen im AUTOCOMMIT-Modus verwendet.

SHOW VARIABLE READ_ONLY_STALENESS
SET READ_ONLY_STALENESS = staleness_type

staleness_type:

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

Der Wert für die schreibgeschützte Veralterung gilt für alle nachfolgenden schreibgeschützten Transaktionen und für alle Abfragen im AUTOCOMMIT-Modus.

Der Standardwert ist STRONG.

Die Optionen für Zeitstempelgrenzen sind folgende:

• STRONG weist Spanner an, einen starken Lesevorgang auszuführen.
• MAX_STALENESS definiert das Zeitintervall, das Spanner zum Ausführen eines Lesevorgangs von begrenzter Veralterung im Verhältnis zu now() verwendet.
• MIN_READ_TIMESTAMP definiert eine absolute Zeit, die Spanner verwendet, um einen Lesevorgang von begrenzter Veralterung auszuführen.
• EXACT_STALENESS definiert das Zeitintervall, das Spanner verwendet, um einen Lesevorgang von exakter Veralterung im Vergleich zu now() auszuführen.
• READ_TIMESTAMP definiert eine absolute Zeit, die Spanner verwendet, um einen Lesevorgang von exakter Veralterung durchzuführen.

Zeitstempel müssen das folgende Format haben:

YYYY-[M]M-[D]DT[[H]H:[M]M:[S]S[.DDDDDD]][timezone]

Folgende Zeiteinheiten werden zum Festlegen der Werte MAX_STALENESS und EXACT_STALENESS unterstützt:

• s: Sekunden
• ms: Millisekunden
• us: Mikrosekunden
• ns: Nanosekunden

Sie können den Wert dieses Attributs nur ändern, wenn keine aktive Transaktion vorhanden ist.

Hinweis: Sie können die Werte MIN_READ_TIMESTAMP und MAX_STALENESS nur für Abfragen im AUTOCOMMIT-Modus verwenden.

▶ Beispiel: Veralterung (schreibgeschützt) (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie Abfragen mit einem benutzerdefinierten Veralterungswert mit dem Spanner-JDBC-Treiber ausführen.

-- Set the read-only staleness to MAX_STALENESS 10 seconds.
SET 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 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 READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_VERSION

Ein Attribut vom Typ STRING, das die Optimierungsversion angibt. Die Version ist entweder eine Ganzzahl oder „LATEST“.

SHOW VARIABLE OPTIMIZER_VERSION
SET OPTIMIZER_VERSION = { 'version'|'LATEST'|'' }

Legt die Version der Optimierung fest, die für alle folgenden Anweisungen in der Verbindung verwendet werden soll. Wenn die Optimierungsversion auf '' (leerer String) festgelegt ist, verwendet Spanner die neueste Version. Wenn keine Optimierungsversion festgelegt ist, verwendet Spanner die Optimierungsversion, die auf Datenbankebene festgelegt wurde.

Der Standardwert ist ''.

▶ Beispiel: Optimierungsversion (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Abfragen mit einer bestimmten Optimierungsversion mit dem Spanner-JDBC-Treiber ausgeführt werden.

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the latest optimizer version.
SET 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 OPTIMIZER_VERSION = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_STATISTICS_PACKAGE

Ein Attribut vom Typ STRING, das das aktuelle Statistikpaket für die Optimierung angibt, das von dieser Verbindung verwendet wird.

SHOW VARIABLE OPTIMIZER_STATISTICS_PACKAGE
SET OPTIMIZER_STATISTICS_PACKAGE = { 'package'|'' }

Legt das Optimierungsstatistikpaket fest, das für alle folgenden Anweisungen in der Verbindung verwendet werden soll. <package> muss ein gültiger Paketname sein. Wenn kein Optimierungsstatistikpaket festgelegt ist, verwendet Spanner das auf Datenbankebene festgelegte Optimierungsstatistikpaket.

Der Standardwert ist ''.

▶ Beispiel: Optimierungsstatistikpaket (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Abfragen mit einem bestimmten Optimierungsstatistikpaket mit dem Spanner-JDBC-Treiber ausgeführt werden.

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

RETURN_COMMIT_STATS

Ein Attribut vom Typ BOOL, das angibt, ob Statistiken für Transaktionen über diese Verbindung zurückgegeben werden sollen. Mit dem Befehl SHOW VARIABLE COMMIT_RESPONSE können Sie die zurückgegebenen Statistiken aufrufen.

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }

Der Standardwert ist false.

▶ Beispiel: Commit-Statistiken (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie Commit-Statistiken für eine Transaktion mit dem Spanner-JDBC-Treiber ansehen.

-- Enable the returning of commit stats.
SET 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 VARIABLE COMMIT_RESPONSE;

RPC_PRIORITY

Ein Attribut vom Typ STRING, das die relative Priorität für Spanner-Anfragen angibt. Die Priorität dient als Hinweis für den Spanner-Planer und garantiert nicht die Reihenfolge der Ausführung.

SHOW VARIABLE RPC_PRIORITY
SET RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

'NULL' bedeutet, dass die Anfrage keinen Hinweis enthalten soll.

Der Standardwert ist 'NULL'.

Weitere Informationen zu Priority.

Tags

Mit den folgenden Anweisungen werden Anfrage- und Transaktions-Tags verwaltet.

STATEMENT_TAG

Eine Eigenschaft vom Typ STRING, die das Anfrage-Tag für die nächste Anweisung enthält.

SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'

Legt das Anfrage-Tag für die nächste auszuführende Anweisung fest. Pro Anweisung kann nur ein Tag festgelegt werden. Das Tag umfasst nicht mehrere Anweisungen. Es muss pro Anweisung festgelegt werden. Sie können ein Anfrage-Tag entfernen, indem Sie es auf einen leeren String ('') festlegen.

Der Standardwert ist ''.

Sie können sowohl Transaktions-Tags als auch Anweisungs-Tags für dieselbe Anweisung festlegen.

Weitere Informationen finden Sie unter Fehlerbehebung mit Anfrage- und Transaktions-Tags.

▶ Beispiel: Anweisungs-Tags (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Anweisungs-Tags mit dem Spanner-JDBC-Treiber festgelegt werden.

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

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

TRANSACTION_TAG

Eine Property vom Typ STRING, die das Transaktions-Tag für die nächste Transaktion enthält.

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

Legt das Transaktions-Tag für die aktuelle Transaktion fest, die ausgeführt werden soll. Pro Transaktion kann nur ein Tag festgelegt werden. Das Tag umfasst nicht mehrere Transaktionen. Es muss pro Transaktion festgelegt werden. Ein Transaktions-Tag kann entfernt werden, indem es auf den leeren String ('') gesetzt wird. Das Transaktions-Tag muss festgelegt werden, bevor in der Transaktion Anweisungen ausgeführt werden.

Der Standardwert ist ''.

Sie können sowohl Transaktions-Tags als auch Anweisungs-Tags für dieselbe Anweisung festlegen.

Weitere Informationen finden Sie unter Fehlerbehebung mit Anfrage- und Transaktions-Tags.

▶ Beispiel: Transaktions-Tags (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie Transaktions-Tags mit dem Spanner-JDBC-Treiber festlegen.

BEGIN;
-- Set the transaction tag for the current transaction.
SET 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 STATEMENT_TAG = 'select-statement';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

-- Set another tag for the next statement.
SET 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 VARIABLE TRANSACTION_TAG;

Transaktionsanweisungen

Mit den folgenden Anweisungen werden Spanner-Transaktionen verwaltet und Commits durchgeführt.

READ_TIMESTAMP

SHOW VARIABLE READ_TIMESTAMP

Gibt eine Ergebnismenge mit einer Zeile und einer Spalte vom Typ TIMESTAMP zurück, die den Lesezeitstempel der letzten schreibgeschützten Transaktion enthält. Diese Anweisung gibt nur dann einen Zeitstempel zurück, wenn entweder eine schreibgeschützte Transaktion noch aktiv ist und mindestens eine Abfrage ausgeführt hat, oder unmittelbar nachdem ein Commit einer schreibgeschützten Transaktion durchgeführt und bevor eine neue Transaktion begonnen wurde. Andernfalls lautet das Ergebnis NULL.

▶ Beispiel: Zeitstempel lesen (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie den Zeitstempel des letzten Lesevorgangs für einen schreibgeschützten Vorgang mit dem Spanner-JDBC-Treiber anzeigen lassen.

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

-- Set a non-deterministic read-only staleness and execute the same query.
SET 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 VARIABLE READ_TIMESTAMP;

-- The read timestamp of a read-only transaction can also be retrieved.
SET 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 VARIABLE 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 VARIABLE READ_TIMESTAMP;

COMMIT;

COMMIT_TIMESTAMP

SHOW VARIABLE COMMIT_TIMESTAMP

Gibt eine Ergebnismenge mit einer Zeile und einer Spalte vom Typ TIMESTAMP zurück, die den Commit-Zeitstempel der letzten Lese-/Schreibtransaktion enthält, für die Spanner ein Commit durchgeführt hat. Diese Anweisung gibt nur dann einen Zeitstempel zurück, wenn Sie sie ausführen, nachdem Sie einen Commit für eine Lese-Schreib-Transaktion durchgeführt haben und bevor Sie nachfolgende SELECT-, DML- oder Schemaänderungsanweisungen ausführen. Andernfalls ist das Ergebnis NULL.

▶ Beispiel: Commit-Zeitstempel (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie den letzten Commit-Zeitstempel für einen Schreibvorgang mit dem Spanner-JDBC-Treiber aufrufen.

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

COMMIT_RESPONSE

SHOW VARIABLE COMMIT_RESPONSE

Gibt eine Ergebnismenge mit einer Zeile und zwei Spalten zurück:

• COMMIT_TIMESTAMP (Typ=TIMESTAMP) gibt an, wann die letzte Transaktion mit Commit bestätigt wurde.
• MUTATION_COUNT (Typ=INT64) gibt an, wie viele Mutationen in der mit Commit durchgeführten Transaktion angewendet wurden. Dieser Wert ist immer leer, wenn er im Emulator ausgeführt wird.

Die Mutationsanzahl ist nur verfügbar, wenn SET RETURN_COMMIT_STATS vor dem Commit der Transaktion auf true gesetzt wurde.

▶ Beispiel: Commit-Antwort (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie die letzte Commit-Antwort für einen Schreibvorgang mit dem Spanner-JDBC-Treiber ansehen.

-- Enable returning commit stats in addition to the commit timestamp.
SET 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 VARIABLE COMMIT_RESPONSE;

BEGIN [TRANSACTION]

BEGIN [TRANSACTION]

Startet eine neue Transaktion. Das Keyword TRANSACTION ist optional.

• Verwenden Sie COMMIT oder ROLLBACK, um eine Transaktion zu beenden.
• Wenn Sie den AUTOCOMMIT-Modus aktiviert haben, entfernt diese Anweisung vorübergehend die Verbindung aus dem AUTOCOMMIT-Modus. Die Verbindung kehrt in den AUTOCOMMIT-Modus zurück, wenn die Transaktion endet.
• Der Transaktionsmodus wird durch die aktuelle READONLY-Einstellung für diese Verbindung bestimmt. Dieser Wert wird mit dem Befehl SET READONLY = {TRUE | FALSE} festgelegt.
• Sie können den Transaktionsmodus ändern, indem Sie SET TRANSACTION READ ONLY oder SET TRANSACTION READ WRITE direkt nach der Ausführung von BEGIN [TRANSACTION] ausführen.

Sie können diese Anweisung nur ausführen, wenn keine aktive Transaktion vorhanden ist.

▶ Beispiel: BEGIN TRANSACTION (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie verschiedene Arten von Transaktionen mit dem Spanner-JDBC-Treiber starten.

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

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

COMMIT [TRANSACTION]

COMMIT [TRANSACTION]

Führt ein Commit der aktuellen Transaktion durch. Das Keyword TRANSACTION ist optional.

• Durch das Commit einer Lese-/Schreibtransaktion werden alle Aktualisierungen dieser Transaktion für andere Transaktionen sichtbar und alle Sperren der Transaktion für Spanner werden freigegeben.
• Durch das Commit einer schreibgeschützten Transaktion wird die aktuelle schreibgeschützte Transaktion beendet. Jede nachfolgende Anweisung startet eine neue Transaktion. Es gibt keinen semantischen Unterschied zwischen COMMIT und ROLLBACK für eine schreibgeschützte Transaktion.

Sie können diese Anweisung nur ausführen, während eine aktive Transaktion vorhanden ist.

▶ Beispiel: COMMIT TRANSACTION (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie mit dem Spanner-JDBC-Treiber einen Commit für eine Transaktion durchführen.

-- 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;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

ROLLBACK [TRANSACTION]

ROLLBACK [TRANSACTION]

Führt ein ROLLBACK der aktuellen Transaktion durch. Die Keywords TRANSACTION sind optional.

• Durch das Ausführen eines ROLLBACK-Vorgangs für eine Lese-Schreib-Transaktion werden alle zwischengespeicherten Mutationen gelöscht, ein Rollback der Transaktion in Spanner durchgeführt und alle Sperren der Transaktion aufgehoben.
• Ein ROLLBACK einer schreibgeschützten Transaktion beendet die aktuelle schreibgeschützte Transaktion. Jede nachfolgende Anweisung startet eine neue Transaktion. Es gibt keinen semantischen Unterschied zwischen COMMIT und ROLLBACK für eine schreibgeschützte Transaktion auf einer Verbindung.

Sie können diese Anweisung nur ausführen, während eine aktive Transaktion vorhanden ist.

▶ Beispiel: ROLLBACK TRANSACTION (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie mit dem Spanner-JDBC-Treiber ein Rollback einer Transaktion durchführen.

-- 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;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Legt den Transaktionsmodus für die aktuelle Transaktion fest.

Sie können diese Anweisung nur ausführen, wenn AUTOCOMMIT den Wert false hat, oder wenn Sie eine Transaktion durch Ausführung von BEGIN [TRANSACTION] gestartet und noch keine Anweisungen in der Transaktion ausgeführt haben.

Diese Anweisung legt den Transaktionsmodus nur für die aktuelle Transaktion fest. Wenn für die Transaktion ein Commit durchgeführt oder ein Rollback durchgeführt wird, verwendet die nächste Transaktion den Standardmodus für die Verbindung (siehe SET READONLY).

Hinweis: Sie können den Transaktionsmodus nicht auf READ WRITE festlegen, wenn sich die Verbindung im READ ONLY-Modus befindet.

▶ Beispiel: SET TRANSACTION (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Transaktionseigenschaften mit dem Spanner-JDBC-Treiber festgelegt werden.

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

Batch-Anweisungen

Mit den folgenden Anweisungen werden Batches von DDL-Anweisungen verwaltet und an Spanner gesendet.

START BATCH DDL

START BATCH DDL

Startet einen Batch von DDL-Anweisungen auf der Verbindung. Alle nachfolgenden Anweisungen im Batch müssen DDL-Anweisungen sein. Die DDL-Anweisungen werden lokal zwischengespeichert und als ein Batch an Spanner gesendet, wenn Sie RUN BATCH ausführen. Die Ausführung mehrerer DDL-Anweisungen in einem Batch ist in der Regel schneller als die separate Ausführung der Anweisungen.

Sie können diese Anweisung nur ausführen, wenn keine aktive Transaktion vorhanden ist.

▶ Beispiel: DDL-Batch (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie einen DDL-Batch mit dem Spanner-JDBC-Treiber ausführen.

-- 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  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

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

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

RUN BATCH

RUN BATCH

Sendet alle zwischengespeicherten DDL-Anweisungen im aktuellen DDL-Batch an die Datenbank, wartet, bis Spanner diese Anweisungen ausgeführt hat, und beendet den aktuellen DDL-Batch.

Wenn Spanner nicht mindestens eine DDL-Anweisung ausführen kann, gibt RUN BATCH für die erste DDL-Anweisung einen Fehler zurück, den Spanner nicht ausführen kann. Andernfalls wird RUN BATCH erfolgreich zurückgegeben.

Hinweis: Wenn eine DDL-Anweisung im Batch einen Fehler zurückgibt, hat Spanner die vorherigen DDL-Anweisungen im selben Batch möglicherweise trotzdem auf die Datenbank angewendet.

BATCH Abbrechen [TRANSAKTION]

Löscht alle gepufferten DDL-Anweisungen im aktuellen DDL-Batch und beendet den Batch.

Sie können diese Anweisung nur ausführen, wenn ein DDL-Batch aktiv ist. Sie können ABORT BATCH verwenden, unabhängig davon, ob im Batch gepufferte DDL-Anweisungen vorhanden sind oder nicht. Alle vorherigen DDL-Anweisungen im Batch werden abgebrochen.

▶ Beispiel: DDL-Batch abbrechen (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie einen DDL-Batch mit dem Spanner-JDBC-Treiber abbrechen.

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

-- The following statements are buffered locally.
CREATE TABLE Singers (
  SingerId  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

CREATE TABLE Albums (
  AlbumId  INT64 NOT NULL,
  Title    STRING(MAX),
  SingerId INT64,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
) PRIMARY KEY (AlbumId);

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

BATCH DML STARTEN und Batch ausführen

Mit den folgenden Anweisungen werden die beiden DML-Anweisungen zusammengefasst und in einem Aufruf an den Server gesendet. Ein DML-Batch kann als Teil einer Transaktion oder im automatischen Commit-Modus ausgeführt werden.

START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
RUN BATCH;

▶ Beispiel: DML-Batch (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie einen DML-Batch mit dem Spanner-JDBC-Treiber ausführen.

-- 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 und partitionierte Abfrageanweisungen

Die partitionQuery API teilt eine Abfrage in kleinere Teile oder Partitionen auf und verwendet mehrere Maschinen, um die Partitionen parallel abzurufen. Jede Partition wird durch ein Partitionstoken identifiziert. Die PartitionQuery API hat eine höhere Latenz als die Standardabfrage-API, da sie nur für Bulk-Vorgänge wie das Exportieren oder Scannen der gesamten Datenbank vorgesehen ist.

Mit Data Boost können Sie Analyseabfragen und Datenexporte mit nahezu keinen Auswirkungen auf vorhandene Arbeitslasten auf der bereitgestellten Spanner-Instanz ausführen. Data Boost unterstützt nur partitionierte Abfragen.

Sie können Data Boost mit der SET DATA_BOOST_ENABLED-Anweisung aktivieren.

Der Spanner-JDBC-Treiber unterstützt drei Alternativen zum Ausführen von partitionierten Abfragen:

• SET AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql gefolgt von mehreren RUN PARTITION 'partition-token'

Jede dieser Methoden wird in den folgenden Abschnitten beschrieben.

DATA_BOOST_ENABLED

Ein Attribut vom Typ BOOL, das angibt, ob für diese Verbindung Data Boost für partitionierte Abfragen verwendet werden soll. Der Standardwert ist false.

SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

▶ Beispiel: Abfrage mit Data Boost ausführen (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie eine Abfrage mithilfe von Data Boost mit dem Spanner-JDBC-Treiber ausführen.

-- Enable Data Boost on this connection.
SET DATA_BOOST_ENABLED = true;

-- Execute a partitioned query. Data Boost is only used for partitioned queries.
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers;

Ein vollständiges Beispiel finden Sie unter DataBoostExample.

AUTO_PARTITION_MODE

Ein Attribut vom Typ BOOL, das angibt, ob die Verbindung automatisch für alle ausgeführten Abfragen partitionierte Abfragen verwendet.

SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}

• Legen Sie diese Variable auf true fest, wenn die Verbindung für alle ausgeführten Abfragen eine partitionierte Abfrage verwenden soll.
• Legen Sie außerdem DATA_BOOST_ENABLED auf true fest, wenn die Verbindung Data Boost für alle Abfragen verwenden soll.

Der Standardwert ist false.

▶ Beispiel: Ausführung (zum Maximieren klicken)

In diesem Beispiel werden zwei Abfragen mit dem Spanner-JDBC-Treiber mithilfe von Data Boost ausgeführt.

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

Ein vollständiges Beispiel finden Sie unter AutoPartitionModeExample.

ABGEGLEICHTE ABFRAGE AUSFÜHREN

RUN PARTITIONED QUERY <sql>

Führt eine Abfrage als partitionierte Abfrage in Spanner aus. Achten Sie darauf, dass DATA_BOOST_ENABLED auf true gesetzt ist, um die Abfrage mit Data Boost auszuführen:

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

Der Spanner-JDBC-Treiber partitioniert die Abfrage intern und führt Partitionen parallel aus. Die Ergebnisse werden zu einem Ergebnissatz zusammengeführt und an die Anwendung zurückgegeben. Die Anzahl der Worker-Threads, die Partitionen ausführen, kann mit der Variablen MAX_PARTITIONED_PARALLELISM festgelegt werden.

Ein vollständiges Beispiel finden Sie unter RunPartitionedQueryExample.

Partition <SQL>

PARTITION <sql>

Erstellt eine Liste von Partitionen, um eine Abfrage für Spanner auszuführen, und gibt ihnen eine Liste von Partitionstokens zurück. Jedes Partitionstoken kann mit dem Befehl RUN PARTITION 'partition-token' auf demselben oder einem anderen Client auf einer separaten Verbindung ausgeführt werden.

▶ Beispiel: Partitionsabfrage (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie eine Abfrage partitionieren und dann jede Partition separat mit dem Spanner-JDBC-Treiber ausführen.

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

Ein vollständiges Beispiel finden Sie unter PartitionQueryExample.

REGION AUSFÜHREN: „partition-token“

RUN PARTITION 'partition-token'

Führt eine Abfragepartition aus, die zuvor vom Befehl PARTITION zurückgegeben wurde. Der Befehl kann für jede Verbindung ausgeführt werden, die mit derselben Datenbank wie die Datenbank verbunden ist, die die Partitionstokens erstellt hat.

MAX_PARTITIONED_PARALLELISM

Ein Attribut vom Typ INT64, das die Anzahl der Worker-Threads angibt, die der Spanner-JDBC-Treiber zum Ausführen von Partitionen verwendet. Dieser Wert wird verwendet für:

• AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

Legt die maximale Anzahl von Worker-Threads fest, die der Spanner-JDBC-Treiber zum Ausführen von Partitionen verwenden kann. Wenn Sie diesen Wert auf 0 festlegen, wird der Spanner-JDBC-Treiber angewiesen, die Anzahl der CPU-Kerne auf dem Clientcomputer als Maximum zu verwenden.

Der Standardwert ist 0.

Savepoint-Befehle

Mit den folgenden Anweisungen werden emulierte Savepoints in Transaktionen aktiviert und deaktiviert. Sie können einen Savepoint durch Aufrufen der Methode java.sql.Connection#setSavepoint() erstellen.

Der Spanner-JDBC-Treiber emuliert Savepoints, um Frameworks zu unterstützen, die diese für verschachtelte Transaktionen verwenden. Savepoints werden emuliert, indem eine laufende Prüfsumme für die Ergebnisse verfolgt wird, die von Anweisungen in der Transaktion zurückgegeben wurden. Beim Rollback zu einem Savepoint führt der Spanner-JDBC-Treiber ein Rollback der Transaktion durch und wiederholt die Transaktion bis zu dem Punkt, an dem der Savepoint festgelegt wurde. Die Prüfsumme des Wiederholungsversuchs wird mit der Prüfsumme der ursprünglichen Transaktion verglichen, um sicherzustellen, dass dieselben Ergebnisse zurückgegeben wurden.

SAVEPOINT_SUPPORT

SHOW VARIABLE SAVEPOINT_SUPPORT
SET SAVEPOINT_SUPPORT = { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }

Ein Attribut vom Typ STRING, das die aktuelle SAVEPOINT_SUPPORT-Konfiguration angibt. Folgende Werte sind möglich:

• DISABLED: Alle Savepoint-Befehle sind deaktiviert und schlagen fehl.
• FAIL_AFTER_ROLLBACK: Savepoint-Befehle sind aktiviert. Bei einem Rollback zu einem Savepoint wird die gesamte Transaktion rückgängig gemacht. Die Transaktion schlägt fehl, wenn Sie versuchen, sie nach dem Rollback zu einem Savepoint zu verwenden.
• ENABLED: Alle Savepoint-Befehle sind aktiviert. Durch ein Rollback zu einem Savepoint wird die Transaktion rückgängig gemacht und es wird ein neuer Versuch am Savepoint durchgeführt. Dieser Vorgang schlägt mit dem Fehler AbortedDueToConcurrentModificationException fehl, wenn sich die zugrunde liegenden Daten, die von der Transaktion bis zum Savepoint verwendet wurden, geändert haben.

Der Standardwert ist FAIL_AFTER_ROLLBACK.

Sie können den Wert dieser Variable nur ändern, wenn keine aktive Transaktion vorhanden ist.

▶ Beispiel: Savepoint-Unterstützung (zum Maximieren klicken)

Das folgende Beispiel zeigt, wie Sie die Unterstützung von Savepoints im Spanner-JDBC-Treiber aktivieren und deaktivieren.

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 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 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 SAVEPOINT_SUPPORT='ENABLED'");
  Savepoint mySavepoint3 = connection.setSavepoint("my_savepoint3");
  connection.createStatement().execute("insert into my_table (id, value) values (2, 'Two')");
  connection.rollback(mySavepoint3);
}

Nächste Schritte

Weitere Informationen zum Verbinden von JDBC mit einer GoogleSQL-Dialekt-Datenbank