Comandi di gestione della sessione JDBC (PostgreSQL)

Il driver JDBC di Spanner (Java Database Connectivity) supporta gli statement di gestione della sessione, che ti consentono di modificare lo stato della connessione, eseguire transazioni ed eseguire in modo efficiente batch di statement.

I seguenti comandi si applicano ai database con dialetto PostgreSQL.

Nota: puoi utilizzare le istruzioni di gestione della sessione solo con il driver JDBC Spanner. Le istruzioni di gestione della sessione non funzionano nelle librerie client, in Google Cloud CLI o nel driver JDBC creato da Simba.

Dichiarazioni di connessione

Le seguenti istruzioni apportano modifiche o mostrano le proprietà della connessione corrente.

SPANNER.READONLY

Un valore booleano che indica se la connessione è in modalità di sola lettura. Il valore predefinito è false.

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

Puoi modificare il valore di questa proprietà solo quando non è attiva alcuna transazione.

▶ Esempio: transazione di sola lettura (fai clic per espandere)

L'esempio seguente mostra come utilizzare questa proprietà per eseguire transazioni di sola lettura in Spanner.

SET SPANNER.READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;

-- The following two queries both use the read-only transaction.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title
FROM Albums
ORDER BY Title;

-- This shows the read timestamp that was used for the two queries.
SHOW SPANNER.READ_TIMESTAMP;

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

AUTOCOMMIT

Un valore booleano che indica se la connessione è in modalità di commit automatico. Il valore predefinito è true.

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

Puoi modificare il valore di questa proprietà solo quando non è presente alcuna transazione attiva.

Quando AUTOCOMMIT è impostato su false, viene avviata automaticamente una nuova transazione dopo l'esecuzione di COMMIT o ROLLBACK. La prima istruzione che esegui avvia la transazione.

▶ Esempio: impegno automatico (fai clic per espandere)

L'esempio seguente mostra come utilizzare la proprietà autocommit.

-- The default value for AUTOCOMMIT is true.
SHOW AUTOCOMMIT;

-- This insert statement is automatically committed after it is executed, as
-- the connection is in autocommit mode.
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);

-- Turning off autocommit means that a new transaction is automatically started
-- when the next statement is executed.
SET AUTOCOMMIT = FALSE;
-- The following statement starts a new transaction.
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);

-- This statement uses the same transaction as the previous statement.
INSERT INTO T (id, col_a, col_b) VALUES (3, 300, 3);

-- Commit the current transaction with the two INSERT statements.
COMMIT;

-- Transactions can also be executed in autocommit mode by executing the BEGIN
-- statement.
SET AUTOCOMMIT = FALSE;

-- Execute a transaction while in autocommit mode.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (4, 400, 4);
INSERT INTO T (id, col_a, col_b) VALUES (5, 500, 5);
COMMIT;

SPANNER.RETRY_ABORTS_INTERNALLY

Un valore booleano che indica se la connessione tenta automaticamente di nuovo le transazioni abortite. Il valore predefinito è true.

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

Puoi modificare il valore di questa proprietà solo dopo l'avvio di una transazione (vedi BEGIN TRANSACTION) e prima dell'esecuzione di qualsiasi istruzione all'interno della transazione.

Quando imposti SPANNER.RETRY_ABORTS_INTERNALLY su true, la connessione mantiene un controllo di tutti i dati che restituisce all'applicazione client. Viene utilizzato per riprovare la transazione se viene interrotta da Spanner.

Il valore predefinito è true. Ti consigliamo di impostare questo valore su false se la tua applicazione riprova già le transazioni interrotte.

SPANNER.AUTOCOMMIT_DML_MODE

Una proprietà STRING che indica la modalità di commit automatico per le istruzioni DML (Data Manipulation Language).

SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }

I valori possibili sono:

