Commandes de gestion des sessions PGAdapter

Spanner PGAdapter prend en charge les instructions de gestion de session, qui vous permettent de modifier l'état et le comportement de votre connexion, d'exécuter des transactions et d'exécuter efficacement des lots d'instructions. Toutes les instructions décrites dans ce document peuvent être utilisées avec n'importe quel client ou pilote qui se connecte à PGAdapter.

Pour en savoir plus, consultez la liste complète des pilotes et ORM PostgreSQL compatibles. Les commandes suivantes s'appliquent aux bases de données en dialecte PostgreSQL.

Pour en savoir plus sur l'utilisation de PGAdapter, consultez la section Démarrer PGAdapter.

Instructions de connexion

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

SPANNER.READONLY

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

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

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

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

L'exemple suivant montre comment utiliser cette propriété pour exécuter des transactions en lecture seule dans 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

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

REMARQUE: En règle générale, vous n'avez pas besoin de modifier la valeur de cette variable lorsque vous utilisez un pilote PostgreSQL avec PGAdapter. Ces pilotes gèrent automatiquement les transactions en exécutant BEGIN et COMMIT si nécessaire. Vous pouvez désactiver autocommit lorsque vous utilisez des outils de ligne de commande tels que psql pour éviter que les modifications de données accidentelles ne soient validées automatiquement.

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

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

Lorsque AUTOCOMMIT est défini sur "false", une nouvelle transaction est lancée automatiquement après l'exécution de 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 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

Valeur booléenne indiquant si la connexion relance automatiquement les transactions annulées. La valeur par défaut est true.

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

Vous ne pouvez exécuter cette commande qu'après le démarrage d'une transaction (voir BEGIN [TRANSACTION | WORK]) et avant l'exécution d'instructions dans la transaction.

Lorsque vous activez SPANNER.RETRY_ABORTS_INTERNALLY, la connexion conserve une somme de contrôle de toutes les données renvoyées à l'application cliente. Il permet de relancer la transaction si elle est interrompue par Spanner.

Ce paramètre est activé par défaut. Nous vous recommandons de désactiver ce paramètre si votre application exécute déjà de nouvelles tentatives de transactions annulées.

SPANNER.AUTOCOMMIT_DML_MODE

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

SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { '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 offre une sémantique affaiblie en échange d'une évolutivité et de performances améliorées.

La valeur par défaut est TRANSACTIONAL.

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

L'exemple suivant montre comment exécuter une instruction LMD partitionnée à l'aide de PGAdapter.

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

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

SHOW [VARIABLE] STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT {TO|=} { '<int8>{ s | ms | us | ns }' | <int8> | DEFAULT }

La valeur int8 est un nombre entier suivi d'un suffixe indiquant l'unité de temps. La valeur DEFAULT indique qu'aucune valeur n'a été définie pour le délai d'expiration. Si une valeur de délai d'expiration d'instruction a été définie, les instructions dont la durée dépasse le délai d'expiration spécifié génèrent une erreur d'expiration et invalident la transaction.

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

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

La valeur DEFAULT est de 0 seconde, ce qui signifie qu'il n'y a pas de délai avant expiration. Un nombre int8 sans unité indique int8 ms. Par exemple, les commandes suivantes définissent toutes les deux le délai avant expiration de l'instruction sur deux secondes.

SET STATEMENT_TIMEOUT TO 2000;
SET STATEMENT_TIMEOUT TO '2s';

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

READ_ONLY_STALENESS

Propriété de type STRING indiquant le paramètre d'obsolescence en lecture seule actuel que Spanner utilise pour les transactions et les requêtes en lecture seule en mode AUTOCOMMIT.

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

staleness_type:

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

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]D [[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 les requêtes en mode AUTOCOMMIT.

▶ Exemple: Obsolescence en lecture seule (cliquez pour développer)

L'exemple suivant montre comment exécuter des requêtes à l'aide d'une valeur d'obsolescence personnalisée avec 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

Propriété de type STRING indiquant la version de l'optimiseur. La version est numérique ou 'LATEST'.

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

Définit la version de l'optimiseur à utiliser pour toutes les instructions suivantes sur la connexion. Définir la version de l'optimiseur sur '' (chaîne vide) indique d'utiliser 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 version d'optimiseur spécifique avec 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

Propriété de type STRING indiquant le package de statistiques de l'optimiseur actuel utilisé par cette connexion.

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

Définit le package de statistiques de l'optimiseur à utiliser pour toutes les instructions suivantes sur la connexion. <package> doit être un nom de package valide. Si aucun package de statistiques d'optimiseur n'est défini, Spanner utilise le package de statistiques d'optimiseur 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 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

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

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

La valeur par défaut est false.

▶ Exemple: Statistiques sur les commits (cliquez pour développer)

L'exemple suivant montre comment afficher les statistiques de commit pour une transaction avec PGAdapter.

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

Propriété de type STRING indiquant la priorité relative des requêtes Spanner. La priorité sert d'indice au planificateur Spanner et ne garantit pas l'ordre d'exécution.

SHOW [VARIABLE] SPANNER.RPC_PRIORITY
SET SPANNER.RPC_PRIORITY {TO|=} {'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 indication d'instruction pour spécifier la priorité de l'appel RPC:

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

Pour en savoir plus, consultez la page Priority.

Instructions de transaction

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

NIVEAU D'ISOLATION DES TRANSACTIONS

SHOW [ VARIABLE ] TRANSACTION ISOLATION LEVEL

Renvoie un ensemble de résultats avec une ligne et une colonne de type STRING. La valeur renvoyée est toujours serializable, car il s'agit du seul niveau d'isolation compatible avec les bases de données Spanner utilisant le dialecte PostgreSQL.

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.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 (cliquez pour développer)

L'exemple suivant montre comment afficher l'horodatage de la dernière lecture pour une opération en lecture seule avec 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

Renvoie un ensemble de résultats contenant une ligne et une colonne de type TIMESTAMP contenant l'horodatage de validation de la dernière transaction en lecture/écriture validée par Spanner. Cette instruction ne renvoie un horodatage que lorsque vous l'exécutez après avoir validé une transaction en lecture/écriture et avant d'exécuter de nouvelles instructions SELECT, DML ou des instructions de modification du schéma. 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 commit pour une opération d'écriture avec PGAdapter.

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

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=int8) Indique le nombre de mutations appliquées dans la transaction validée. Cette valeur est toujours vide lors de l'exécution sur l'émulateur.

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

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

L'exemple suivant montre comment afficher la dernière réponse de validation pour une opération d'écriture avec PGAdapter.

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

Démarre une nouvelle transaction. Les mots clés TRANSACTION et WORK sont facultatifs, équivalents et n'ont aucun effet.

• 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.
• Si READ ONLY ou READ WRITE n'est pas spécifié, le mode de transaction est déterminé par le mode de transaction par défaut de la session. Cette valeur par défaut est définie à l'aide de la commande SET SESSION CHARACTERISTICS AS TRANSACTION.

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

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

L'exemple suivant montre comment démarrer différents types de transactions avec 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]

Valide la transaction actuelle. Les mots clés TRANSACTION et WORK sont facultatifs et équivalents, et n'ont aucun effet.

• 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 PGAdapter.

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

Annule (ROLLBACK) la transaction actuelle. Les mots clés TRANSACTION et WORK sont facultatifs et équivalents, et n'ont aucun effet.

• L'annulation (ROLLBACK) d'une transaction en lecture/écriture efface toutes les mutations mises en mémoire tampon, annule la transaction sur Spanner et désactive tous les verrouillages de 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 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 }

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

Vous ne pouvez exécuter cette instruction que lorsque AUTOCOMMIT est false ou si vous avez démarré une transaction en exécutant BEGIN [TRANSACTION | WORK] et que vous n'avez pas encore exécuté d'instructions dans cette transaction.

Cette instruction définit le mode de transaction pour la transaction en cours uniquement. Lorsque la transaction est validée ou annulée, la transaction suivante utilise le mode par défaut de la connexion. (voir SET SESSION CHARACTERISTICS).

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

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

L'exemple suivant montre comment définir les caractéristiques des transactions avec 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;

DÉFINIR LES CARACTÉRISTIQUES DE LA SESSION

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

Définit le mode de transaction par défaut pour les transactions de la session sur READ ONLY ou READ WRITE. Cette instruction n'est autorisée que lorsqu'aucune transaction n'est active.

La commande SET TRANSACTION peut remplacer ce paramètre.

▶ Exemple: SET SESSION CHARACTERISTICS (cliquez pour développer)

L'exemple suivant montre comment définir les caractéristiques de session avec 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

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

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

Définit la balise de requête pour l'instruction suivante à exécuter. Vous ne pouvez définir qu'une seule balise par instruction. La balise ne s'applique pas à plusieurs instructions. Elle doit être définie par instruction. Vous pouvez supprimer une balise de requête en la définissant sur 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: balises de déclaration (cliquez pour développer)

L'exemple suivant montre comment définir des balises d'instruction avec 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

Propriété de type STRING contenant la balise de transaction pour la transaction suivante.

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

Définit la balise de transaction pour la transaction en cours à exécuter. 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 (cliquez pour développer)

L'exemple suivant montre comment définir des tags de transaction avec 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;

Instructions par lots

Les instructions suivantes gèrent des lots d'instructions LDD et les envoient à 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 PGAdapter.

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

Envoie à la base de données toutes les instructions LDD mises en mémoire tampon du lot LDD actuel, attend que Spanner exécute ces instructions et met fin au 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 comprise dans le lot renvoie une erreur, il est possible que Spanner ait appliqué les instructions LDD précédentes du même lot à la base de données.

ABORT BATCH

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 du 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 PGAdapter.

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

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

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

Commandes de point de sauvegarde

Les points de sauvegarde dans PGAdapter sont émulés. Le rollback vers un point d'arrêt annule l'ensemble de la transaction et la réexécute jusqu'au point où le point d'arrêt a été défini. Cette opération échoue avec une erreur AbortedDueToConcurrentModificationException si les données sous-jacentes utilisées par la transaction jusqu'au point d'enregistrement ont changé.

La création et la libération de points de sauvegarde réussissent toujours lorsque la prise en charge des points de sauvegarde est activée.

Les instructions suivantes activent et désactivent les points de sauvegarde émulés dans les transactions.

SPANNER.SAVEPOINT_SUPPORT

SHOW [VARIABLE] SPANNER.SAVEPOINT_SUPPORT
SET SPANNER.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 de point de sauvegarde sont désactivées et échouent.
• FAIL_AFTER_ROLLBACK: les commandes de point d'arrêt sont activées. Le rollback vers un point d'enregistrement annule l'ensemble de la transaction. L'opération échoue si vous essayez d'utiliser la transaction après avoir effectué un rollback vers un point de sauvegarde.
• ENABLED: toutes les commandes de point d'arrêt sont activées. Le rollback vers un point de sauvegarde annule la transaction et une nouvelle tentative est effectuée au point de sauvegarde. Cette opération échoue avec une erreur AbortedDueToConcurrentModificationException si les données sous-jacentes utilisées par la transaction jusqu'au point d'enregistrement ont changé.

La valeur par défaut est ENABLED.

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

SAVEPOINT savepoint_name

SAVEPOINT savepoint-name;

SAVEPOINT crée un point de sauvegarde dans la transaction en cours. Une transaction peut être annulée jusqu'à un point de sauvegarde pour annuler toutes les opérations exécutées depuis la création du point de sauvegarde.

▶ Exemple: point de sauvegarde (cliquez pour développer)

L'exemple suivant montre comment utiliser des points de sauvegarde avec 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

Rétablit la transaction en cours au point de sauvegarde avec le nom spécifié.

Le rollback vers un point de sauvegarde n'est pas toujours possible. Le rollback vers un point d'arrêt annule l'intégralité de la transaction et la réexécute jusqu'au point où le point d'arrêt a été défini. Cette opération échouera avec un AbortedDueToConcurrentModificationException si les données sous-jacentes utilisées par la transaction jusqu'au point d'enregistrement ont changé.

RELEASE [SAVEPOINT] savepoint_name

RELEASE savepoint_name

Supprime le point de sauvegarde de la transaction en cours. Il ne peut plus être utilisé pour exécuter une instruction ROLLBACK TO savepoint_name.

Instructions préparées

Les instructions suivantes créent et exécutent des instructions préparées.

PRÉPARER

PREPARE statement_name [(data_type, ...)] AS statement

Prépare une instruction sur cette connexion. L'instruction est analysée et validée par Spanner, puis stockée en mémoire dans PGAdapter.

▶ Exemple: Instructions préparées (cliquez pour développer)

L'exemple suivant montre comment créer et exécuter des instructions préparées avec 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

EXECUTE statement_name [(value, ...)]

Exécute une instruction créée sur cette connexion avec PREPARE.

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

L'exemple suivant montre comment préparer et exécuter des instructions avec 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

Supprime une instruction préparée de cette connexion.

Copier

PGAdapter est compatible avec un sous-ensemble de la commande COPY PostgreSQL.

COPY nom_table FROM STDIN

COPY table_name FROM STDIN [BINARY]

Copier les données de stdin vers Spanner Il est plus efficace d'utiliser COPY pour importer un grand ensemble de données dans Spanner que d'exécuter des instructions INSERT.

COPY peut être combiné avec SPANNER.AUTOCOMMIT_DML_MODE pour exécuter une transaction non atomique. Cela permet à la transaction d'exécuter plus de mutations que la limite standard de mutation de transaction.

▶ Exemple: Copier (cliquez pour développer)

Les exemples suivants montrent comment copier des données vers et depuis Spanner avec PGAdapter.

create table numbers (number bigint not null primary key, name varchar);

Exécutez une opération COPY atomique:

cat numbers.txt | psql -h /tmp -d test-db -c "copy numbers from stdin;"

Exécutez une opération COPY non atomique:

cat numbers.txt | psql -h /tmp -d test-db \
  -c "set spanner.autocommit_dml_mode='partitioned_non_atomic'; copy numbers from stdin;"

Copiez des données de PostgreSQL vers 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;"

Cet exemple suppose que PostgreSQL s'exécute sur le port 5432 et que PGAdapter s'exécute sur le port 5433.

Pour en savoir plus, consultez PGAdapter : prise en charge de COPY.

COPY nom_table TO STDOUT [BINARY]

COPY table_name TO STDOUT [BINARY]

Copier les données d'une table ou d'une requête dans stdout

Data Boost et instructions de requête partitionnées

Data Boost vous permet d'exécuter des requêtes d'analyse et des exportations de données avec un impact quasiment nul sur les charges de travail existantes sur 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 SPANNER.DATA_BOOST_ENABLED.

PGAdapter propose trois options pour exécuter des requêtes partitionnées:

• SET SPANNER.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.

SPANNER.DATA_BOOST_ENABLED

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

Indique si cette connexion doit utiliser Data Boost pour les requêtes partitionnées.

La valeur par défaut est false.

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

L'exemple suivant montre comment effectuer une requête à l'aide de Data Boost avec PGAdapter.

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

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

• 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 SPANNER.DATA_BOOST_ENABLED sur true si vous souhaitez que la connexion utilise Data Boost pour toutes les requêtes.

La valeur par défaut est false.

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

Cet exemple exécute deux requêtes avec PGAdapter à l'aide de Data Boost.

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

EXÉCUTER LA REQUÊTE PARTITIONNÉE

RUN PARTITIONED QUERY <sql>

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

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

PGAdapter partitionne en interne la requête et exécute les partitions en parallèle. Les résultats sont fusionnés dans un seul ensemble de résultats et renvoyés à l'application. Le nombre de threads de calcul exécutant des partitions peut être défini avec la variable SPANNER.MAX_PARTITIONED_PARALLELISM.

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 la même instance PGAdapter ou sur une 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 partition séparément à l'aide de 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'

Exécute une partition de requête précédemment renvoyée par la commande 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.

SPANNER.MAX_PARTITIONED_PARALLELISM

Propriété de type bigint indiquant le nombre de threads de travail que PGAdapter utilise pour exécuter des partitions. Cette valeur est utilisée pour:

• SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM {TO|=} <bigint>

Définit le nombre maximal de threads de travail que PGAdapter peut utiliser pour exécuter des partitions. Définir cette valeur sur 0 indique à PGAdapter d'utiliser le nombre de cœurs de processeur de la machine cliente comme valeur maximale.

La valeur par défaut est 0.

Étape suivante

• Découvrez comment démarrer PGAdapter.
• Consultez la liste complète des pilotes et ORM PostgreSQL compatibles.