Comandi di gestione delle sessioni JDBC (GoogleSQL)

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

I seguenti comandi si applicano ai database dialetti SQL di Google.

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

Istruzioni di connessione

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

READONLY

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

SHOW VARIABLE READONLY
SET READONLY = { true | false }

Puoi modificare il valore di questa proprietà solo se non ci sono transazioni attive.

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

COMMIT AUTOMATICO

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

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

Puoi modificare il valore di questa proprietà solo se non ci sono transazioni attive.

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

▶ Esempio: commit automatico (fai clic per espandere)

L'esempio seguente mostra come utilizzare la proprietà 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 = FALSE;

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

RETRY_ABORTS_INTERNALLY

Un valore booleano che indica se la connessione riprova automaticamente a eseguire le transazioni interrotte. Il valore predefinito è true.

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }

Puoi modificare il valore di questa proprietà solo dopo l'inizio di una transazione (vedi BEGIN TRANSACTION) e prima che vengano eseguite istruzioni all'interno della transazione.

Se imposti RETRY_ABORTS_INTERNALLY su true, la connessione conserva un checksum di tutti i dati che la connessione restituisce all'applicazione client. Viene utilizzato per ritentare 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à alle transazioni interrotte.

AUTOCOMMIT_DML_MODE

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

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

I valori possibili sono:

• In modalità TRANSACTIONAL, il driver esegue le istruzioni DML come transazioni atomiche separate. Il conducente crea una nuova transazione, esegue l'istruzione DML ed esegue il commit della transazione una volta completata l'esecuzione oppure 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 aggiornamento partizionata può essere eseguita come una serie di transazioni, ognuna delle quali copre un sottoinsieme di righe interessate. L'istruzione partizionata fornisce una semantica indebolita in cambio di una migliore scalabilità e prestazioni.

Il valore predefinito è TRANSACTIONAL.

▶ Esempio: DML partizionato (fai clic per espandere)

L'esempio seguente mostra come eseguire DML partizionato utilizzando il driver JDBC di 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

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

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

Il valore INT64 è un numero intero seguito da un suffisso che indica l'unità di tempo. Un valore NULL indica che non è stato impostato alcun valore di timeout. Se è stato impostato un valore di timeout dell'istruzione, le istruzioni che richiedono più tempo del valore di timeout specificato causeranno un errore java.sql.SQLTimeoutException e annulleranno la transazione.

Le unità di tempo supportate sono:

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

Il valore predefinito è NULL, il che significa che non è impostato alcun valore di timeout.

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

READ_ONLY_STALENESS

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

Il valore di inattività di sola lettura si applica a tutte le successive transazioni di sola lettura e a tutte le query in modalità AUTOCOMMIT.

Il valore predefinito è STRONG.

Le opzioni associate al timestamp sono le seguenti:

• STRONG indica a Spanner di eseguire una lettura efficace.
• MAX_STALENESS definisce l'intervallo di tempo utilizzato da Spanner per eseguire una lettura di inattività limitata, relativa a now().
• MIN_READ_TIMESTAMP definisce il tempo assoluto utilizzato da Spanner per eseguire una lettura di inattività limitata.
• EXACT_STALENESS definisce l'intervallo di tempo utilizzato da Spanner per eseguire una lettura di inattività esatta, relativo a now().
• READ_TIMESTAMP definisce il tempo assoluto utilizzato da Spanner per eseguire una lettura di 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 se non sono presenti transazioni attive.

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

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

L'esempio seguente mostra come eseguire query utilizzando un valore di inattività personalizzato con il driver JDBC di 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

Una proprietà di tipo STRING che indica la versione dello strumento di ottimizzazione. La versione è un numero intero o "LATEST".

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

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

Il valore predefinito è ''.

▶ Esempio: versione dell'ottimizzatore (fai clic per espandere)

L'esempio seguente mostra come eseguire query utilizzando una versione di ottimizzazione specifica con il driver JDBC di 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

Una proprietà di tipo STRING che indica l'attuale pacchetto di statistiche di ottimizzazione utilizzato da questa connessione.

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