• In modalità TRANSACTIONAL, il driver esegue le istruzioni DML come transazioni atomiche separate. Il driver crea una nuova transazione, esegue l'istruzione DML e esegue il commit della transazione al termine dell'esecuzione o esegue il rollback della transazione in caso di errore.
• In modalità PARTITIONED_NON_ATOMIC, il driver esegue le istruzioni DML come istruzioni di aggiornamento partizionate. Un'istruzione di update partizionata può essere eseguita come una serie di molte transazioni, ciascuna che copre un sottoinsieme di righe interessate. L'istruzione partizionata fornisce una semantica indebolita in cambio di una maggiore scalabilità e prestazioni.

Il valore predefinito è TRANSACTIONAL.

▶ Esempio: DML partizionato (fai clic per espandere)

L'esempio seguente mostra come eseguire la DML partizionata utilizzando il driver JDBC Spanner.

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

Una proprietà di tipo STRING che indica il valore di timeout corrente per le istruzioni.

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

Il valore int8 è un numero intero seguito da un suffisso che indica l'unità di misura del tempo. DEFAULT significa 0 secondi, ovvero l'equivalente di nessun timeout. Un numero int8 senza unità indica millisecondi. Se è stato impostato un valore di timeout per le istruzioni, le istruzioni che richiedono più tempo del valore di timeout specificato causeranno un errore java.sql.SQLTimeoutException e invalideranno la transazione.

Le unità di tempo supportate sono:

• s: secondi
• ms: millisecondi
• us: microsecondi
• ns: nanosecondi

Il valore predefinito è 0, il che significa nessun timeout.

Un timeout dell'istruzione durante una transazione la rende non valida, tutte le istruzioni successive nella transazione non valida (tranne ROLLBACK) non vanno a buon fine e il driver JDBC Spanner genera un java.sql.SQLTimeoutException.

SPANNER.READ_ONLY_STALENESS

Una proprietà di tipo STRING che indica l'impostazione di inattività di sola lettura corrente utilizzata da Spanner per le query e le transazioni di sola lettura in modalità 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 }' }

Il valore read-only staleness si applica a tutte le transazioni di sola lettura successive e a tutte le query in modalità AUTOCOMMIT.

Il valore predefinito è STRONG.

Le opzioni di limite di timestamp sono le seguenti:

• STRONG indica a Spanner di eseguire una lettura sicura.
• MAX_STALENESS definisce l'intervallo di tempo utilizzato da Spanner per eseguire una lettura con invecchiamento limitato rispetto a now().
• MIN_READ_TIMESTAMP definisce un'ora assoluta utilizzata da Spanner per eseguire una lettura con tempo di aggiornamento limitato.
• EXACT_STALENESS definisce l'intervallo di tempo utilizzato da Spanner per eseguire una lettura dell'obsolescenza esatta rispetto a now().
• READ_TIMESTAMP definisce un momento assoluto utilizzato da Spanner per eseguire una lettura dell'obsolescenza esatta.

I timestamp devono utilizzare il seguente formato:

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

Le unità di tempo supportate per l'impostazione dei valori MAX_STALENESS e EXACT_STALENESS sono:

• s: secondi
• ms: millisecondi
• us: microsecondi
• ns: nanosecondi

Puoi modificare il valore di questa proprietà solo quando non è attiva alcuna transazione.

Nota: puoi utilizzare i valori MIN_READ_TIMESTAMP e MAX_STALENESS solo per le query in modalità AUTOCOMMIT.

▶ Esempio: inattività in sola lettura (fai clic per espandere)

L'esempio seguente mostra come eseguire query utilizzando un valore di inattività personalizzato con il driver JDBC Spanner.

-- Set the read-only staleness to MAX_STALENESS 10 seconds.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 10s';

-- Execute a query in auto-commit mode. This returns results that are up to
-- 10 seconds stale.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is only allowed for queries in autocommit mode.
-- Change the staleness to EXACT_STALENESS and start a read-only transaction.
SET SPANNER.READ_ONLY_STALENESS = 'EXACT_STALENESS 10s';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title, SingerId
FROM Albums
ORDER BY Title;

