Comandos de gestão de sessões JDBC (PostgreSQL)

O controlador JDBC (Java Database Connectivity) do Spanner suporta declarações de gestão de sessões, que lhe permitem modificar o estado da sua ligação, executar transações e executar eficientemente lotes de declarações.

Os seguintes comandos aplicam-se a bases de dados com dialeto PostgreSQL.

Nota: só pode usar declarações de gestão de sessões com o controlador JDBC do Spanner. As declarações de gestão de sessões não funcionam nas bibliotecas cliente, na CLI Google Cloud nem no controlador JDBC criado pela Simba.

Declarações de ligação

As seguintes declarações alteram ou apresentam propriedades da ligação atual.

SPANNER.READONLY

Um valor booleano que indica se a ligação está ou não no modo só de leitura. O valor predefinido é false.

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

Só pode alterar o valor desta propriedade enquanto não existir uma transação ativa.

▶ Exemplo: transação só de leitura (clique para expandir)

O exemplo seguinte mostra como usar esta propriedade para executar transações de leitura apenas 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 valor booleano que indica se a ligação está ou não no modo de confirmação automática. O valor predefinido é true.

SHOW [VARIABLE] AUTOCOMMIT
SET AUTOCOMMIT {TO|=} { true | false }

Só pode alterar o valor desta propriedade quando não existir nenhuma transação ativa.

Quando AUTOCOMMIT está definido como falso, é iniciada automaticamente uma nova transação depois de executar COMMIT ou ROLLBACK. A primeira declaração que executar inicia a transação.

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

O exemplo seguinte 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 valor booleano que indica se a ligação tenta novamente as transações anuladas automaticamente. A predefinição é true.

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

Só pode alterar o valor desta propriedade depois de uma transação ter sido iniciada (consulte BEGIN TRANSACTION) e antes de qualquer declaração ser executada na transação.

Quando define SPANNER.RETRY_ABORTS_INTERNALLY como verdadeiro, a ligação mantém uma soma de verificação de todos os dados que a ligação devolve à aplicação cliente. Isto é usado para tentar novamente a transação se for anulada pelo Spanner.

O valor predefinido é true. Recomendamos que defina este valor como false se a sua aplicação já repetir as transações anuladas.

SPANNER.AUTOCOMMIT_DML_MODE

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

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 controlador executa declarações DML como transações atómicas separadas. O controlador cria uma nova transação, executa a declaração DML e confirma a transação após a execução bem-sucedida ou reverte a transação em caso de erro.
• No modo PARTITIONED_NON_ATOMIC, o controlador executa declarações DML como declarações de atualização particionadas. Uma declaração de atualização particionada pode ser executada como uma série de muitas transações, cada uma abrangendo um subconjunto das linhas afetadas. A declaração particionada oferece uma semântica mais fraca em troca de uma melhor escalabilidade e desempenho.

A predefinição é TRANSACTIONAL.

▶ Exemplo: DML particionada (clique para expandir)

O exemplo seguinte mostra como executar DML particionada através do controlador 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 de tempo limite atual para declarações.

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

O valor int8 é um número inteiro seguido de um sufixo que indica a unidade de tempo. DEFAULT significa 0 segundos, o que equivale a não ter limite de tempo. Um int8 número sem unidades indica ms. Se tiver sido definido um valor de limite de tempo da declaração, as declarações que demorarem mais do que o valor de limite de tempo especificado vão causar um erro java.sql.SQLTimeoutException e invalidar a transação.

As unidades de tempo suportadas são:

• s: segundos
• ms: milissegundos
• us: microssegundos
• ns: nanosegundos

A predefinição é 0, o que significa que não existe limite de tempo.

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

SPANNER.READ_ONLY_STALENESS

Uma propriedade do tipo STRING que indica a definição de desatualização só de leitura atual que o Spanner usa para transações e consultas só de 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 obsolescência só de leitura aplica-se a todas as transações só de leitura subsequentes e a todas as consultas no modo AUTOCOMMIT.

