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

O driver JDBC (Java Database Connectivity) do Spanner 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 aos bancos de dados de dialeto PostgreSQL.

Observação: é possível usar instruções de gerenciamento de sessão somente com o Driver JDBC do Spanner. Gerenciamento de sessão não funcionam nas bibliotecas de cliente, na Google Cloud CLI ou na solicitação 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 operações transações 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;

AUTOCOMMIT

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á nenhuma transação.

Quando AUTOCOMMIT for definido como falso, uma nova transação será iniciada automaticamente depois de executar 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 que indica se a conexão é cancelada automaticamente e de novo transações. O padrão é true.

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

Só é possível mudar o valor dessa propriedade depois que uma transação é iniciada (consulte BEGIN TRANSACTION) e antes instruções são executadas dentro da transação.

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 seu aplicativo já tenta novamente as transações canceladas.

SPANNER.AUTOCOMMIT_DML_MODE

Uma propriedade STRING indicando 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] 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. Um particionado update pode ser executada como uma série de diversas 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 particionada usando a 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 indicando o valor de tempo limite atual para 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, equivalente a nenhum tempo limite. Um O número int8 sem unidades indica em ms. Se um valor de tempo limite da instrução tiver sido definido, as instruções que demoram mais do que o valor de tempo limite especificado causarão uma 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 é 0, o que significa que não há tempo limite.

O tempo limite de uma instrução durante uma transação invalida a transação, todas 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 o valor de inatividade somente leitura O Spanner usa para consultas e transações somente leitura em AUTOCOMMIT modo

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 todos transações somente leitura subsequentes e para 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 realizar uma leitura de inatividade limitada, relativa a now().
• MIN_READ_TIMESTAMP define um tempo absoluto que o Spanner usa para perform uma leitura de inatividade limitada.
• EXACT_STALENESS define o intervalo de tempo que o Spanner usa para realizar uma leitura exata de inatividade, relativa a now().
• READ_TIMESTAMP define um tempo absoluto que o Spanner usa para executar uma leitura de inatividade exata.

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 desta propriedade quando não há transação.

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 uma inatividade personalizada. 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 indicando o 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 em a conexão. Se a versão do otimizador estiver definida como '' (a string vazia), O Spanner usa a versão mais recente. Se nenhuma versão do otimizador for definida, O Spanner usa a versão do otimizador definida no banco de dados nível

O padrão é ''.

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

O exemplo a seguir mostra como executar consultas usando uma da versão do otimizador com a 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 indicando o valor pacote de estatísticas do otimizador que é 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 seguintes na conexão. <package> precisa ser um nome de pacote válido. Se não houver otimizador o pacote de estatísticas estiver definido, o Spanner vai usar as estatísticas do otimizador que é 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 uma pacote de estatísticas do otimizador com e 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 estatísticas devem ser retornadas para transações nesta conexão. Você pode conferir as estatísticas retornadas executando o comando SHOW SPANNER.COMMIT_RESPONSE.