COMMIT;

-- Set the read staleness to an exact timestamp.
SET SPANNER.READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_VERSION

Una proprietà di tipo STRING che indica la versione dell'ottimizzatore. La versione è un numero intero o "LATEST".

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

Imposta la versione dell'ottimizzatore da utilizzare per tutte le seguenti istruzioni sulla connessione. Se la versione dell'ottimizzatore è impostata su '' (la stringa vuota), Spanner utilizza la versione più recente. Se non è impostata alcuna versione dell'ottimizzatore, Spanner utilizza la versione dell'ottimizzatore impostata a livello di database.

Il valore predefinito è ''.

▶ Esempio: versione dello strumento di ottimizzazione (fai clic per espandere)

L'esempio seguente mostra come eseguire query utilizzando una versione dell'ottimizzatore specifica con il driver JDBC Spanner.

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the latest optimizer version.
SET SPANNER.OPTIMIZER_VERSION = 'LATEST';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Revert back to using the default optimizer version that has been set for the
-- database.
SET SPANNER.OPTIMIZER_VERSION = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_STATISTICS_PACKAGE

Una proprietà di tipo STRING che indica il pacchetto di statistiche dello strumento di ottimizzazione corrente utilizzato da questa connessione.

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

Imposta il pacchetto di statistiche dello strumento di ottimizzazione da utilizzare per tutte le istruzioni successive sulla connessione. <package> deve essere un nome di pacchetto valido. Se non è impostato alcun pacchetto di statistiche dell'ottimizzatore, Spanner utilizza il pacchetto di statistiche dell'ottimizzatore impostato a livello di database.

Il valore predefinito è ''.

▶ Esempio: pacchetto di statistiche dello strumento di ottimizzazione (fai clic per espandere)

L'esempio seguente mostra come eseguire query utilizzando un pacchetto di statistiche dello strumento di ottimizzazione specifico con il driver JDBC di 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 SPANNER.OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the default optimizer statistics package.
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.RETURN_COMMIT_STATS

Una proprietà di tipo BOOL che indica se devono essere restituite statistiche per le transazioni su questa connessione. Puoi visualizzare le statistiche restituite eseguendo il comando SHOW SPANNER.COMMIT_RESPONSE.

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

Il valore predefinito è false.

▶ Esempio: statistiche sui commit (fai clic per espandere)

L'esempio seguente mostra come visualizzare le statistiche dei commit per una transazione con il driver JDBC Spanner.

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

Una proprietà di tipo STRING che indica la priorità relativa per le richieste Spanner. La priorità funge da suggerimento per lo schedulatore di Spanner e non garantisce l'ordine di esecuzione.

SHOW [VARIABLE] SPANNER.RPC_PRIORITY
SET SPANNER.RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

'NULL' indica che non è necessario includere alcun suggerimento nella richiesta.

Il valore predefinito è 'NULL'.

Puoi anche utilizzare un suggerimento di dichiarazione per specificare la priorità dell'RPC:

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

Per ulteriori informazioni, vedi Priority.

Tag

Le seguenti istruzioni gestiscono i tag di richiesta e di transazione.

SPANNER.STATEMENT_TAG

Una proprietà di tipo STRING che contiene il tag di richiesta per l'istruzione successiva.

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

Imposta il tag di richiesta per l'istruzione successiva da eseguire. È possibile impostare un solo tag per istruzione. Il tag non si estende su più istruzioni; deve essere impostato su base per istruzione. Un tag richiesta può essere rimosso impostandolo sulla stringa vuota ('').

Il valore predefinito è ''.

Puoi impostare sia i tag transazioni che i tag estratto conto per lo stesso estratto conto.

Puoi anche utilizzare un suggerimento per l'istruzione per aggiungere un tag istruzione:

/*@STATEMENT_TAG='my-tag'*/ SELECT * FROM Albums

