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

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 de maneira eficiente.

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

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.

SPANNER.READONLY

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

SHOW [VARIABLE] SPANNER.READONLY
SET SPANNER.READONLY {TO|=} { 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 SPANNER.READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;

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

SELECT Title
FROM Albums
ORDER BY Title;

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

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

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 {TO|=} { 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 da execução de 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 AUTOCOMMIT;

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

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

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

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

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

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

SPANNER.RETRY_ABORTS_INTERNALLY

Um booleano indicando se a conexão repete automaticamente as transações canceladas. O padrão é true.

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

É possível alterar o valor dessa propriedade somente 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 SPANNER.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. Isso é 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 novamente as transações canceladas.

SPANNER.AUTOCOMMIT_DML_MODE

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

SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { '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 SPANNER.AUTOCOMMIT_DML_MODE = 'PARTITIONED_NON_ATOMIC';

-- Delete all singers that have been marked as inactive.
-- This statement is executed using Partitioned DML.
DELETE
FROM singers
WHERE active=false;

-- Change DML mode back to standard `TRANSACTIONAL`.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';

STATEMENT_TIMEOUT

Uma propriedade do tipo STRING que indica o valor do tempo limite atual das instruções.

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

O valor int8 é um número inteiro seguido por um sufixo que indica a unidade de tempo. DEFAULT significa 0 segundo, o que equivale a "sem tempo limite". Um número de int8 sem unidades indica ms. Se um valor de tempo limite da instrução tiver sido definido, as instruções que demorarem mais do que o valor de tempo limite especificado causarão um erro java.sql.SQLTimeoutException e invalidarão 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 é 0, que significa que não há tempo limite.

Um tempo limite da 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 uma java.sql.SQLTimeoutException.

SPANNER.READ_ONLY_STALENESS

Uma propriedade do tipo STRING indicando a configuração atual de inatividade somente leitura que o Spanner usa para transações e consultas somente leitura no modo AUTOCOMMIT.

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

staleness_type:

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

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 instrui o Spanner a 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, em relação 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 :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 SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 10s';

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title, SingerId
FROM Albums
ORDER BY Title;

COMMIT;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_VERSION

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

SHOW [VARIABLE] SPANNER.OPTIMIZER_VERSION
SET SPANNER.OPTIMIZER_VERSION {TO|=} { '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 estiver 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 SPANNER.OPTIMIZER_VERSION = '5';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_STATISTICS_PACKAGE

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

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

Define o pacote de estatísticas do otimizador a ser usado para 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 estiver definido, o Spanner vai usar o pacote 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 SPANNER.OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.RETURN_COMMIT_STATS

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

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

O padrão é false.

▶ Exemplo: estatísticas de confirmação (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 SPANNER.RETURN_COMMIT_STATS = true;

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

-- View the commit response with the transaction statistics for the last
-- transaction that was committed.
SHOW SPANNER.COMMIT_RESPONSE;

SPANNER.RPC_PRIORITY

Uma propriedade do tipo STRING que indica a prioridade relativa para as 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] SPANNER.RPC_PRIORITY
SET SPANNER.RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

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

O padrão é 'NULL'.

Para mais informações, consulte Priority.

Tags

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

SPANNER.STATEMENT_TAG

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

SHOW [VARIABLE] SPANNER.STATEMENT_TAG
SET SPANNER.STATEMENT_TAG {TO|=} '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 precisa ser configurada para cada instrução. Uma tag de solicitação pode ser removida configurando-a como a string vazia ('').

O padrão é ''.

Você pode definir tags de transação e de instrução para a mesma instrução.

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 SPANNER.STATEMENT_TAG = 'tag1';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SPANNER.TRANSACTION_TAG

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

SHOW [VARIABLE] SPANNER.TRANSACTION_TAG
SET SPANNER.TRANSACTION_TAG {TO|=} '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 e precisa ser definida para cada transação. Uma tag de transação pode ser removida ao defini-la como uma string vazia (''). A tag de transação precisa ser definida antes que qualquer instrução seja executada na transação.

O padrão é ''.

Você pode definir tags de transação e de instrução para a mesma instrução.

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 SPANNER.TRANSACTION_TAG = 'transaction-tag-1';

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

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

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

COMMIT;

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

Instruções da transação

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

NÍVEL DE ISOLAMENTO DE TRANSAÇÕES

SHOW [VARIABLE] TRANSACTION ISOLATION LEVEL

Retorna um conjunto de resultados com uma linha e uma coluna do tipo STRING. O valor retornado é sempre serializable.

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.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: carimbo de data/hora de leitura (clique para expandir)

O exemplo a seguir mostra como visualizar 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 SPANNER.READ_TIMESTAMP;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT Title
FROM Albums
ORDER BY Title;

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

COMMIT;

SPANNER.COMMIT_TIMESTAMP

SHOW [VARIABLE] SPANNER.COMMIT_TIMESTAMP

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/gravação confirmada pelo Spanner. Essa instrução retorna um carimbo de data/hora somente quando você o executa depois de confirmar uma transação de leitura/gravação e antes de executar qualquer SELECT, DML ou instruções de mudança 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 visualizar o último carimbo de data/hora de confirmação para 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 SPANNER.COMMIT_TIMESTAMP;

SPANNER.COMMIT_RESPONSE

SHOW [VARIABLE] SPANNER.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 é sempre vazio quando executado no emulador.

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

▶ Exemplo: resposta com 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 SPANNER.RETURN_COMMIT_STATS = true;

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

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

{ INICIAR | INICIAR } [ TRANSAÇÃO | TRABALHO ]

{ START | BEGIN } [ TRANSACTION | WORK ] [{ READ ONLY | READ WRITE }]

Inicia uma nova transação. As palavras-chave TRANSACTION e WORK são opcionais, equivalentes e não têm efeito.

• 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.
• Se READ ONLY ou READ WRITE não for especificado, o modo de transação será determinado pelo modo de transação padrão da sessão. Esse padrão é definido usando o comando SET SESSION CHARACTERISTICS AS TRANSACTION ou configurando a variável READONLY.

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;

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

COMENTÁRIO [TRANSAÇÃO | TRABALHO]

COMMIT [ TRANSACTION | WORK ]

Confirma a transação atual. As palavras-chave TRANSACTION e WORK são opcionais e equivalentes e não têm efeito.

• A confirmação de uma transação de leitura/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 READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

{ ABORT | ROLLBACK } [TRANSAÇÃO | TRABALHO]

{ ABORT | ROLLBACK } [TRANSACTION | WORK]

Executa um ROLLBACK da transação atual. As palavras-chave TRANSACTION e WORK são opcionais e equivalentes e não têm efeito.

• Realizar um ROLLBACK de uma transação de leitura/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 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 | WORK] e ainda não tiver executado nenhuma instrução na transação.

Esta instrução define o modo de transação apenas 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 SESSION CHARACTERISTICS.

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

DEFINIR CARACTERÍSTICAS DA SESSÃO

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

Define o modo de transação padrão para transações na sessão como READ ONLY ou READ WRITE. Esta instrução só é permitida quando não há uma transação ativa.

O comando SET TRANSACTION pode substituir essa configuração.

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  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

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

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

RUN BATCH

RUN BATCH

Envia todas as instruções DDL armazenadas em buffer no lote DDL atual para o banco de dados, espera 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 na 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, talvez o Spanner ainda tenha aplicado as instruções DDL anteriores no mesmo lote ao banco de dados.

ABORT BATCH

ABORT BATCH

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  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

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

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

INICIAR BATCH DML e EXECUTAR 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 DML (clique para expandir)

O exemplo a seguir mostra como executar um lote da 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 de partição. A API PartitionQuery tem uma latência maior do que a API de consulta padrão porque se destina apenas a operações em massa, como exportação ou verificação de todo o banco de dados.

O Data Boost permite que você execute 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 na conexão atual com a instrução SET SPANNER.DATA_BOOST_ENABLED.

O driver do JDBC oferece três alternativas para executar consultas particionadas:

• SET SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql seguida por várias RUN PARTITION 'partition-token'

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

SPANNER.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] SPANNER.DATA_BOOST_ENABLED
SET SPANNER.DATA_BOOST_ENABLED {TO|=} { true | false }

Define se essa conexão precisa usar o Data Boost para consultas particionadas.

O padrão é false.

▶ Exemplo: executar uma consulta usando o Data Boost (clique para expandir)

O exemplo a seguir mostra como uma consulta usando o Data Boost com o driver JDBC do Spanner.

-- Enable Data Boost on this connection.
SET SPANNER.DATA_BOOST_ENABLED = true;

-- Execute a partitioned query. Data Boost is only used for partitioned queries.
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers;

Para ver um exemplo completo, consulte PostgreSQL DataBoostExample.

SPANNER.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] SPANNER.AUTO_PARTITION_MODE
SET SPANNER.AUTO_PARTITION_MODE {TO|=} { 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 SPANNER.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 SPANNER.AUTO_PARTITION_MODE = true
SET SPANNER.DATA_BOOST_ENABLED = true
SELECT FirstName, LastName FROM Singers
SELECT SingerId, Title FROM Albums

Para ver um exemplo completo, consulte PostgreSQL AutoPartitionModeExample.

EXECUTAR CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

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

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

O driver JDBC 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 SPANNER.MAX_PARTITIONED_PARALLELISM.

Para ver um exemplo completo, consulte PostgreSQL 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 JDBC separada no mesmo host 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, em seguida, 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 ver um exemplo completo, consulte PostgreSQL PartitionQueryExample.

EXECUTAR 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 JDBC que esteja conectada ao mesmo banco de dados que criou os tokens de partição.

Para ver um exemplo completo, consulte PostgreSQL PartitionQueryExample.

SPANNER.MAX_PARTITIONED_PARALLELISM

Uma propriedade do tipo int8 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:

• SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

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

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 savepoints emulados em transações. É possível criar um ponto de salvamento chamando o método java.sql.Connection#setSavepoint().

O driver JDBC do Spanner emula os pontos de salvamento para oferecer suporte a frameworks que dependem deles para transações aninhadas. Os Savepoints são emulados pelo monitoramento de 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 repetir 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 confirmar se os mesmos resultados foram retornados.

SPANNER.SAVEPOINT_SUPPORT

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

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

• DISABLED: todos os comandos do ponto de salvamento estão desativados e vão falhar.
• FAIL_AFTER_ROLLBACK: os comandos do Savepoint estão ativados. Reverter para um ponto de salvamento 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 para esse ponto. 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 mudar o valor dessa variável enquanto não houver uma transação ativa.

▶ Exemplo: suporte ao 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 SPANNER.SAVEPOINT_SUPPORT='DISABLED'");
  // The following statement fails because savepoints have been disabled.
  connection.setSavepoint("my_savepoint1");

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

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

A seguir

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