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

O driver JDBC do Spanner (Java Database Connectivity) oferece suporte a 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 a bancos de dados com 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á ou não no modo somente leitura. O padrão é false.

SHOW VARIABLE READONLY
SET READONLY = { true | false }

Só é possível mudar o valor dessa propriedade enquanto não há uma 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;

AUTOCOMMIT

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

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

Só é possível mudar 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 = TRUE;

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

RETRY_ABORTS_INTERNALLY

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 mudar o valor dessa propriedade depois que uma transação é iniciada (consulte BEGIN TRANSACTION) e antes que qualquer instrução seja executada na transação.

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 é usado para tentar novamente a transação se ela for abortada pelo Spanner.

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

AUTOCOMMIT_DML_MODE

Uma propriedade STRING que indica o modo de confirmação automática para as instruções da linguagem de manipulação de dados (DML).

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 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 DML particionado 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 que indica 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 que indica a unidade de tempo. Um valor de NULL indica que não há um valor de tempo limite definido. Se um valor de tempo limite de instrução tiver sido definido, as instruções que demorarem mais do que o valor de 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.

O tempo limite de uma instrução durante uma transação invalida a transação, todas as instruções subsequentes na transação invalidada falham (exceto ROLLBACK) 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 e consultas somente leitura 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 informa 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, relativa 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 há uma transação ativa.

Observação: use os valores MIN_READ_TIMESTAMP e MAX_STALENESS apenas para consultas no modo AUTOCOMMIT.

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

O exemplo a seguir mostra como executar consultas usando um valor de desatuação 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 que indica 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 vai usar a versão mais recente. Se nenhuma versão do otimizador estiver definida, o Spanner vai 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 que indica 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 para todas as instruções seguintes na conexão. <package> precisa ser um nome de pacote válido. Se nenhum pacote de estatísticas do otimizador estiver definido, o Spanner vai 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 conferir 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 confirmação (clique para expandir)

O exemplo a seguir mostra como conferir estatísticas de confirmação de 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 para solicitações do Spanner. A prioridade funciona 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 precisa ser incluída na solicitação.

O padrão é 'NULL'.

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

@{RPC_PRIORITY=PRIORITY_LOW} SELECT * FROM Albums

Para ver mais informações, consulte Priority.

Tags

As instruções a seguir gerenciam as tags de solicitação e de 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 que a próxima instrução seja executada. Apenas uma tag pode ser definida por instrução. A tag não abrange várias instruções. Ela precisa ser definida por instrução. Uma tag de solicitação pode ser removida definindo-a como a string vazia ('').

O padrão é ''.

É possível definir tags de transação e de extrato para o mesmo extrato.

Também é possível 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 tags de transação.

▶ Exemplo: tags de declaraçã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 da transação para a próxima transação.

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

Define a tag da transação para que a transação atual seja executada. Só é possível definir uma tag por transação. A tag não abrange várias transações. Ela precisa ser definida por transação. Uma tag de transação pode ser removida definindo-a como uma string vazia (''). A tag de transação precisa ser definida antes de qualquer instrução ser executada na transação.

O padrão é ''.

É possível definir tags de transação e de extrato para o mesmo extrato.

Para mais informações, consulte Resolver problemas com tags de solicitação e tags 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: ler carimbo de data/hora (clique para expandir)

O exemplo a seguir mostra como conferir o último carimbo de data/hora de leitura de 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 que contém o carimbo de data/hora de consolidação da última transação de leitura e gravação confirmada pelo Spanner. Essa instrução retorna um carimbo de data/hora apenas quando você o executa, depois de confirmar uma transação de leitura e gravação e antes de executar qualquer SELECT, DML ou instruções de alteração de esquema subsequentes. Caso contrário, o resultado será NULL.

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

O exemplo a seguir mostra como conferir o carimbo de data/hora do último commit 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 só estará disponível 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 conferir a última resposta de confirmação de 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 executar 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 desta 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. As palavras-chave TRANSACTION são opcionais.

• A realização de um ROLLBACK de uma transação de leitura e gravação limpa todas as mutações armazenadas em buffer, reverte a transação no Spanner e libera todos os bloqueios retidos pela transação.
• 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 o modo de transação apenas para a transação atual. Quando a transação é confirmada ou revertida, a próxima transação usa o modo padrão da 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: TRANSFERÊNCIA DE CONFIGURAÇÃO (clique para expandir)

O exemplo a seguir mostra como definir características de 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 de DDL (clique para expandir)

O exemplo a seguir mostra como executar um lote de 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 o Spanner executar 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 puder executar. Caso contrário, RUN BATCH retorna com sucesso.

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

ABORT BATCH [TRANSACTION]

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

▶ Exemplo: interromper o lote de DDL (clique para expandir)

O exemplo a seguir mostra como abortar um lote de 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;

DML START BATCH e RUN Batch

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

Aprimoramento de dados 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 de partição. A API PartitionQuery tem uma latência maior do que a API de consulta padrão, porque é destinada apenas a operações em massa, como exportar ou procurar todo o banco de dados.

O Data Boost permite 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ó oferece suporte a consultas particionadas.

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

O driver JDBC do Spanner oferece suporte a três alternativas para executar 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 o Data Boost para consultas particionadas. O padrão é false.

SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

▶ Exemplo: executar uma consulta usando o Data Boost (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 conferir 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 consultas particionadas para todas as consultas executadas.
• Defina DATA_BOOST_ENABLED como true se quiser que a conexão use o Data Boost para 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 conferir 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 Data 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 workers que executam partições pode ser definido com a variável MAX_PARTITIONED_PARALLELISM.

Para conferir um exemplo completo, consulte RunPartitionedQueryExample.

PARTIÇÃO <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 conferir 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 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. A definição desse valor como 0 instrui o driver JDBC do Spanner a usar o número de núcleos de CPU na máquina cliente como o máximo.

O padrão é 0.

Instruções de leitura direcionadas

Uma propriedade do tipo STRING que define a opção de leitura direcionada para as seguintes instruções.

SHOW VARIABLE DIRECTED_READ
SET DIRECTED_READ='{"includeReplicas":{"replicaSelections":[{"location":"<location-name>"}]}}'

Para mais informações, consulte Leituras direcionadas.

Comandos de ponto de salvamento

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 do Spanner emula pontos de salvamento para oferecer suporte a frameworks que dependem deles para transações aninhadas. Os pontos de salvamento são emulados mantendo o controle de uma soma de verificação em execução para os resultados 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 até o ponto em que o ponto de salvamento foi definido. A soma de verificação da tentativa é comparada à soma de verificação da transação inicial para verificar 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 atual de SAVEPOINT_SUPPORT. Os valores possíveis são:

• DISABLED: todos os comandos de ponto de salvamento são desativados e vão falhar.
• FAIL_AFTER_ROLLBACK: os comandos de ponto de salvamento estão ativados. A reversão para um ponto de salvamento reverte toda a transação. A transação falha se você tentar usá-la após reverter para um ponto de salvamento.
• ENABLED: todos os comandos de ponto de salvamento estão ativados. A reversão para um ponto de salvamento reverterá a transação, e a nova tentativa será realizada no ponto de salvamento. Essa operação falha com um erro AbortedDueToConcurrentModificationException se os dados usados pela transação até o ponto de salvamento tiverem mudado.

O valor padrão é FAIL_AFTER_ROLLBACK.

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

▶ Exemplo: suporte a pontos de salvamento (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 do GoogleSQL.