Comandos de gerenciamento de sessão do JDBC (GoogleSQL)

O driver JDBC do Spanner (Java Database Connectivity) é compatível com instruções de gerenciamento de sessão, que permitem modificar o estado da conexão, executar transações e executar lotes de instruções com eficiência.

Os comandos a seguir se aplicam aos bancos de dados do dialeto GoogleSQL.

Observação: só é possível usar instruções de gerenciamento de sessão com o driver JDBC do Spanner. As instruções de gerenciamento de sessão não funcionam nas bibliotecas de cliente, na Google Cloud CLI ou no driver JDBC criado pela Simba.

Instruções de conexão

As instruções a seguir alteram ou exibem as propriedades da conexão atual.

READONLY

Um booleano que indica se a conexão está no modo somente leitura. O padrão é false.

SHOW VARIABLE READONLY
SET READONLY = { true | false }

Só é possível alterar o valor dessa propriedade enquanto não há transação ativa.

▶ Exemplo: transação somente leitura (clique para expandir)

O exemplo a seguir mostra como usar essa propriedade para executar transações somente leitura no 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;

COMUNICADO AUTOMÁTICO

Um booleano que indica se a conexão está ou não no modo de confirmação automática. O padrão é true.

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

Só é possível alterar o valor dessa propriedade quando não há uma transação ativa.

Quando AUTOCOMMIT é definido como falso, uma nova transação é iniciada automaticamente depois que você executa COMMIT ou ROLLBACK. A primeira instrução executada inicia a transação.

▶ Exemplo: confirmação automática (clique para expandir)

O exemplo a seguir mostra como usar a propriedade 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

Um booleano que indica se a conexão tenta repetir automaticamente as transações canceladas. O padrão é true.

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }

Só é possível alterar o valor dessa propriedade após o início de uma transação (consulte BEGIN TRANSACTION) e antes que qualquer instrução seja executada dentro dela.

Quando você define RETRY_ABORTS_INTERNALLY como verdadeiro, a conexão mantém uma soma de verificação de todos os dados que a conexão retorna ao aplicativo cliente. Ele será usado para repetir a transação se ela for cancelada pelo Spanner.

O valor padrão é true. Recomendamos definir esse valor como false se o aplicativo já tentar realizar novamente as transações canceladas.

AUTOCOMMIT_DML_MODE

Uma propriedade STRING que indica o modo de confirmação automática para instruções de Linguagem de manipulação de dados (DML, na sigla em inglês).

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

Os valores possíveis são:

• No modo TRANSACTIONAL, o driver executa instruções DML como transações atômicas separadas. O driver cria uma nova transação, executa a instrução DML e realiza a confirmação da transação após a execução bem-sucedida ou reverte a transação no caso de um erro.
• No modo PARTITIONED_NON_ATOMIC, o driver executa instruções DML como instruções de atualização particionadas. Uma instrução de atualização particionada pode ser executada como uma série de muitas transações, cada uma cobrindo um subconjunto das linhas afetadas. A instrução particionada fornece uma semântica enfraquecida em troca de melhor escalonabilidade e desempenho.

O padrão é TRANSACTIONAL.

▶ Exemplo: DML particionada (clique para expandir)

O exemplo a seguir mostra como executar a DML particionada usando o driver JDBC do 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

Uma propriedade do tipo STRING indicando o valor de tempo limite atual para instruções.

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

O valor INT64 é um número inteiro seguido por um sufixo indicando a unidade de tempo. Um valor NULL indica que não há um valor de tempo limite definido. Se um valor de tempo limite da instrução tiver sido definido, as instruções que demorarem mais do que o tempo limite especificado vão causar um erro java.sql.SQLTimeoutException e invalidar a transação.

Os blocos de tempo compatíveis são estes:

• s: segundos
• ms: milésimos de segundo
• us: microssegundos
• ns: nanossegundos

O padrão é NULL, o que significa que nenhum valor de tempo limite foi definido.

