Commandes de gestion des sessions JDBC (GoogleSQL)

Le pilote JDBC Spanner (connectivité de base de données Java) accepte les sessions qui vous permettent de modifier l'état de votre connexion, exécuter des transactions et exécuter efficacement des lots d'instructions.

Les commandes suivantes s'appliquent aux bases de données en dialecte GoogleSQL.

Remarque :Vous ne pouvez utiliser les instructions de gestion des sessions qu'avec le Pilote JDBC Spanner. Les déclarations de gestion de session ne fonctionnent pas les bibliothèques clientes, la Google Cloud CLI ou le pilote JDBC créé par Simba.

Instructions de connexion

Les déclarations suivantes modifient ou affichent les propriétés de la connexion actuelle.

LECTURE SEULE

Valeur booléenne indiquant si la connexion est en mode lecture seule ou non. La valeur par défaut est false.

SHOW VARIABLE READONLY
SET READONLY = { true | false }

Vous ne pouvez modifier la valeur de cette propriété que lorsqu'aucune transaction n'est active.

▶ Exemple: Transaction en lecture seule (cliquer pour développer)

L'exemple suivant montre comment utiliser cette propriété pour exécuter des transactions en lecture seule dans Spanner.

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;

COMMUNICATION AUTOMATIQUE

Valeur booléenne indiquant si la connexion est en mode commit automatique ou non. La valeur par défaut est true.

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

Vous ne pouvez modifier la valeur de cette propriété que lorsqu'aucune transaction.

Lorsque AUTOCOMMIT est défini sur "false", une nouvelle transaction est automatiquement lancée. après avoir exécuté COMMIT ou ROLLBACK. La première instruction que vous exécutez démarre la transaction.

▶ Exemple : Commit automatique (cliquez pour développer)

L'exemple suivant montre comment utiliser la propriété autocommit.

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

RETRY_ABORTS_INTERNALLY

Booléen indiquant si les tentatives de connexion sont automatiquement annulées les transactions. La valeur par défaut est true.

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }

Vous ne pouvez modifier la valeur de cette propriété qu'après le début d'une transaction (voir BEGIN TRANSACTION) et avant toutes les instructions sont exécutées dans la transaction.

Lorsque vous définissez RETRY_ABORTS_INTERNALLY sur "true", la connexion conserve un de toutes les données que la connexion renvoie à l'application cliente. Ce permet de relancer la transaction si elle est annulée par Spanner.

La valeur par défaut est true. Nous vous recommandons de définir cette valeur sur false si votre application exécute déjà de nouvelles tentatives de transactions annulées.

AUTOCOMMIT_DML_MODE

Propriété STRING indiquant le mode autocommit pour les instructions LMD (langage de manipulation de données).

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

Les valeurs possibles sont :

• En mode TRANSACTIONAL, le pilote exécute les instructions LMD en tant que transactions atomiques distinctes. Le pilote crée une transaction, exécute l'instruction LMD, puis valide la transaction une fois l'exécution terminée ou annule la transaction en cas d'erreur.
• En mode PARTITIONED_NON_ATOMIC, le pilote exécute les instructions LMD en tant qu'instructions UPDATE partitionnées. Une instruction UPDATE partitionnée peut s'exécuter sous la forme d'une série de transactions, chacune couvrant un sous-ensemble de lignes affectées. L'instruction partitionnée fournit a affiné la sémantique en échange d'une meilleure évolutivité et de performances.

La valeur par défaut est TRANSACTIONAL.

▶ Exemple: LMD partitionné (cliquer pour développer)

L'exemple suivant montre comment exécuter une DML partitionnée à l'aide du pilote JDBC Spanner.

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

Propriété de type STRING indiquant la valeur de délai d'expiration actuelle pour les instructions.

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

La valeur INT64 est un nombre entier suivi d'un suffixe indiquant l'unité de temps. La valeur NULL indique qu'aucune valeur n'a été définie pour le délai d'expiration. Si un une valeur de délai avant expiration d'instruction définie, les instructions qui prennent plus de temps que la valeur du délai avant expiration spécifiée entraînera une erreur java.sql.SQLTimeoutException et invalider la transaction.

Les unités de temps acceptées sont les suivantes :