Imposta il pacchetto delle statistiche di ottimizzazione da utilizzare per tutte le seguenti istruzioni sulla connessione. <package> deve essere un nome di pacchetto valido. Se non viene impostato alcun pacchetto di statistiche di ottimizzazione, Spanner utilizza il pacchetto di statistiche di ottimizzazione impostato a livello di database.

Il valore predefinito è ''.

▶ Esempio: pacchetto di statistiche di ottimizzazione (fare clic per espandere)

L'esempio seguente mostra come eseguire query utilizzando uno specifico pacchetto di statistiche di ottimizzazione con il driver 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

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

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }

Il valore predefinito è false.

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

L'esempio seguente mostra come visualizzare le statistiche di commit per una transazione con il driver JDBC di 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

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

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

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

Il valore predefinito è 'NULL'.

Per ulteriori informazioni, vedi Priority.

Tag

Le seguenti istruzioni gestiscono i tag di richiesta e transazione.

STATEMENT_TAG

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

SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'

Imposta il tag di richiesta per l'esecuzione successiva dell'istruzione. È possibile impostare un solo tag per istruzione. Il tag non copre più istruzioni, ma deve essere impostato per singole istruzioni. Un tag di richiesta può essere rimosso impostandolo sulla stringa vuota ('').

Il valore predefinito è ''.

Puoi impostare sia tag Transaction sia tag di istruzione per la stessa istruzione.

Per maggiori informazioni, consulta Risolvere i problemi con i tag di richiesta e le transazioni.

▶ Esempio: tag di istruzione (clic per espandere)

L'esempio seguente mostra come impostare tag di istruzioni con il driver JDBC di 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;

TRANSACTION_TAG

Una proprietà di tipo STRING contenente il tag transazioni per la transazione successiva.

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

Imposta il tag Transaction per l'esecuzione della transazione corrente. È possibile impostare un solo tag per transazione. Il tag non copre più transazioni, ma deve essere impostato per transazione. Un tag Transaction può essere rimosso impostandolo sulla stringa vuota (''). Il tag Transaction deve essere impostato prima di eseguire istruzioni nella transazione.

Il valore predefinito è ''.

Puoi impostare sia tag Transaction sia tag di istruzione per la stessa istruzione.

Per maggiori informazioni, consulta Risolvere i problemi con i tag di richiesta e le transazioni.

▶ Esempio: tag di transazione (clic per espandere)

L'esempio seguente mostra come impostare i tag di transazione con il driver JDBC di 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;

Estratti conto delle transazioni

Le istruzioni seguenti gestiscono ed eseguono il commit delle transazioni Spanner.

READ_TIMESTAMP

SHOW VARIABLE READ_TIMESTAMP

Restituisce un set 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 ed ha eseguito almeno una query oppure subito dopo il commit di una transazione di sola lettura e prima dell'avvio di una nuova transazione. In caso contrario, il risultato è NULL.