SHOW [VARIABLE] SPANNER.RETURN_COMMIT_STATS
SET SPANNER.RETURN_COMMIT_STATS {TO|=} { 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 de 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 indicando a prioridade relativa para solicitações do Spanner. A prioridade serve como uma dica para a 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'.

Também é possível usar uma dica de instrução para especificar a prioridade da 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.

SPANNER.STATEMENT_TAG

Uma propriedade do tipo STRING que contém a tag de solicitação para o próximo 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. Só um tag pode ser definida por instrução. A tag não abrange várias instruções. deve ser definido por instrução. Para remover uma tag de solicitação, configure-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 abaixo 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;

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

SPANNER.TRANSACTION_TAG

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

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

Define a tag da transação atual a ser executada. Apenas uma tag pode ser definida por transação. A tag não abrange várias transações. precisam ser definidos 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 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 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ÇÃO

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: leitura de carimbo de data/hora (clique para expandir)

O exemplo a seguir mostra como exibir o carimbo de data/hora da última leitura de um 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 que O Spanner está comprometido. 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 é NULL.

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

O exemplo a seguir mostra como exibir o último carimbo de data/hora de commit de um 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 o evento transação foi confirmada.
• MUTATION_COUNT (type=INT64) indica quantas mutações foram aplicadas em a transação confirmada. Este valor está sempre vazio quando executado no emulador.

A contagem de mutações só estará disponível se SET SPANNER.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 de um 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;

{ START | COMEÇAR } [ 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 definindo 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 e 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;

COMMIT [TRANSACTION | WORK]

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.

• Confirmar uma transação de leitura e gravação faz todas as atualizações dessa transação fica visível 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 } [TRANSACTION | WORK]

{ 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 uma ROLLBACK de uma transação de leitura/gravação limpa todos os dados em buffer mutações, reverte a transação no Spanner e libera qualquer bloqueio que a transação tenha.
• 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 iniciou uma transação executando BEGIN [TRANSACTION | WORK] e não mas executou quaisquer instruções na transação.

Essa instrução define o modo de transação apenas para a transação atual. Quando confirmar ou reverter a transação, a próxima transação usará 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 for no modo READ ONLY.

▶ Exemplo: SET TRANSACTION (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;

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á 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 enviam-nos 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 enviada 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 as 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 a no lote de 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 pode ter aplicado as instruções DDL anteriores no mesmo lote à no seu 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: interromper o lote de DDL (clique para expandir)

O exemplo a seguir mostra como cancelar um lote DDL com as 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 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 de DML (clique para expandir)

O exemplo a seguir mostra como executar um lote DML com a 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 partitionQuery divide a consulta em partes menores, ou partições, e usa várias para buscar as partições em paralelo. Cada partição é identificada por uma token de partição. A API PartitionQuery tem latência maior que a API API de consulta, já que ela se destina apenas a operações em massa, como exportar ou verificar todo o banco de dados.

Otimização de dados você executa consultas analíticas e exportações de dados com 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 na conexão atual com o Instrução SET SPANNER.DATA_BOOST_ENABLED.

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

• SET SPANNER.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.

SPANNER.DATA_BOOST_ENABLED

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

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

Define se esta conexão deve usar Otimização de dados para consultas particionadas.

O padrão é 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 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 um exemplo completo, consulte PostgreSQL DataBoostExample.

SPANNER.AUTO_PARTITION_MODE

Uma propriedade do tipo BOOL que indica se a conexão usa automaticamente 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 particionada para todas as consultas executadas.
• Também defina SPANNER.DATA_BOOST_ENABLED como true se quiser que a conexão para usar o Data Boost para todos consultas.

O padrão é false.

▶ Exemplo: executar (clique para expandir)

Este exemplo executa duas consultas com o driver JDBC do Spanner usando Otimização de dados

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

Para 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 Otimização de dados:

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 para o aplicativo. O número de linhas de execução de trabalho que executam partições pode ser definido com a variável SPANNER.MAX_PARTITIONED_PARALLELISM.

Para conferir um exemplo completo, consulte PostgreSQL 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 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 executar cada 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 PostgreSQL PartitionQueryExample.

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

Executa uma partição de consulta que já foi retornada por PARTITION. kubectl. O comando pode ser executado em qualquer conexão JDBC conectada o mesmo banco de dados que criou os tokens de partição.

Para um exemplo completo, consulte PostgreSQL PartitionQueryExample.

SPANNER.MAX_PARTITIONED_PARALLELISM

Uma propriedade do tipo int8 indicando 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 que pode ser usado para executar partições. Definir esse valor como 0 instrui o O driver JDBC do Spanner para usar o número de núcleos de CPU no cliente máquina, como o máximo.

O padrão é 0.

Comandos do Savepoint

As instruções a seguir ativam e desativam emulados pontos de salvamento nas transações. É possível criar um ponto de salvamento chamando o 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 Savepoints são emulados ao acompanhar de uma soma de verificação em execução para os resultados que foram retornados por instruções em a transação. Ao reverter para um ponto de salvamento, o 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.

SPANNER.SAVEPOINT_SUPPORT

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

Uma propriedade do tipo STRING indicando o SAVEPOINT_SUPPORT atual. configuração do Terraform. 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 de ponto de salvamento estão ativados. Revertendo para um o ponto de salvamento reverte toda a transação. A transação vai falhar se você tentar para usar a transação depois de reverter para um ponto de salvamento.
• ENABLED: todos os comandos do ponto de salvamento estão ativados. Como reverter para um ponto de salvamento vai reverter a transação e uma 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 desta variável quando ela não está ativa transação.

▶ Exemplo: compatibilidade com Savepoint (clique para expandir)

O exemplo a seguir mostra como ativar e desativar o suporte a pontos de salvamento em e o 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 de dialeto PostgreSQL.