A predefinição é STRONG.

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

• STRONG indica ao Spanner que deve executar uma leitura forte.
• MAX_STALENESS define o intervalo de tempo que o Spanner usa para executar uma leitura de desatualização limitada, relativamente a now().
• MIN_READ_TIMESTAMP define uma hora absoluta que o Spanner usa para executar uma leitura de desatualização limitada.
• EXACT_STALENESS define o intervalo de tempo que o Spanner usa para fazer uma leitura de desatualização exata, relativamente a now().
• READ_TIMESTAMP define uma hora absoluta que o Spanner usa para fazer uma leitura de desatualização exata.

As indicações de tempo têm de usar o seguinte formato:

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

As unidades de tempo suportadas para definir valores MAX_STALENESS e EXACT_STALENESS são:

• s: segundos
• ms: milissegundos
• us: microssegundos
• ns: nanosegundos

Só pode modificar o valor desta propriedade enquanto não existir uma transação ativa.

Nota: só pode usar os valores MIN_READ_TIMESTAMP e MAX_STALENESS para consultas no modo AUTOCOMMIT.

▶ Exemplo: desatualização só de leitura (clique para expandir)

O exemplo seguinte mostra como executar consultas usando um valor de desatualização personalizado com o controlador 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 usar para todas as declarações seguintes na ligação. Se a versão do otimizador estiver definida como '' (a string vazia), o Spanner usa a versão mais recente. Se não estiver definida nenhuma versão do otimizador, o Spanner usa a versão do otimizador definida ao nível da base de dados.

A predefinição é ''.

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

O exemplo seguinte mostra como executar consultas usando uma versão do otimizador específica com o controlador 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 esta associação.

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

Define o pacote de estatísticas do otimizador a usar para todas as declarações seguintes na ligação. <package> tem de ser um nome de pacote válido. Se não estiver definido nenhum pacote de estatísticas do otimizador, o Spanner usa o pacote de estatísticas do otimizador que está definido ao nível da base de dados.

A predefinição é ''.

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

O exemplo seguinte mostra como executar consultas usando um pacote de estatísticas do otimizador específico com o controlador 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 devem ser devolvidas estatísticas para transações nesta associação. Pode ver as estatísticas devolvidas executando o comando SHOW SPANNER.COMMIT_RESPONSE.

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

A predefinição é false.

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

O exemplo seguinte mostra como ver as estatísticas de confirmação de uma transação com o controlador 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 dos pedidos do Spanner. A prioridade funciona como uma sugestão para o agendador 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 não deve ser incluída nenhuma sugestão no pedido.

A predefinição é 'NULL'.

Também pode usar uma sugestão de declaração para especificar a prioridade do RPC:

/*@RPC_PRIORITY=PRIORITY_LOW*/ SELECT * FROM Albums

Para mais informações, consulte Priority.

Etiquetas

As seguintes declarações gerem etiquetas de pedidos e transações.

SPANNER.STATEMENT_TAG

Uma propriedade do tipo STRING que contém a etiqueta de pedido para a declaração seguinte.

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

Define a etiqueta de pedido para a próxima declaração a ser executada. Só é possível definir uma etiqueta por declaração. A etiqueta não abrange várias declarações. Tem de ser definida por declaração. Pode remover uma etiqueta de pedido definindo-a como a string vazia ('').

A predefinição é ''.

Pode definir etiquetas de transação e etiquetas de extrato para o mesmo extrato.

Também pode usar uma sugestão de declaração para adicionar uma etiqueta de declaração:

/*@STATEMENT_TAG='my-tag'*/ SELECT * FROM Albums

Para mais informações, consulte o artigo Resolva problemas com etiquetas de pedidos e etiquetas de transações.

▶ Exemplo: etiquetas de declaração (clique para expandir)

O exemplo seguinte mostra como definir etiquetas de declaração com o controlador 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 etiqueta de transação para a próxima transação.

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