• s : secondes
• ms : millisecondes
• us : microsecondes
• ns : nanosecondes

La valeur par défaut est NULL, ce qui signifie qu'aucune valeur de délai d'expiration n'est définie.

Le déclenchement d'un délai d'expiration d'instruction lors d'une transaction invalide celle-ci et entraîne l'échec de toutes les instructions suivantes (sauf ROLLBACK). En outre, le pilote JDBC Spanner génère une exception java.sql.SQLTimeoutException.

READ_ONLY_STALENESS

Une propriété de type STRING indiquant l'état actuel paramètre d'obsolescence en lecture seule qui Spanner utilise les transactions et les requêtes en lecture seule dans AUTOCOMMIT .

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

La valeur d'obsolescence en lecture seule s'applique à toutes les transactions suivantes en lecture seule et à toutes les requêtes en mode AUTOCOMMIT.

La valeur par défaut est STRONG.

Les options liées à l'horodatage sont les suivantes :

• STRONG indique à Spanner d'effectuer une lecture forte.
• MAX_STALENESS définit l'intervalle de temps que Spanner utilise pour effectuer une lecture d'obsolescence limitée, par rapport à now().
• MIN_READ_TIMESTAMP définit le délai absolu que Spanner utilise pour effectuer une lecture d'obsolescence limitée.
• EXACT_STALENESS définit l'intervalle de temps que Spanner utilise pour effectuer une lecture d'obsolescence exacte, par rapport à now().
• READ_TIMESTAMP définit le délai absolu que Spanner utilise pour effectuer une lecture d'obsolescence exacte.

Les horodatages doivent respecter le format suivant :

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

Les unités de temps acceptées pour la définition des valeurs MAX_STALENESS et EXACT_STALENESS sont les suivantes :

• s : secondes
• ms : millisecondes
• us : microsecondes
• ns : nanosecondes

Vous ne pouvez modifier la valeur de cette propriété que lorsqu'aucune transaction n'est active.

Remarque :Vous ne pouvez utiliser les valeurs MIN_READ_TIMESTAMP et MAX_STALENESS que pour en mode AUTOCOMMIT.

▶ Exemple: obsolescence en lecture seule (cliquer pour développer)

L'exemple suivant montre comment exécuter des requêtes avec une obsolescence personnalisée avec le pilote JDBC Spanner.

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

Une propriété de type STRING indiquant version de l'optimiseur. La version est un entier ou 'LATEST'.

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

Définit la version de l'optimiseur à utiliser pour toutes les instructions suivantes sur la connexion. Si la version de l'optimiseur est définie sur '' (chaîne vide), Spanner utilise la dernière version. Si aucune version d'optimiseur n'est définie, Spanner utilise la version d'optimiseur définie au niveau de la base de données.

La valeur par défaut est ''.

▶ Exemple: Version de l'optimiseur (cliquez pour développer)

L'exemple suivant montre comment exécuter des requêtes à l'aide d'une méthode la version de l'optimiseur Pilote JDBC Spanner.

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

Une propriété de type STRING indiquant l'état actuel Package de statistiques de l'optimiseur utilisée par cette connexion.

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

Définit le package de statistiques de l'optimiseur à utiliser pour toutes les instructions suivantes concernant la connexion. <package> doit être un nom de package valide. Si aucun optimiseur Si le package de statistiques est défini, Spanner utilise les statistiques de l'optimiseur qui est défini au niveau de la base de données.

La valeur par défaut est ''.

▶ Exemple: Package de statistiques de l'optimiseur (cliquez pour développer)

L'exemple suivant montre comment exécuter des requêtes à l'aide d'un package de statistiques de l'optimiseur spécifique avec le pilote JDBC Spanner.

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

Une propriété de type BOOL indiquant si des statistiques doivent être renvoyées pour transactions sur cette connexion. Vous pouvez afficher les statistiques renvoyées en exécutant la commande SHOW VARIABLE COMMIT_RESPONSE.

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }

La valeur par défaut est false.

▶ Exemple: Statistiques sur le commit (cliquez pour développer)

L'exemple suivant montre comment afficher les statistiques de commit d'une transaction avec le pilote JDBC Spanner.

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