Per ulteriori informazioni, consulta la sezione Risolvere i problemi relativi ai tag di richiesta e di transazione.

▶ Esempio: tag dichiarazione (fai clic per espandere)

L'esempio seguente mostra come impostare i tag di istruzioni con il driver JDBC Spanner.

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

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

-- Set a statement tag with a query hint.
/*@STATEMENT_TAG='tag3'*/
SELECT TrackNumber, Title
FROM Tracks
WHERE AlbumId=1 AND SingerId=1
ORDER BY TrackNumber;

SPANNER.TRANSACTION_TAG

Una proprietà di tipo STRING che contiene il tag transazione per la transazione successiva.

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

Imposta il tag transazione per la transazione corrente da eseguire. È possibile impostare un solo tag per transazione. Il tag non si applica a più transazioni, ma deve essere impostato su base transazionale. Un tag transazione può essere rimosso impostandolo sulla stringa vuota (''). Il tag transazione deve essere impostato prima che vengano eseguite istruzioni nella transazione.

Il valore predefinito è ''.

Puoi impostare sia i tag transazioni che i tag estratto conto per lo stesso estratto conto.

Per ulteriori informazioni, consulta la sezione Risolvere i problemi relativi ai tag di richiesta e di transazione.

▶ Esempio: tag transazione (fai clic per espandere)

Il seguente esempio mostra come impostare i tag transazioni con il driver JDBC Spanner.

BEGIN;
-- Set the transaction tag for the current transaction.
SET SPANNER.TRANSACTION_TAG = 'transaction-tag-1';

-- Set the statement tag that should be included with the next statement.
-- The statement will include both the statement tag and the transaction tag.
SET SPANNER.STATEMENT_TAG = 'select-statement';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

-- Set another tag for the next statement.
SET SPANNER.STATEMENT_TAG = 'insert-statement';
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

-- The transaction tag property is cleared when the transaction finishes.
SHOW SPANNER.TRANSACTION_TAG;

Estratti conto delle transazioni

Le seguenti istruzioni gestiscono e confermano le transazioni Spanner.

LIVELLO DI ISOLAMENTO DELLE TRANSAZIONI

SHOW [VARIABLE] TRANSACTION ISOLATION LEVEL

Restituisce un set di risultati con una riga e una colonna di tipo STRING. Il valore restituito è sempre serializable.

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

Restituisce un insieme di risultati con una riga e una colonna di tipo TIMESTAMP contenente il timestamp di lettura della transazione di sola lettura più recente. Questa istruzione restituisce un timestamp solo quando una transazione di sola lettura è ancora attiva e ha eseguito almeno una query oppure immediatamente dopo il commit di una transazione di sola lettura e prima dell'inizio di una nuova transazione. In caso contrario, il risultato è NULL.

▶ Esempio: leggi timestamp (fai clic per espandere)

L'esempio seguente mostra come visualizzare l'ultimo timestamp di lettura per un'operazione di sola lettura con il driver 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 SPANNER.READ_TIMESTAMP;

-- Set a non-deterministic read-only staleness and execute the same query.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 20s';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp that was used for the previous query. The timestamp
-- is determined by Spanner, and is guaranteed to be no less than
-- 20 seconds stale.
SHOW SPANNER.READ_TIMESTAMP;

-- The read timestamp of a read-only transaction can also be retrieved.
SET SPANNER.READ_ONLY_STALENESS = 'STRONG';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp of the current read-only transaction. All queries in
-- this transaction will use this read timestamp.
SHOW SPANNER.READ_TIMESTAMP;

SELECT Title
FROM Albums
ORDER BY Title;

-- The read timestamp is the same as for the previous query, as all queries in
-- the same transaction use the same read timestamp.
SHOW SPANNER.READ_TIMESTAMP;

COMMIT;

SPANNER.COMMIT_TIMESTAMP