Um tempo limite de instrução durante uma transação invalida a transação, todas as instruções subsequentes na transação invalidada (exceto ROLLBACK) falham e o driver JDBC do Spanner gera um java.sql.SQLTimeoutException.

READ_ONLY_STALENESS

Uma propriedade do tipo STRING que indica a configuração de inatividade somente leitura atual que o Spanner usa para transações somente leitura e consultas no modo 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 }' }

O valor de inatividade somente leitura se aplica a todas as transações somente leitura subsequentes e a todas as consultas no modo AUTOCOMMIT.

O padrão é STRONG.

As opções de limite de carimbo de data/hora são as seguintes:

• STRONG diz ao Spanner para executar uma leitura forte.
• MAX_STALENESS define o intervalo de tempo que o Spanner usa para executar uma leitura de inatividade limitada, em relação a now().
• MIN_READ_TIMESTAMP define um tempo absoluto que o Spanner usa para executar uma leitura de inatividade limitada.
• EXACT_STALENESS define o intervalo de tempo que o Spanner usa para executar uma leitura exata de inatividade, relativa a now().
• READ_TIMESTAMP define um tempo absoluto que o Spanner usa para executar uma leitura exata de inatividade.

Os carimbo de data/hora precisam usar o seguinte formato:

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

As unidades de tempo compatíveis para definir os valores MAX_STALENESS e EXACT_STALENESS são estes:

• s: segundos
• ms: milésimos de segundo
• us: microssegundos
• ns: nanossegundos

Só é possível modificar o valor dessa propriedade enquanto não houver uma transação ativa.

Observação: só é possível usar os valores MIN_READ_TIMESTAMP e MAX_STALENESS para consultas no modo AUTOCOMMIT.

▶ Exemplo: inatividade somente leitura (clique para expandir)

O exemplo a seguir mostra como executar consultas usando um valor de inatividade personalizado com o driver JDBC do 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

Uma propriedade do tipo STRING indicando a versão do otimizador. A versão é um número inteiro ou "LATEST".

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

Define a versão do otimizador a ser usada para todas as instruções a seguir na conexão. Se a versão do otimizador estiver definida como '' (a string vazia), o Spanner usará a versão mais recente. Se nenhuma versão do otimizador for definida, o Spanner usará a versão do otimizador definida no nível do banco de dados.

O padrão é ''.

▶ Exemplo: versão do otimizador (clique para expandir)

O exemplo a seguir mostra como executar consultas usando uma versão do otimizador específica com o driver JDBC do 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

Uma propriedade do tipo STRING indicando o pacote de estatísticas do otimizador atual usado por essa conexão.

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

Define o pacote de estatísticas do otimizador a ser usado em todas as instruções a seguir na conexão. <package> precisa ser um nome de pacote válido. Se nenhum pacote de estatísticas do otimizador for definido, o Spanner usará o pacote de estatísticas do otimizador definido no nível do banco de dados.

O padrão é ''.

▶ Exemplo: pacote de estatísticas do otimizador (clique para expandir)

O exemplo a seguir mostra como executar consultas usando um pacote de estatísticas do otimizador específico com o driver JDBC do 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

Uma propriedade do tipo BOOL que indica se as estatísticas precisam ser retornadas para transações nessa conexão. Para ver as estatísticas retornadas, execute o comando SHOW VARIABLE COMMIT_RESPONSE.

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }

O padrão é false.

▶ Exemplo: estatísticas de commit (clique para expandir)

O exemplo a seguir mostra como visualizar estatísticas de confirmação para uma transação com o driver JDBC do 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

Uma propriedade do tipo STRING que indica a prioridade relativa das solicitações do Spanner. A prioridade atua como uma dica para o programador do Spanner e não garante a ordem de execução.

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

'NULL' significa que nenhuma dica deve ser incluída na solicitação.

O padrão é 'NULL'.

Também é possível usar uma dica de instrução para especificar a prioridade da RPC:

@{RPC_PRIORITY=PRIORITY_LOW} SELECT * FROM Albums