Define a etiqueta de transação para a transação atual a ser executada. Só é possível definir uma etiqueta por transação. A etiqueta não abrange várias transações. Tem de ser definida por transação. Pode remover uma etiqueta de transação definindo-a como a string vazia (''). A etiqueta de transação tem de ser definida antes de serem executadas quaisquer declarações na transação.

A predefinição é ''.

Pode definir etiquetas de transação e etiquetas de extrato para o mesmo extrato.

Para mais informações, consulte o artigo Resolva problemas com etiquetas de pedidos e etiquetas de transações.

▶ Exemplo: etiquetas de transações (clique para expandir)

O exemplo seguinte mostra como definir etiquetas de transação com o controlador 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;

Extratos de transações

As seguintes declarações gerem e confirmam transações do Spanner.

NÍVEL DE ISOLAMENTO DE TRANSAÇÕES

SHOW [VARIABLE] TRANSACTION ISOLATION LEVEL

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

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

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

▶ Exemplo: ler data/hora (clique para expandir)

O exemplo seguinte mostra como ver a data/hora da última leitura para uma operação de só de leitura com o controlador 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

Devolve um conjunto de resultados com uma linha e uma coluna do tipo TIMESTAMP que contém a data/hora de confirmação da última transação de leitura/escrita que o Spanner confirmou. Esta declaração devolve uma data/hora apenas quando a executa depois de confirmar uma transação de leitura/escrita e antes de executar quaisquer declarações SELECT, DML ou de alteração do esquema subsequentes. Caso contrário, o resultado é NULL.

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

O exemplo seguinte mostra como ver a data/hora da última confirmação de uma operação de escrita com o controlador 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

Devolve 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. Este valor está sempre vazio quando executado no emulador.

A contagem de mutações só está disponível se SET SPANNER.RETURN_COMMIT_STATS tiver sido definido como true antes da consolidação da transação.

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

O exemplo seguinte mostra como ver a última resposta de confirmação para uma operação de escrita com o controlador 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 | BEGIN } [ TRANSACTION | WORK ]

{ 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 qualquer efeito.

• Use COMMIT ou ROLLBACK para terminar uma transação.
• Se tiver ativado o modo AUTOCOMMIT, esta declaração retira temporariamente a ligação do modo AUTOCOMMIT. A ligação volta ao modo AUTOCOMMIT quando a transação termina.
• Se READ ONLY ou READ WRITE não for especificado, o modo de transação é determinado pelo modo de transação predefinido da sessão. Esta predefinição é definida através do comando SET SESSION CHARACTERISTICS AS TRANSACTION ou da definição da variável READONLY.

Só pode executar esta declaração quando não existir nenhuma transação ativa.

▶ Exemplo: BEGIN TRANSACTION (clique para expandir)

O exemplo seguinte mostra como iniciar diferentes tipos de transações com o controlador 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 qualquer efeito.

• A confirmação de uma transação de leitura/escrita torna todas as atualizações desta transação visíveis para outras transações e liberta todos os bloqueios da transação no Spanner.
• A confirmação de uma transação só de leitura termina a transação só de leitura atual. Qualquer declaração subsequente inicia uma nova transação. Não existe diferença semântica entre COMMIT e ROLLBACK para uma transação de leitura.

Só pode executar esta declaração enquanto existir uma transação ativa.

▶ Exemplo: COMMIT TRANSACTION (Clique para expandir)

O exemplo seguinte mostra como confirmar uma transação com o controlador 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]

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

• A execução de um ROLLBACK de uma transação de leitura/escrita limpa todas as mutações em buffer, reverte a transação no Spanner e liberta todos os bloqueios que a transação detinha.
• A execução de um ROLLBACK de uma transação só de leitura termina a transação só de leitura atual. Todas as declarações subsequentes iniciam uma nova transação. Não existe diferença semântica entre COMMIT e ROLLBACK para uma transação só de leitura numa ligação.

Só pode executar esta declaração enquanto existir uma transação ativa.