▶ Esempio: timestamp di lettura (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 di 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

Restituisce un set di risultati con una riga e una colonna di tipo TIMESTAMP contenente il timestamp di commit dell'ultima transazione di lettura-scrittura impegnata da Spanner. Questa istruzione restituisce un timestamp solo quando la esegui dopo aver eseguito il commit di una transazione di lettura-scrittura e prima di eseguire eventuali istruzioni SELECT, DML o di modifica dello schema successive. In caso contrario, il risultato è NULL.

▶ Esempio: timestamp di 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 di 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

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

• COMMIT_TIMESTAMP (type=TIMESTAMP) indica quando è stato eseguito il commit della transazione più recente.
• MUTATION_COUNT (type=INT64) indica quante mutazioni sono state applicate nella transazione impegnata. Questo valore è sempre vuoto se eseguito nell'emulatore.

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

▶ Esempio: conferma di una risposta (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 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;

INIZIA [TRANSAZIONE]

BEGIN [TRANSACTION]

Avvia una nuova transazione. La parola chiave TRANSACTION è facoltativa.

• Utilizza COMMIT o ROLLBACK per terminare una transazione.
• Se hai attivato la modalità AUTOCOMMIT, questa istruzione sostituisce temporaneamente la connessione dalla modalità AUTOCOMMIT. La connessione torna in modalità AUTOCOMMIT al termine della transazione.
• La modalità di transazione è determinata dall'impostazione READONLY corrente per questa connessione. Questo valore viene impostato utilizzando il comando SET READONLY = {TRUE | FALSE}.
• La modalità di transazione può essere modificata eseguendo SET TRANSACTION READ ONLY o SET TRANSACTION READ WRITE direttamente dopo l'esecuzione BEGIN [TRANSACTION].

Puoi eseguire questa istruzione solo se non ci sono transazioni attive.

▶ Esempio: INIZIA TRANSAZIONE (fai clic per espandere)

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

ISCRIVITI [TRANSAZIONE]

COMMIT [TRANSACTION]

Esegue il commit della transazione corrente. La parola chiave TRANSACTION è facoltativa.

• L'esecuzione di una transazione di lettura/scrittura rende tutti gli aggiornamenti di questa transazione visibili ad altre transazioni e rilascia tutti i blocchi della transazione su Spanner.
• L'esecuzione di una transazione di sola lettura termina l'attuale transazione di sola lettura. 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 se c'è una transazione attiva.

▶ Esempio: TRANSAZIONE DI COMMIT (fai clic per espandere)

L'esempio seguente mostra come eseguire il commit di una transazione con il driver JDBC di 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 [TRANSAZIONE]

ROLLBACK [TRANSACTION]

Esegue un ROLLBACK della transazione corrente. La parola chiave TRANSACTION è facoltativa.

• L'esecuzione di un ROLLBACK di una transazione di lettura-scrittura cancella le mutazioni nel buffer, esegue il rollback della transazione su Spanner e rilascia gli eventuali blocchi della transazione trattenuta.
• L'esecuzione di un ROLLBACK di una transazione di sola lettura termina l'attuale transazione di sola lettura. Eventuali istruzioni successive avviano una nuova transazione. Non esiste una differenza semantica tra COMMIT e ROLLBACK per una transazione di sola lettura su una connessione.

Puoi eseguire questa istruzione solo se c'è una transazione attiva.

▶ Esempio: ROLLBACK TRANSACTION (Fare clic per espandere)

L'esempio seguente mostra come eseguire il rollback di una transazione con il driver JDBC di 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;

IMPOSTA TRANSAZIONE

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] e non hai ancora eseguito alcuna istruzione nella transazione.

Questa istruzione imposta la modalità Transazione solo per la transazione corrente. Quando viene eseguito il commit o il rollback della transazione, la transazione successiva utilizza la modalità predefinita per la connessione (vedi SET READONLY).

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

▶ Esempio: IMPOSTA TRANSAZIONE (fai clic per espandere)

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

Istruzioni batch

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

AVVIA DDL 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 memorizzate nel buffer localmente e inviate a Spanner come un unico batch quando esegui RUN BATCH. L'esecuzione di più istruzioni DDL come un singolo batch è in genere più rapida rispetto all'esecuzione delle istruzioni separatamente.

Puoi eseguire questa istruzione solo se non ci sono transazioni attive.

▶ Esempio: batch DDL (fai clic per espandere)

L'esempio seguente mostra come eseguire un batch DDL con il driver JDBC di 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;

ESEGUI BATCH

RUN BATCH

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

Se Spanner non può eseguire almeno un'istruzione DDL, RUN BATCH restituisce un errore per la prima istruzione DDL che Spanner non è in grado di eseguire. In caso contrario, RUN BATCH restituisce correttamente.

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

ABBRACCIAMO IL BATCH [TRANSAZIONE]

Cancella tutte le istruzioni DDL memorizzate nel 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 istruzioni DDL con buffer. Tutte le istruzioni DDL precedenti nel batch verranno interrotte.

▶ Esempio: interruzione batch DDL (fai clic per espandere)

L'esempio seguente mostra come interrompere un batch DDL con il driver JDBC di 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;

AVVIA BATCH DML ed ESEGUI batch

Le seguenti istruzioni raggruppano le due istruzioni DML e le inviano in un'unica chiamata al server. Un batch DML può essere eseguito come parte 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 di 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 suddivide 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 maggiore rispetto all'API di query standard perché è destinata solo a operazioni collettive come l'esportazione o la scansione dell'intero database.

Data Boost ti consente di eseguire query di analisi ed esportazioni di dati con un impatto prossimo allo zero sui carichi di lavoro esistenti sull'istanza Spanner di cui è stato eseguito il provisioning. Data Boost supporta solo le query partizionate.

Puoi attivare Data Boost con l'istruzione SET DATA_BOOST_ENABLED.

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

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

Nelle sezioni seguenti sono descritti tutti questi metodi.

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 DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

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

L'esempio seguente mostra come eseguire una query utilizzando Data Boost con il driver JDBC di 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;

Per un esempio completo, consulta DataBoostExample.

AUTO_PARTITION_MODE

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

SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}

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