Para mais informações, consulte Priority.

Tags

As instruções a seguir gerenciam tags de solicitação e transação.

STATEMENT_TAG

Uma propriedade do tipo STRING que contém a tag de solicitação para a próxima instrução.

SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'

Define a tag de solicitação para a próxima instrução a ser executada. Somente uma tag pode ser definida por instrução. A tag não abrange várias instruções. Ela deve ser definida por instrução. Para remover uma tag de solicitação, defina-a como a string vazia ('').

O padrão é ''.

É possível definir tags de transação e tags de instrução para a mesma instrução.

Você também pode usar uma dica de instrução para adicionar uma tag de instrução:

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

Para mais informações, consulte Resolver problemas com tags de solicitação e de transação.

▶ Exemplo: tags de instrução (clique para expandir)

O exemplo a seguir mostra como definir tags de instrução com o driver JDBC do Spanner.

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

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

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

TRANSACTION_TAG

Uma propriedade do tipo STRING que contém a tag para a próxima transação.

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

Define a tag da transação atual a ser executada. Somente uma tag pode ser definida por transação. A tag não abrange várias transações. Ela precisa ser definida por transação. Para remover uma tag de transação, defina-a como a string vazia (''). Ela precisa ser definida antes de executar qualquer instrução na transação.

O padrão é ''.

É possível definir tags de transação e tags de instrução para a mesma instrução.

Para mais informações, consulte Resolver problemas com tags de solicitação e de transação.

▶ Exemplo: tags de transação (clique para expandir)

O exemplo a seguir mostra como definir tags de transação com o driver JDBC do 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;

Instruções da transação

As instruções a seguir gerenciam e confirmam as transações do Spanner.

READ_TIMESTAMP

SHOW VARIABLE READ_TIMESTAMP

Retorna um conjunto de resultados com uma linha e uma coluna do tipo TIMESTAMP que contém a leitura do carimbo de data/hora da transação somente leitura mais recente. Essa instrução retorna um carimbo de data/hora apenas quando uma transação somente leitura ainda está ativa e executou pelo menos uma consulta ou imediatamente após uma transação somente leitura ser confirmada e antes de uma nova transação. Caso contrário, o resultado será NULL.

▶ Exemplo: leitura de carimbo de data/hora (clique para expandir)

O exemplo a seguir mostra como exibir o último carimbo de data/hora de leitura para uma operação somente leitura com o driver JDBC do 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

Retorna um conjunto de resultados com uma linha e uma coluna do tipo TIMESTAMP contendo o carimbo de data/hora de confirmação da última transação de leitura e gravação confirmada pelo Spanner. Essa instrução retorna um carimbo de data/hora somente quando você a executa depois de confirmar uma transação de leitura/gravação e antes de executar qualquer instrução SELECT, DML ou de alteração de esquema subsequente. Caso contrário, o resultado será NULL.

▶ Exemplo: carimbo de data/hora de confirmação (clique para expandir)

O exemplo a seguir mostra como visualizar o último carimbo de data/hora de confirmação de uma operação de gravação com o driver JDBC do 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

Retorna um conjunto de resultados com uma linha e duas colunas:

• COMMIT_TIMESTAMP (type=TIMESTAMP) indica quando a transação mais recente foi confirmada.
• MUTATION_COUNT (type=INT64) indica quantas mutações foram aplicadas na transação confirmada. Esse valor está sempre vazio quando executado no emulador.

A contagem de mutações estará disponível somente se SET RETURN_COMMIT_STATS tiver sido definido como true antes da confirmação da transação.

▶ Exemplo: resposta de confirmação (clique para expandir)

O exemplo a seguir mostra como visualizar a última resposta de confirmação para uma operação de gravação com o driver JDBC do Spanner.

-- Enable returning commit stats in addition to the commit timestamp.
SET RETURN_COMMIT_STATS = true;

-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);

-- Show the timestamp that the statement was committed.
SHOW VARIABLE COMMIT_RESPONSE;