Une propriété de type STRING indiquant la priorité relative de Requêtes Spanner. La priorité sert d'indice programmeur Spanner et ne garantit pas l'ordre d'exécution.

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

'NULL' signifie qu'aucune indication ne doit être incluse dans la requête.

La valeur par défaut est 'NULL'.

Vous pouvez également utiliser une suggestion d'instruction pour spécifier la priorité RPC:

@{RPC_PRIORITY=PRIORITY_LOW} SELECT * FROM Albums

Pour en savoir plus, consultez la page Priority.

Tags

Les instructions suivantes permettent de gérer les tags de demande et de transaction.

STATEMENT_TAG

Propriété de type STRING contenant la balise de requête pour l'instruction suivante.

SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'

Définit le tag de requête pour l'exécution de l'instruction suivante. Une seule peut être définie par instruction. La balise ne couvre pas plusieurs instructions. cette doit être défini pour chaque instruction. Vous pouvez supprimer un tag de demande en le définissant à la chaîne vide ('').

La valeur par défaut est ''.

Vous pouvez définir à la fois des tags de transaction et des tags de relevé pour le même relevé.

Vous pouvez également utiliser une suggestion d'instruction pour ajouter un tag d'instruction :

@{STATEMENT_TAG='my-tag'} SELECT * FROM Albums

Pour en savoir plus, consultez la page Résoudre les problèmes liés aux tags de requête et aux tags de transaction.

▶ Exemple: Tags d'instruction (cliquez pour développer)

L'exemple suivant montre comment définir des balises d'instruction avec le paramètre Pilote JDBC Spanner.

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

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

TRANSACTION_TAG

Une propriété de type STRING qui contient le tag de transaction pour la prochaine transaction.

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

Définit le tag de transaction pour l'exécution de la transaction en cours. Vous ne pouvez définir qu'une seule balise par transaction. La balise ne s'applique pas à plusieurs transactions. Elle doit être définie par transaction. Vous pouvez supprimer un tag de transaction en le définissant sur la chaîne vide (''). Le tag de transaction doit être défini avant que des instructions n'aient été exécutées dans la transaction.

La valeur par défaut est ''.

Vous pouvez définir à la fois des tags de transaction et des tags de relevé pour le même relevé.

Pour en savoir plus, consultez la page Résoudre les problèmes liés aux tags de requête et aux tags de transaction.

▶ Exemple: Tags de transaction (cliquer pour développer)

L'exemple suivant montre comment définir des tags de transaction avec le pilote JDBC Spanner.

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;

Instructions de transaction

Les instructions suivantes gèrent et valident les transactions Spanner.

READ_TIMESTAMP

SHOW VARIABLE READ_TIMESTAMP

Renvoie un ensemble de résultats contenant une ligne et une colonne de type TIMESTAMP contenant l'horodatage de lecture de la transaction en lecture seule la plus récente. Cette instruction ne renvoie un horodatage que lorsqu'une transaction en lecture seule est toujours active et a exécuté au moins une requête, ou immédiatement après la validation d'une transaction en lecture seule et avant le début d'une nouvelle transaction. Sinon, le résultat est NULL.

▶ Exemple: Lire le code temporel (cliquer pour développer)

L'exemple suivant montre comment afficher le code temporel de la dernière lecture d'une en lecture seule avec le pilote JDBC Spanner.

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

Renvoie un ensemble de résultats contenant une ligne et une colonne de type TIMESTAMP contenant l'horodatage de commit de la dernière transaction en lecture/écriture Spanner validé. Cette instruction ne renvoie un code temporel que lorsque vous l'exécutez après avoir validé une transaction en lecture/écriture et avant d'exécuter toutes les instructions SELECT, DML ou de modification de schéma ultérieures. Sinon, le résultat est NULL.

▶ Exemple : code temporel de validation (cliquez pour développer)

L'exemple suivant montre comment afficher le dernier code temporel de validation pour une opération d'écriture avec le pilote JDBC Spanner.

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

Renvoie un ensemble de résultats avec une ligne et deux colonnes :

• COMMIT_TIMESTAMP (type=TIMESTAMP) indique quand la transaction la plus récente a été validée.
• MUTATION_COUNT (type=INT64) indique le nombre de mutations appliquées la transaction validée. Cette valeur est toujours vide en cas d'exécution sur le émulateur d'application.