SHOW [VARIABLE] SPANNER.COMMIT_TIMESTAMP

Restituisce un insieme di risultati con una riga e una colonna di tipo TIMESTAMP contenente il timestamp del commit dell'ultima transazione di lettura/scrittura eseguita da Spanner. Questa istruzione restituisce un timestamp solo se la esecuti dopo aver eseguito l'commit di una transazione di lettura/scrittura e prima di eseguire qualsiasi istruzione SELECT, DML o di modifica dello schema successiva. In caso contrario, il risultato è NULL.

▶ Esempio: timestamp commit (fai clic per espandere)

L'esempio seguente mostra come visualizzare il timestamp dell'ultimo commit per un'operazione di scrittura con il driver 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 SPANNER.COMMIT_TIMESTAMP;

SPANNER.COMMIT_RESPONSE

SHOW [VARIABLE] SPANNER.COMMIT_RESPONSE

Restituisce un set di risultati con una riga e due colonne:

• COMMIT_TIMESTAMP (type=TIMESTAMP) indica quando è stata eseguita la transazione più recente.
• MUTATION_COUNT (type=INT64) indica quante mutazioni sono state applicate nella transazione impegnata. Questo valore è sempre vuoto quando viene eseguito sull'emulatore.

Il conteggio delle mutazioni è disponibile solo se SET SPANNER.RETURN_COMMIT_STATS è stato impostato su true prima del commit della transazione.

▶ Esempio: risposta al commit (fai clic per espandere)

L'esempio seguente mostra come visualizzare l'ultima risposta del commit per un'operazione di scrittura con il driver JDBC di Spanner.

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

Avvia una nuova transazione. Le parole chiave TRANSACTION e WORK sono facoltative, equivalenti e non hanno alcun effetto.

• Usa COMMIT o ROLLBACK per terminare una transazione.
• Se hai attivato la modalità AUTOCOMMIT, questa istruzione interrompe temporaneamente la connessione dalla modalità AUTOCOMMIT. La connessione torna alla modalità AUTOCOMMIT al termine della transazione.
• Se non viene specificato READ ONLY o READ WRITE, la modalità di transazione è determinata dalla modalità di transazione predefinita della sessione. Questo valore predefinito viene impostato utilizzando il comando SET SESSION CHARACTERISTICS AS TRANSACTION o impostando la variabile READONLY.

Puoi eseguire questa istruzione solo quando non è in corso alcuna transazione.

▶ Esempio: BEGIN TRANSACTION (fai clic per espandere)

L'esempio seguente mostra come avviare diversi tipi di transazioni con il driver 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;

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

COMMIT [TRANSACTION | WORK]

COMMIT [ TRANSACTION | WORK ]

Esegue il commit della transazione corrente. Le parole chiave TRANSACTION e WORK sono facoltative ed equivalenti e non hanno alcun effetto.

• L'commit di una transazione di lettura-scrittura rende visibili tutti gli aggiornamenti di questa transazione alle altre transazioni e rilascia tutti i blocchi della transazione su Spanner.
• L'commit di una transazione di sola lettura termina la transazione di sola lettura corrente. Qualsiasi istruzione successiva avvia una nuova transazione. Non esiste alcuna differenza semantica tra COMMIT e ROLLBACK per una transazione di sola lettura.

Puoi eseguire questa istruzione solo quando è presente una transazione attiva.

▶ Esempio: COMMIT TRANSACTION (fai clic per espandere)

L'esempio seguente mostra come eseguire il commit di una transazione con il driver 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 READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

{ ABORT | ROLLBACK } [TRANSACTION | WORK]

{ ABORT | ROLLBACK } [TRANSACTION | WORK]

Esegue un ROLLBACK della transazione corrente. Le parole chiave TRANSACTION e WORK sono facoltative ed equivalenti e non hanno alcun effetto.