BEGIN [TRANSACTION]

BEGIN [TRANSACTION]

Inicia uma nova transação. A palavra-chave TRANSACTION é opcional.

• Use COMMIT ou ROLLBACK para encerrar uma transação.
• Se você ativou o modo AUTOCOMMIT, esta instrução temporariamente remove a conexão do modo AUTOCOMMIT. A conexão retorna ao modo AUTOCOMMIT quando a transação termina.
• O modo de transação é determinado pela configuração atual de READONLY para essa conexão. Esse valor é definido usando o comando SET READONLY = {TRUE | FALSE}.
• O modo de transação pode ser alterado executando SET TRANSACTION READ ONLY ou SET TRANSACTION READ WRITE diretamente após a execução de BEGIN [TRANSACTION].

Execute esta instrução apenas enquanto não houver uma transação ativa.

▶ Exemplo: "BEGIN TRANSACTION" (clique para expandir)

O exemplo a seguir mostra como iniciar diferentes tipos de transações com o driver JDBC do Spanner.

-- This starts a transaction using the current defaults of this connection.
-- The value of READONLY determines whether the transaction is a
-- read-write or a read-only transaction.

BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Set READONLY to TRUE to use read-only transactions by default.
SET READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

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

COMMIT [TRANSACTION]

COMMIT [TRANSACTION]

Confirma a transação atual. A palavra-chave TRANSACTION é opcional.

• A confirmação de uma transação de leitura e gravação torna todas as atualizações dessa transação visíveis para outras transações e libera todos os bloqueios da transação no Spanner.
• A confirmação de uma transação somente leitura encerra a transação somente leitura atual. Qualquer instrução subsequente inicia uma nova transação. Não há diferença semântica entre COMMIT e ROLLBACK para uma transação somente leitura.

É possível executar essa instrução somente quando houver uma transação ativa.

▶ Exemplo: COMMIT TRANSACTION (clique para expandir)

O exemplo a seguir mostra como confirmar uma transação com o driver JDBC do Spanner.

-- Execute a regular read-write transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Execute a read-only transaction. Read-only transactions also need to be
-- either committed or rolled back in the Spanner JDBC driver in order
-- to mark the end of the transaction.
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

ROLLBACK [TRANSACTION]

ROLLBACK [TRANSACTION]

Executa um ROLLBACK da transação atual. A palavra-chave TRANSACTION é opcional.

• A execução de um ROLLBACK de uma transação de leitura/gravação limpa todas as mutações em buffer, reverte a transação no Spanner e libera todos os bloqueios que a transação manteve.
• Realizar um ROLLBACK de uma transação somente leitura encerra a transação somente leitura atual. Qualquer instrução subsequente inicia uma nova transação. Não há diferença semântica entre COMMIT e ROLLBACK para uma transação somente leitura em uma conexão.

É possível executar essa instrução somente quando houver uma transação ativa.

▶ Exemplo: ROLLBACK TRANSACTION (clique para expandir)

O exemplo a seguir mostra como reverter uma transação com o driver JDBC do Spanner.

-- Use ROLLBACK to undo the effects of a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
-- This ensures that the insert statement is not persisted in the database.
ROLLBACK;

-- Read-only transactions also need to be either committed or rolled back in the
-- Spanner JDBC driver in order to mark the end of the transaction.
-- There is no semantic difference between rolling back or committing a
-- read-only transaction.
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Define o modo de transação da transação atual.

Execute essa instrução somente quando AUTOCOMMIT for false ou se você tiver iniciado uma transação executando BEGIN [TRANSACTION] e ainda não tiver executado nenhuma instrução na transação.

Essa instrução define apenas o modo da transação atual. Quando a transação é confirmada ou revertida, a próxima transação usa o modo padrão para a conexão (consulte SET READONLY).

Observação: não é possível definir o modo de transação como READ WRITE se a conexão estiver no modo READ ONLY.

▶ Exemplo: SET TRANSACTION (Clique para expandir)