▶ Exemplo: ROLLBACK TRANSACTION (clique para expandir)

O exemplo seguinte mostra como reverter uma transação com o controlador 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 para a transação atual.

Só pode executar esta declaração quando AUTOCOMMIT for false ou se tiver iniciado uma transação executando BEGIN [TRANSACTION | WORK] e ainda não tiver executado nenhuma declaração na transação.

Esta declaração define o modo de transação apenas para a transação atual. Quando a transação é confirmada ou revertida, a transação seguinte usa o modo predefinido para a ligação. (Consulte SET SESSION CHARACTERISTICS.)

Nota: não pode definir o modo de transação como READ WRITE se a ligação estiver no modo READ ONLY.

▶ Exemplo: SET TRANSACTION (Clique para expandir)

O exemplo seguinte mostra como definir as caraterísticas da transação com o controlador 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;

DEFINA AS CARATERÍSTICAS DA SESSÃO

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

Define o modo de transação predefinido para transações na sessão como READ ONLY ou READ WRITE. Esta declaração só é permitida quando não existe nenhuma transação ativa.

O comando SET TRANSACTION pode substituir esta definição.

Extratos em lote

As seguintes declarações gerem lotes de declarações DDL e enviam esses lotes para o Spanner.

INICIE O LDD EM LOTE

START BATCH DDL

Inicia um lote de declarações DDL na ligação. Todas as declarações subsequentes durante o lote têm de ser declarações DDL. As declarações DDL são armazenadas em buffer localmente e enviadas para o Spanner como um lote quando executa RUN BATCH. A execução de várias declarações DDL como um lote é normalmente mais rápida do que a execução das declarações em separado.

Só pode executar esta declaração quando não existir nenhuma transação ativa.

▶ Exemplo: lote de DDL (clique para expandir)

O exemplo seguinte mostra como executar um lote de DDL com o controlador 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 declarações DDL em buffer no lote DDL atual para a base de dados, aguarda que o Spanner execute estas declarações e termina o lote DDL atual.

Se o Spanner não conseguir executar, pelo menos, uma declaração DDL, RUN BATCH devolve um erro para a primeira declaração DDL que o Spanner não consegue executar. Caso contrário, RUN BATCH é devolvido com êxito.

Nota: se uma declaração DDL no lote devolver um erro, o Spanner pode ainda ter aplicado as declarações DDL anteriores no mesmo lote à base de dados.

ABORT BATCH

ABORT BATCH

Limpa todas as declarações DDL em buffer no lote DDL atual e termina o lote.

Só pode executar esta declaração quando um lote de LDD está ativo. Pode usar ABORT BATCH independentemente de o lote ter ou não instruções DDL em buffer. Todas as declarações DDL anteriores no lote são anuladas.

▶ Exemplo: anular lote de DDL (clique para expandir)

O exemplo seguinte mostra como anular um lote de DDL com o controlador 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;

START BATCH DML e RUN BATCH

As seguintes declarações agrupam as duas declarações DML e enviam-nas numa chamada para o servidor. Um lote de 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 seguinte mostra como executar um lote de DML com o controlador 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 declarações de consultas particionadas

A API partitionQuery divide uma consulta em partes mais pequenas, ou partições, e usa várias máquinas para obter as partições em paralelo. Cada partição é identificada por um token de partição. A API PartitionQuery tem uma latência superior à da API de consulta padrão, porque destina-se apenas a operações em massa, como exportar ou analisar toda a base de dados.

O Data Boost permite-lhe executar consultas de estatísticas e exportações de dados com um impacto quase nulo nos fluxos de trabalho existentes na instância do Spanner aprovisionada. A otimização de dados só suporta consultas particionadas.

Pode ativar o aumento de dados na associação atual com a declaração SET SPANNER.DATA_BOOST_ENABLED.

O controlador JDBC suporta três alternativas para executar consultas particionadas:

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

Cada um destes métodos é descrito nas secções seguintes.