• L'esecuzione di un ROLLBACK di una transazione di lettura-scrittura cancella tutte le mutazioni messe in buffer, esegue il rollback della transazione su Spanner e rilascia tutti i blocchi detenuti dalla transazione.
• L'esecuzione di un ROLLBACK di una transazione di sola lettura termina la transazione di sola lettura corrente. Tutti gli eventuali comandi successivi avviano una nuova transazione. Non esiste alcuna differenza semantica tra COMMIT e ROLLBACK per una transazione di sola lettura su una connessione.

Puoi eseguire questa istruzione solo quando è presente una transazione attiva.

▶ Esempio: ROLLBACK TRANSACTION (fai clic per espandere)

L'esempio seguente mostra come eseguire il rollback di una transazione con il driver 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 READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Imposta la modalità di transazione per la transazione corrente.

Puoi eseguire questa istruzione solo quando AUTOCOMMIT è false o se hai avviato una transazione eseguendo BEGIN [TRANSACTION | WORK] e non hai ancora eseguito istruzioni nella transazione.

Questa istruzione imposta la modalità di transazione solo per la transazione corrente. Quando la transazione viene confermata o annullata, la transazione successiva utilizza la modalità predefinita per la connessione. (vedi SET SESSION CHARACTERISTICS).

Nota: non puoi impostare la modalità di transazione su READ WRITE se la connessione è in modalità READ ONLY.

▶ Esempio: SET TRANSACTION (fai clic per espandere)

L'esempio seguente mostra come impostare le caratteristiche delle transazioni con il driver 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;

IMPOSTARE LE CARATTERISTICHE DELLA SESSIONE

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

Imposta la modalità di transazione predefinita per le transazioni nella sessione su READ ONLY o READ WRITE. Questa istruzione è consentita solo quando non è presente alcuna transazione attiva.

Il comando SET TRANSACTION può avere la priorità su questa impostazione.

Istruzioni batch

Le seguenti istruzioni gestiscono batch di istruzioni DDL e li inviano a Spanner.

DDL START BATCH

START BATCH DDL

Avvia un batch di istruzioni DDL sulla connessione. Tutte le istruzioni successive durante il batch devono essere istruzioni DDL. Le istruzioni DDL vengono messe in buffer localmente e inviate a Spanner come un unico batch quando esegui RUN BATCH. L'esecuzione di più istruzioni DDL come un unico batch è in genere più veloce dell'esecuzione delle istruzioni separatamente.

Puoi eseguire questa istruzione solo quando non è in corso alcuna transazione.

▶ Esempio: batch DDL (fai clic per espandere)

L'esempio seguente mostra come eseguire un batch DDL con il driver 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  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

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

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

ESEGUI BATCH

RUN BATCH

Invia tutte le istruzioni DDL in buffer nel batch DDL corrente al database, attende che Spanner le esegua e termina il batch DDL corrente.

Se Spanner non riesce a eseguire almeno un'istruzione DDL, RUN BATCH restituisce un errore per la prima istruzione DDL che Spanner non riesce a eseguire. In caso contrario, RUN BATCH restituisce un valore corretto.

Nota: se un'istruzione DDL nel batch restituisce un errore, Spanner potrebbe aver comunque applicato al database le istruzioni DDL precedenti nello stesso batch.

ABORT BATCH

ABORT BATCH

Cancella tutte le istruzioni DDL in buffer nel batch DDL corrente e termina il batch.

Puoi eseguire questa istruzione solo quando è attivo un batch DDL. Puoi utilizzare ABORT BATCH indipendentemente dal fatto che il batch abbia o meno memorizzato nel buffer le istruzioni DDL. Tutti gli enunciati DDL precedenti nel batch verranno interrotti.

▶ Esempio: interrompi il batch DDL (fai clic per espandere)

L'esempio seguente mostra come interrompere un batch DDL con il driver 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  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

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

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

DML START BATCH e RUN BATCH

Le seguenti istruzioni raggruppano le due istruzioni DML e le inviano in una sola chiamata al server. Un batch DML può essere eseguito nell'ambito di una transazione o in modalità di commit automatico.

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