O exemplo a seguir mostra como definir características da transação com o driver JDBC do 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;

Instruções em lote

As instruções a seguir gerenciam lotes de instruções DDL e os enviam para o Spanner.

START BATCH DDL

START BATCH DDL

Inicia um lote de instruções DDL na conexão. Todas as instruções subsequentes durante o lote precisam ser instruções DDL. As instruções DDL são armazenadas em buffer localmente e enviadas ao Spanner como um lote quando você executa RUN BATCH. Executar várias instruções DDL como um lote é, geralmente, mais rápido do que executá-las separadamente.

Execute esta instrução apenas enquanto não houver uma transação ativa.

▶ Exemplo: lote DDL (clique para expandir)

O exemplo a seguir mostra como executar um lote DDL com o driver JDBC do Spanner.

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

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Singers (
  SingerId  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

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

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

RUN BATCH

RUN BATCH

Envia todas as instruções DDL armazenadas em buffer no lote DDL atual para o banco de dados, aguarda que o Spanner execute essas instruções e encerra o lote DDL atual.

Se o Spanner não puder executar pelo menos uma instrução DDL, RUN BATCH retornará um erro para a primeira instrução DDL que o Spanner não pode executar. Caso contrário, RUN BATCH retorna com sucesso.

Observação :se uma instrução DDL no lote retornar um erro, o Spanner ainda pode ter aplicado as instruções DDL anteriores no mesmo lote ao banco de dados.

CANCELAR LOTE [TRANSAÇÃO]

Limpa todas as instruções DDL armazenadas em buffer no lote DDL e encerra o lote.

Execute essa instrução somente quando um lote DDL estiver ativo. É possível usar ABORT BATCH independentemente do lote ter ou não instruções DDL armazenadas em buffer. Todas as instruções DDL anteriores no lote serão canceladas.

▶ Exemplo: cancelar lote DDL (clique para expandir)

O exemplo a seguir mostra como cancelar um lote DDL com o driver JDBC do 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;

INICIAR BATCH DML e EXECUTAR Lote

As instruções a seguir agrupam as duas instruções DML e as enviam em uma chamada para o servidor. Um lote DML pode ser executado como parte de uma transação ou no modo de confirmação automática.

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

▶ Exemplo: lote DML (clique para expandir)

O exemplo a seguir mostra como executar um lote de DML com o driver JDBC do 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 instruções de consulta particionadas

A API partitionQuery divide uma consulta em partes menores, ou partições, e usa várias máquinas para buscar as partições em paralelo. Cada partição é identificada por um token. A API PartitionQuery tem maior latência que a API de consulta padrão, porque se destina apenas a operações em massa, como exportar ou verificar todo o banco de dados.

Com o Otimização de dados, é possível executar consultas de análise e exportações de dados com impacto quase zero nas cargas de trabalho atuais na instância provisionada do Spanner. O Data Boost só é compatível com consultas particionadas.

É possível ativar o Data Boost com a instrução SET DATA_BOOST_ENABLED.

O driver JDBC do Spanner é compatível com três alternativas para a execução de consultas particionadas:

• SET AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql seguido por vários RUN PARTITION 'partition-token'

Cada um desses métodos é descrito nas seções a seguir.

DATA_BOOST_ENABLED

Uma propriedade do tipo BOOL que indica se essa conexão precisa usar Otimização de dados para consultas particionadas. O padrão é false.

SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

▶ Exemplo: executar uma consulta usando a otimização de dados (clique para expandir)

O exemplo a seguir mostra como fazer uma consulta usando o Data Boost com o driver JDBC do 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;

Para um exemplo completo, consulte DataBoostExample.

AUTO_PARTITION_MODE

Uma propriedade do tipo BOOL que indica se a conexão usa automaticamente consultas particionadas para todas as consultas executadas.

SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}

• Defina essa variável como true se quiser que a conexão use a consulta particionada para todas as consultas executadas.
• Defina também DATA_BOOST_ENABLED como true se quiser que a conexão use o Data Boost em todas as consultas.