SPANNER.DATA_BOOST_ENABLED

Uma propriedade do tipo BOOL que indica se esta associação deve usar o Data Boost para consultas particionadas. O valor predefinido é false.

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

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

A predefinição é false.

▶ Exemplo: execute uma consulta com o aumento de dados (clique para expandir)

O exemplo seguinte mostra como fazer uma consulta usando o Data Boost com o controlador 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 o artigo PostgreSQL DataBoostExample.

SPANNER.AUTO_PARTITION_MODE

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

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

• Defina esta variável como true se quiser que a ligação use consultas particionadas para todas as consultas executadas.
• Defina também SPANNER.DATA_BOOST_ENABLED como true se quiser que a ligação use o Data Boost para todas as consultas.

A predefinição é false.

▶ Exemplo: Execute (clique para expandir)

Este exemplo executa duas consultas com o controlador 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.

EXECUTE UMA CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

Executa uma consulta como uma consulta particionada no Spanner. Certifique-se de que 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 controlador JDBC divide internamente a consulta e executa as partições em paralelo. Os resultados são unidos num conjunto de resultados e devolvidos à aplicação. O número de threads de trabalho 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 devolve uma lista de tokens de partição. Cada token de partição pode ser executado numa ligação JDBC separada no mesmo anfitrião ou noutro anfitrião através do comando RUN PARTITION 'partition-token'.

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

O exemplo seguinte mostra como particionar uma consulta e, em seguida, executar cada partição separadamente através do controlador 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.

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

Executa uma partição de consulta que foi devolvida anteriormente pelo comando PARTITION. O comando pode ser executado em qualquer ligação JDBC que esteja ligada à mesma base 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 threads de trabalho que o controlador JDBC do Spanner usa para executar partições. Este 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 threads de trabalho que o controlador JDBC do Spanner pode usar para executar partições. Se definir este valor como 0, indica ao controlador JDBC do Spanner que deve usar o número de núcleos do CPU na máquina cliente como o máximo.

A predefinição é 0.

Comandos de ponto de gravação

As seguintes declarações ativam e desativam os pontos de reposição em transações. Pode criar um ponto de salvaguarda chamando o método java.sql.Connection#setSavepoint().

O controlador JDBC do Spanner emula pontos de reposição para suportar frameworks que dependem destes para transações aninhadas. Os pontos de salvaguarda são emulados através do acompanhamento de uma soma de verificação em execução para os resultados que foram devolvidos por declarações na transação. Quando reverte para um ponto de salvaguarda, o controlador JDBC do Spanner reverte a transação e, em seguida, tenta novamente a transação até ao ponto em que o ponto de salvaguarda foi definido. A soma de verificação da repetição é comparada com a soma de verificação da transação inicial para verificar se foram devolvidos os mesmos resultados.

SPANNER.SAVEPOINT_SUPPORT

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

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

• DISABLED: todos os comandos de ponto de salvaguarda estão desativados e vão falhar.
• FAIL_AFTER_ROLLBACK: os comandos Savepoint estão ativados. A reversão para um ponto de reposição reverte toda a transação. A transação falha se tentar usar a transação depois de reverter para um ponto de salvaguarda.
• ENABLED: todos os comandos de ponto de salvaguarda estão ativados. A reversão para um ponto de salvaguarda reverte a transação e é feita uma nova tentativa para o ponto de salvaguarda. Esta operação falha com um erro AbortedDueToConcurrentModificationException se os dados subjacentes que foram usados pela transação até ao ponto de salvaguarda tiverem sido alterados.

O valor predefinido é FAIL_AFTER_ROLLBACK.

Só pode alterar o valor desta variável se não existir uma transação ativa.

▶ Exemplo: compatibilidade com Savepoint (clique para expandir)

O exemplo seguinte mostra como ativar e desativar o suporte de pontos de reposição no controlador 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);
}

O que se segue?

Saiba como associar o JDBC a uma base de dados de dialeto PostgreSQL.