▶ Esempio: batch DML (fai clic per espandere)

L'esempio seguente mostra come eseguire un batch DML con il driver 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 e istruzioni di query partizionate

L'API partitionQuery divide una query in parti più piccole, o partizioni, e utilizza più macchine per recuperare le partizioni in parallelo. Ogni partizione è identificata da un token di partizione. L'API PartitionQuery ha una latenza più elevata rispetto all'API query standard, in quanto è destinata solo a operazioni collettive come l'esportazione o la scansione dell'intero database.

Data Boost consente di eseguire query di analisi ed esportazioni di dati con un impatto quasi nullo sui carichi di lavoro esistenti nell'istanza Spanner di cui è stato eseguito il provisioning. Data Boost supporta solo le query partizionate.

Puoi attivare Data Boost sulla connessione corrente con l'istruzione SET SPANNER.DATA_BOOST_ENABLED.

Il driver JDBC supporta tre alternative per l'esecuzione di query partizionate:

• SET SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql seguito da più RUN PARTITION 'partition-token'

Ciascuno di questi metodi è descritto nelle sezioni seguenti.

SPANNER.DATA_BOOST_ENABLED

Una proprietà di tipo BOOL che indica se questa connessione deve utilizzare Data Boost per le query partizionate. Il valore predefinito è false.

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

Imposta se questa connessione deve utilizzare Data Boost per le query partizionate.

Il valore predefinito è false.

▶ Esempio: esegui una query utilizzando Data Boost (fai clic per espandere)

L'esempio seguente mostra come eseguire una query utilizzando Data Boost con il driver JDBC Spanner.

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

Per un esempio completo, consulta PostgreSQL DataBoostExample.

SPANNER.AUTO_PARTITION_MODE

Una proprietà di tipo BOOL che indica se la connessione utilizza automaticamente query suddivise per tutte le query eseguite.

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

• Imposta questa variabile su true se vuoi che la connessione utilizzi la query partizionata per tutte le query eseguite.
• Imposta anche SPANNER.DATA_BOOST_ENABLED su true se vuoi che la connessione utilizzi Data Boost per tutte le query.

Il valore predefinito è false.

▶ Esempio: Esegui (fai clic per espandere)

Questo esempio esegue due query con il driver JDBC Spanner utilizzando Data Boost

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

Per un esempio completo, consulta PostgreSQL AutoPartitionModeExample.

ESEGUI QUERY PARTIZIONATA

RUN PARTITIONED QUERY <sql>

Esegue una query come query partizionata su Spanner. Assicurati che SPANNER.DATA_BOOST_ENABLED sia impostato su true per eseguire la query con Data Boost:

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

Il driver JDBC partiziona internamente la query ed esegue le partizioni in parallelo. I risultati vengono uniti in un unico insieme di risultati e restituiti all'applicazione. Il numero di thread worker che eseguono le partizioni può essere impostato con la variabile SPANNER.MAX_PARTITIONED_PARALLELISM.

Per un esempio completo, consulta PostgreSQL RunPartitionedQueryExample.

PARTITION <SQL>

PARTITION <sql>

Crea un elenco di partizioni per eseguire una query su Spanner e restituisce un elenco di token di partizione. Ogni token di partizione può essere eseguito su una connessione JDBC separata sullo stesso o su un altro host utilizzando il comando RUN PARTITION 'partition-token'.

▶ Esempio: query di partizione (fai clic per espandere)

Il seguente esempio mostra come partizionare una query ed eseguire ogni partizione separatamente utilizzando il driver JDBC di 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';

Per un esempio completo, consulta PostgreSQL PartitionQueryExample.

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

Esegue una partizione di query precedentemente restituita dal comando PARTITION. Il comando può essere eseguito su qualsiasi connessione JDBC collegata allo stesso database di quello che ha creato i token di partizione.