Le nombre de mutations n'est disponible que si SET RETURN_COMMIT_STATS a été défini sur true avant la validation de la transaction.

▶ Exemple : Réponse de validation (cliquez pour développer)

L'exemple suivant montre comment afficher la réponse du dernier commit pour une une opération d'écriture avec le pilote JDBC Spanner.

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

Démarre une nouvelle transaction. Le mot clé TRANSACTION est facultatif.

• Utilisez COMMIT ou ROLLBACK pour mettre fin à une transaction.
• Si vous avez activé le mode AUTOCOMMIT, cette instruction désactive temporairement le mode AUTOCOMMIT sur la connexion. La connexion retrouve le mode AUTOCOMMIT à la fin de la transaction.
• Le mode de transaction est déterminé par le paramètre READONLY actuel de cette connexion. Cette valeur est définie à l'aide de la propriété SET READONLY = {TRUE | FALSE} .
• Le mode de transaction peut être modifié en exécutant SET TRANSACTION READ ONLY ou SET TRANSACTION READ WRITE directement après l'exécution de BEGIN [TRANSACTION].

Vous pouvez exécuter cette instruction lorsqu'aucune transaction n'est active.

▶ Exemple: DÉBUT DE LA TRANSACTION (cliquer pour développer)

L'exemple suivant montre comment démarrer différents types de transactions avec le pilote JDBC Spanner.

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

Valide la transaction actuelle. Le mot clé TRANSACTION est facultatif.

• La validation d'une transaction en lecture/écriture rend toutes les mises à jour de cette transaction visibles aux autres transactions et désactive tous les verrouillages associés sur Spanner.
• La validation d'une transaction en lecture seule met fin à la transaction en lecture seule actuelle. Toute nouvelle instruction démarre une nouvelle transaction. Il n'existe aucune différence sémantique entre COMMIT et ROLLBACK pour une transaction en lecture seule.

Vous ne pouvez exécuter cette instruction que lorsqu'une transaction est active.

▶ Exemple : COMMIT TRANSACTION (cliquez pour développer)

L'exemple suivant montre comment valider une transaction avec le Pilote JDBC Spanner.

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

Annule (ROLLBACK) la transaction actuelle. Le mot clé TRANSACTION est (facultatif).

• Effectuer une opération ROLLBACK d'une transaction en lecture/écriture efface tout élément mis en mémoire tampon mutations, effectue un rollback de la transaction sur Spanner verrouille la transaction.
• L'annulation (ROLLBACK) d'une transaction en lecture seule met fin à la transaction en lecture seule actuelle. Toute instruction ultérieure démarre une nouvelle transaction. Il n'existe aucune différence sémantique entre COMMIT et ROLLBACK pour une transaction en lecture seule sur une connexion.

Vous ne pouvez exécuter cette instruction que lorsqu'une transaction est active.

▶ Exemple : ROLLBACK TRANSACTION (cliquez pour développer)

L'exemple suivant montre comment annuler une transaction avec le pilote JDBC Spanner.

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

Définit le mode de transaction pour la transaction en cours.

Vous ne pouvez exécuter cette instruction que lorsque AUTOCOMMIT est défini sur false, ou si vous avez a démarré une transaction en exécutant BEGIN [TRANSACTION] et n'ont pas encore exécuté toutes les instructions de la transaction.

Cette instruction définit le mode de transaction pour la transaction en cours uniquement. Quand ? la transaction est validée ou annulée, la transaction suivante utilise pour la connexion (voir SET READONLY).

Remarque : Vous ne pouvez pas définir le mode de transaction sur READ WRITE si la connexion est en mode READ ONLY.

▶ Exemple: DÉFINIR LA TRANSACTION (cliquer pour développer)

L'exemple suivant montre comment définir les caractéristiques des transactions avec le pilote JDBC Spanner.

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

Instructions par lots

Les instructions suivantes gèrent des lots d'instructions LDD et les envoient dans Spanner.

START BATCH DDL

START BATCH DDL

Démarre un lot d'instructions LDD sur la connexion. Toutes les instructions suivantes du lot doivent être des instructions LDD. Les instructions LDD sont mises en mémoire tampon localement et envoyées à Spanner en tant que lot lorsque vous exécutez RUN BATCH. L'exécution simultanée de plusieurs instructions LDD est généralement plus rapide que l'exécution des instructions séparément.