Il valore predefinito è false.

▶ Esempio: esecuzione (clic per espandere)

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

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

Per un esempio completo, consulta AutoPartitionModeExample.

ESEGUI QUERY Partizionata

RUN PARTITIONED QUERY <sql>

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

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

Il driver JDBC di Spanner esegue il partizionamento interno della query ed esegue le partizioni in parallelo. I risultati vengono uniti in un unico set di risultati e restituiti all'applicazione. Il numero di thread worker che eseguono partizioni può essere impostato con la variabile MAX_PARTITIONED_PARALLELISM.

Per un esempio completo, consulta RunPartitionedQueryExample.

PARTIZIONE <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 separata sullo stesso client o su un altro client utilizzando il comando RUN PARTITION 'partition-token'.

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

L'esempio seguente 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 PartitionQueryExample.

RUN PARTITION "partition-token"

RUN PARTITION 'partition-token'

Esegue una partizione di query che è stata restituita in precedenza dal comando PARTITION. Il comando può essere eseguito su qualsiasi connessione connessa allo stesso database del database che ha creato i token di partizione.

MAX_PARTITIONED_PARALLELISM

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

• AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

Imposta il numero massimo di thread worker che il driver JDBC di Spanner può utilizzare per eseguire le partizioni. L'impostazione di questo valore su 0 indica al driver JDBC di Spanner di utilizzare come massimo il numero di core della CPU sulla macchina client.

Il valore predefinito è 0.

Comandi Savepoint

Le seguenti istruzioni abilitano e disabilitano i punti di salvataggio emulati 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 framework che si basano su questi valori per le transazioni nidificate. I punti di salvataggio vengono emulati tenendo traccia di un checksum in esecuzione per i risultati restituiti dalle istruzioni nella transazione. Quando esegue il rollback a un punto di salvataggio, il driver JDBC di 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 nuovo tentativo viene confrontato con il checksum della transazione iniziale per verificare che siano stati restituiti gli stessi risultati.

SAVEPOINT_SUPPORT

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

Una proprietà di tipo STRING che indica l'attuale configurazione di SAVEPOINT_SUPPORT. I valori possibili sono:

• DISABLED: tutti i comandi del punto di salvataggio sono disabilitati e non andranno a buon fine.
• FAIL_AFTER_ROLLBACK: i comandi Savepoint 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 del punto di salvataggio sono abilitati. Il rollback a un punto di salvataggio comporterà il rollback della transazione e l'esecuzione di un nuovo tentativo nel punto di salvataggio. Questa operazione non riesce e viene restituito un errore AbortedDueToConcurrentModificationException se i dati sottostanti utilizzati dalla transazione fino al punto di salvataggio sono cambiati.

Il valore predefinito è FAIL_AFTER_ROLLBACK.

Puoi modificare il valore di questa variabile solo se non ci sono transazioni attive.

▶ Esempio: supporto Savepoint (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 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);
}

Passaggi successivi

Scopri come collegare JDBC a un database dialetto GoogleSQL.