Per un esempio completo, consulta PostgreSQL PartitionQueryExample.

SPANNER.MAX_PARTITIONED_PARALLELISM

Una proprietà di tipo int8 che indica il numero di thread di lavoro utilizzati dal driver JDBC Spanner per eseguire le partizioni. Questo valore viene utilizzato per:

• SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW [VARIABLE] SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM = <int8>

Imposta il numero massimo di thread di lavoro che il driver JDBC di Spanner può utilizzare per eseguire le partizioni. Se imposti questo valore su 0, il driver JDBC Spanner utilizza il numero di core della CPU sulla macchina client come valore massimo.

Il valore predefinito è 0.

Comandi punto di salvataggio

Le seguenti istruzioni attivano e disattivano i punti di salvataggio simulati nelle transazioni. Puoi creare un punto di salvataggio chiamando il metodo java.sql.Connection#setSavepoint().

Il driver JDBC di Spanner emula i punti di salvataggio per supportare i framework che si basano su questi per le transazioni nidificate. I punti di salvataggio vengono emulati monitorando un checksum in esecuzione per i risultati restituiti dagli enunciati nella transazione. Quando esegui il rollback a un punto di salvataggio, il driver JDBC Spanner esegue il rollback della transazione e poi riprova la transazione fino al punto in cui è stato impostato il punto di salvataggio. Il checksum del retry viene confrontato con quello della transazione iniziale per verificare che siano stati restituiti gli stessi risultati.

SPANNER.SAVEPOINT_SUPPORT

SHOW [VARIABLE] SPANNER.SAVEPOINT_SUPPORT
SET SPANNER.SAVEPOINT_SUPPORT {TO|=} { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }

Una proprietà di tipo STRING che indica la configurazione SAVEPOINT_SUPPORT corrente. I valori possibili sono:

• DISABLED: tutti i comandi di punto di salvataggio sono disattivati e non andranno a buon fine.
• FAIL_AFTER_ROLLBACK: i comandi di punto di salvataggio sono abilitati. Il rollback a un punto di salvataggio comporta il rollback dell'intera transazione. La transazione non va a buon fine se provi a utilizzarla dopo il rollback a un punto di salvataggio.
• ENABLED: tutti i comandi di punto di salvataggio sono abilitati. Il rollback a un punto di salvataggio eseguirà il rollback della transazione e verrà eseguito un nuovo tentativo fino al punto di salvataggio. Questa operazione non va a buon fine con un errore AbortedDueToConcurrentModificationException se i dati sottostanti utilizzati dalla transazione fino al punto di salvataggio sono stati modificati.

Il valore predefinito è FAIL_AFTER_ROLLBACK.

Puoi modificare il valore di questa variabile solo quando non è attiva alcuna transazione.

▶ Esempio: supporto del punto di salvataggio (fai clic per espandere)

L'esempio seguente mostra come attivare e disattivare il supporto dei punti di salvataggio nel driver 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 SPANNER.SAVEPOINT_SUPPORT='DISABLED'");
  // The following statement fails because savepoints have been disabled.
  connection.setSavepoint("my_savepoint1");

  // Enables setting a savepoint and releasing a savepoint.
  // Rolling back to a savepoint is disabled.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='FAIL_AFTER_ROLLBACK'");
  Savepoint mySavepoint2 = connection.setSavepoint("my_savepoint2");
  connection.createStatement().execute("insert into my_table (id, value) values (1, 'One')");
  connection.releaseSavepoint(mySavepoint2);
  connection.commit();

  // Enables setting, releasing and rolling back to a savepoint.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='ENABLED'");
  Savepoint mySavepoint3 = connection.setSavepoint("my_savepoint3");
  connection.createStatement().execute("insert into my_table (id, value) values (2, 'Two')");
  connection.rollback(mySavepoint3);
}

Passaggi successivi

Scopri come collegare JDBC a un database in dialetto PostgreSQL.