Vous pouvez exécuter cette instruction lorsqu'aucune transaction n'est active.

▶ Exemple : lot de commandes DDL (cliquez pour développer)

L'exemple suivant montre comment exécuter un lot DDL avec le pilote JDBC Spanner.

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

Envoie toutes les instructions LDD mises en mémoire tampon du lot LDD actuel à la base de données. attend que Spanner exécute ces instructions et met fin au du lot LDD actuel.

Si Spanner ne peut pas exécuter au moins une instruction LDD, RUN BATCH renvoie une erreur pour la première instruction LDD que Spanner ne peut pas exécuter. Sinon, RUN BATCH renvoie un résultat positif.

Remarque :Si une instruction LDD du lot renvoie une erreur, Spanner peut avoir appliqué les instructions LDD précédentes du même lot au de la base de données.

ABORD LOT [TRANSACTION]

Efface toutes les instructions LDD mises en mémoire tampon dans le lot LDD actuel et met fin au lot.

Vous ne pouvez exécuter cette instruction que lorsqu'un lot LDD est actif. Vous pouvez utiliser ABORT BATCH, indépendamment du fait que le lot comprenne des instructions LDD mises en mémoire tampon. Toutes les instructions LDD précédentes dans le lot seront annulées.

▶ Exemple : Arrêter le lot de LDD (cliquez pour développer)

L'exemple suivant montre comment interrompre un lot DDL avec le pilote JDBC Spanner.

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

START BATCH DML et RUN Batch

Les instructions suivantes regroupent les deux instructions LMD et les envoient dans un seul appel au serveur. Un lot LMD peut être exécuté dans le cadre d'une transaction ou en mode autocommit.

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

▶ Exemple : lot de LMD (cliquez pour développer)

L'exemple suivant montre comment exécuter un lot DML avec le pilote JDBC Spanner.

-- 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 et instructions de requête partitionnées

L'API partitionQuery divise une requête en fragments plus petits, ou partitions, et utilise plusieurs machines pour extraire les partitions en parallèle. Chaque partition est identifiée par un jeton de partition. L'API PartitionQuery présente une latence plus élevée que l'API de requêtes standard, car elle n'est destinée qu'aux opérations groupées telles que l'exportation ou l'analyse de l'ensemble de la base de données.

Data Boost vous permet d'exécuter des requêtes d'analyse et des exportations de données avec une sur les charges de travail existantes de l'instance Spanner provisionnée. Data Boost n'est compatible qu'avec les requêtes partitionnées.

Vous pouvez activer Data Boost avec l'instruction SET DATA_BOOST_ENABLED.

Le pilote JDBC Spanner propose trois options pour exécuter des requêtes partitionnées :

• SET AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql suivi de plusieurs RUN PARTITION 'partition-token'

Chacune de ces méthodes est décrite dans les sections suivantes.

DATA_BOOST_ENABLED

Une propriété de type BOOL indiquant si cette connexion doit utiliser Data Boost pour les requêtes partitionnées La valeur par défaut est false.

SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

▶ Exemple : Exécuter une requête à l'aide de Data Boost (cliquez pour développer)

L'exemple suivant montre comment exécuter une requête utilisant Data Boost avec la méthode Pilote JDBC Spanner.

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

Pour obtenir un exemple complet, consultez DataBoostExample.

AUTO_PARTITION_MODE

Une propriété de type BOOL indiquant si la connexion utilise automatiquement les requêtes partitionnées pour toutes les requêtes exécutées.

SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}

• Définissez cette variable sur true si vous souhaitez que la connexion utilise la requête partitionnée pour toutes les requêtes exécutées.
• Définissez également DATA_BOOST_ENABLED sur true si vous souhaitez que pour utiliser Data Boost requêtes.

La valeur par défaut est false.

▶ Exemple: Exécuter (cliquer pour développer)

Cet exemple exécute deux requêtes avec le pilote JDBC Spanner en utilisant Data Boost

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

Pour obtenir un exemple complet, consultez AutoPartitionModeExample.

EXÉCUTER LA REQUÊTE PARTITIONÉ