O padrão é false.

▶ Exemplo: executar (clique para expandir)

Este exemplo executa duas consultas com o driver JDBC do Spanner usando o Data Boost

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

Para um exemplo completo, consulte AutoPartitionModeExample.

EXECUTAR CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

Executa uma consulta como uma consulta particionada no Spanner. Verifique se DATA_BOOST_ENABLED está definido como true para executar a consulta com o Google Boost:

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

O driver JDBC do Spanner particiona internamente a consulta e executa partições em paralelo. Os resultados são mesclados em um conjunto de resultados e retornados ao aplicativo. O número de linhas de execução de worker que executam partições pode ser definido com a variável MAX_PARTITIONED_PARALLELISM.

Para um exemplo completo, consulte RunPartitionedQueryExample.

PARTITION <SQL>

PARTITION <sql>

Cria uma lista de partições para executar uma consulta no Spanner e retorna uma lista de tokens de partição. Cada token de partição pode ser executado em uma conexão separada no mesmo cliente ou em outro usando o comando RUN PARTITION 'partition-token'.

▶ Exemplo: consulta de partição (clique para expandir)

O exemplo a seguir mostra como particionar uma consulta e executar cada partição separadamente usando o driver JDBC do 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';

Para um exemplo completo, consulte PartitionQueryExample.

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

Executa uma partição de consulta que foi retornada anteriormente pelo comando PARTITION. O comando pode ser executado em qualquer conexão conectada ao mesmo banco de dados que o banco de dados que criou os tokens de partição.

MAX_PARTITIONED_PARALLELISM

Uma propriedade do tipo INT64 que indica o número de linhas de execução de worker que o driver JDBC do Spanner usa para executar partições. Esse valor é usado para:

• AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

Define o número máximo de linhas de execução de worker que o driver JDBC do Spanner pode usar para executar partições. Definir esse valor como 0 instrui o driver JDBC do Spanner a usar o número de núcleos da CPU na máquina cliente como o máximo.

O padrão é 0.

Comandos do Savepoint

As instruções a seguir ativam e desativam os pontos de salvamento emulados nas transações. É possível criar um ponto de salvamento chamando o método java.sql.Connection#setSavepoint().

O driver JDBC emula pontos de salvamento para oferecer suporte a frameworks que dependem deles para transações aninhadas. Os Savepoints são emulados acompanhando uma soma de verificação em execução para os resultados que foram retornados por instruções na transação. Ao reverter para um ponto de salvamento, o driver JDBC do Spanner reverte a transação e tenta novamente a transação até o ponto em que o ponto de salvamento foi definido. A soma de verificação da nova tentativa é comparada à da transação inicial para conferir se os mesmos resultados foram retornados.

SAVEPOINT_SUPPORT

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

Uma propriedade do tipo STRING que indica a configuração SAVEPOINT_SUPPORT atual. Os valores possíveis são:

• DISABLED: todos os comandos do ponto de salvamento estão desativados e falharão.
• FAIL_AFTER_ROLLBACK: os comandos do Savepoint estão ativados. Reverter para um savepoint reverte toda a transação. A transação falhará se você tentar usá-la depois de reverter para um ponto de salvamento.
• ENABLED: todos os comandos do ponto de salvamento estão ativados. A reversão para um ponto de salvamento reverte a transação, e uma nova tentativa é realizada no ponto de salvamento. Essa operação falhará com um erro AbortedDueToConcurrentModificationException se os dados subjacentes usados pela transação até o ponto de salvamento forem alterados.

O valor padrão é FAIL_AFTER_ROLLBACK.

Só é possível alterar o valor dessa variável enquanto não há transação ativa.

▶ Exemplo: compatibilidade com Savepoint (clique para expandir)

O exemplo a seguir mostra como ativar e desativar o suporte a pontos de salvamento no driver JDBC do 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);
}

A seguir

Saiba como conectar o JDBC a um banco de dados de dialeto GoogleSQL.