RUN PARTITIONED QUERY <sql>

Exécute une requête en tant que requête partitionnée sur Spanner. Assurez-vous que DATA_BOOST_ENABLED est défini sur true pour exécuter la requête avec Data Boost :

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

Le pilote JDBC Spanner partitionne la requête en interne et l'exécute. des partitions en parallèle. Les résultats sont fusionnés dans un seul ensemble de résultats et renvoyés à l'application. Vous pouvez définir le nombre de threads de calcul exécutant des partitions avec la variable MAX_PARTITIONED_PARALLELISM.

Pour obtenir un exemple complet, consultez RunPartitionedQueryExample.

PARTITION <SQL>

PARTITION <sql>

Crée une liste de partitions pour exécuter une requête sur Spanner et renvoie une liste de jetons de partition. Chaque jeton de partition peut être exécuté sur une connexion distincte sur le même client ou sur un autre à l'aide de la commande RUN PARTITION 'partition-token'.

▶ Exemple : Requête de partitionnement (cliquez pour développer)

L'exemple suivant montre comment partitionner une requête, puis exécuter chaque à l'aide du pilote JDBC Spanner.

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

Pour obtenir un exemple complet, consultez PartitionQueryExample.

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

Exécute une partition de requête précédemment renvoyée par PARTITION. . La commande peut être exécutée sur n'importe quelle connexion connectée à la même base de données que celle qui a créé les jetons de partition.

MAX_PARTITIONED_PARALLELISM

Propriété de type INT64 indiquant le nombre de threads de travail utilisés par le pilote JDBC Spanner pour exécuter des partitions. Cette valeur est utilisée pour:

• AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

Définit le nombre maximal de threads de calcul que le pilote JDBC Spanner. pour exécuter des partitions. Définir cette valeur sur 0 indique au pilote JDBC Spanner d'utiliser le nombre de cœurs de processeur sur la machine cliente comme valeur maximale.

La valeur par défaut est 0.

Commandes de point de sauvegarde

Les instructions suivantes activent et désactivent l'émulation savepoints dans les transactions. Vous pouvez créer un point de sauvegarde en appelant la méthode java.sql.Connection#setSavepoint() .

Le pilote JDBC Spanner émule des points de sauvegarde pour prendre en charge les frameworks pour les transactions imbriquées. Les points de sauvegarde sont émulés en effectuant un suivi d'une somme de contrôle en cours d'exécution pour les résultats qui ont été renvoyés par les instructions dans la transaction. Lors d'un rollback vers un point de sauvegarde, Le pilote JDBC Spanner effectue un rollback de la transaction, puis une nouvelle tentative transaction jusqu'au moment où le Savepoint a été défini. La somme de contrôle de la nouvelle tentative est comparée à celle de la transaction initiale pour vérifier que les mêmes résultats ont été renvoyés.

SAVEPOINT_SUPPORT

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

Propriété de type STRING indiquant la configuration SAVEPOINT_SUPPORT actuelle. Les valeurs possibles sont les suivantes :

• DISABLED: toutes les commandes Savepoint sont désactivées et échouent.
• FAIL_AFTER_ROLLBACK : les commandes de point d'arrêt sont activées. Effectuer un rollback vers un Savepoint restaure l'intégralité de la transaction. La transaction échoue si vous essayez pour utiliser la transaction après un rollback vers un point de sauvegarde.
• ENABLED : toutes les commandes de point de sauvegarde sont activées. Effectuer un rollback vers un point de sauvegarde effectue un rollback de la transaction et une nouvelle tentative est effectuée vers le point d'enregistrement. Ce échoue avec une erreur AbortedDueToConcurrentModificationException si les données sous-jacentes qui ont été utilisées par la transaction jusqu'au point de sauvegarde. a changé.

La valeur par défaut est FAIL_AFTER_ROLLBACK.

Vous ne pouvez modifier la valeur de cette variable que lorsqu'aucune transaction n'est active.

▶ Exemple : Prise en charge des points de sauvegarde (cliquez pour développer)

L'exemple suivant montre comment activer et désactiver la prise en charge des points de sauvegarde dans le pilote JDBC Spanner.

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

Étape suivante

Découvrez comment connecter JDBC à une base de données à dialecte GoogleSQL.