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

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

Declarações de ligação

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

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 READONLY
SET READONLY = { 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 READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;

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

SELECT Title
FROM Albums
ORDER BY Title;

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

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

AUTOCOMMIT

Um 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 = { 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 VARIABLE AUTOCOMMIT;

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

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

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

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

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

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

RETRY_ABORTS_INTERNALLY

Um valor booleano que indica se a ligação tenta novamente as transações anuladas automaticamente. A predefinição é true.

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { 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 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.

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 AUTOCOMMIT_DML_MODE
SET AUTOCOMMIT_DML_MODE = { '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 AUTOCOMMIT_DML_MODE = 'PARTITIONED_NON_ATOMIC';

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

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

STATEMENT_TIMEOUT

Uma propriedade do tipo STRING que indica o valor de tempo limite atual para declarações.

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

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

As unidades de tempo suportadas são:

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

O valor predefinido é NULL, o que significa que não é definido nenhum valor de tempo limite.

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.

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 READ_ONLY_STALENESS
SET READ_ONLY_STALENESS = staleness_type

staleness_type:

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

O valor de 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:

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.

▶ 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 READ_ONLY_STALENESS = 'MAX_STALENESS 10s';

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title, SingerId
FROM Albums
ORDER BY Title;

COMMIT;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_VERSION

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

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

Define a versão do otimizador a 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 OPTIMIZER_VERSION = '5';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_STATISTICS_PACKAGE

Uma propriedade do tipo STRING que indica o pacote de estatísticas do otimizador atual usado por esta associação.

SHOW VARIABLE OPTIMIZER_STATISTICS_PACKAGE
SET OPTIMIZER_STATISTICS_PACKAGE = { '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 OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

RETURN_COMMIT_STATS

Uma propriedade do tipo BOOL que indica se devem ser devolvidas estatísticas para transações nesta associação. Pode ver as estatísticas devolvidas executando o comando SHOW VARIABLE COMMIT_RESPONSE.

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { 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 RETURN_COMMIT_STATS = true;

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

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

RPC_PRIORITY

Uma propriedade do tipo STRING que indica a prioridade relativa 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 RPC_PRIORITY
SET 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.

STATEMENT_TAG

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

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

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

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

TRANSACTION_TAG

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

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = '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 TRANSACTION_TAG = 'transaction-tag-1';

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

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

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

COMMIT;

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

Extratos de transações

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

READ_TIMESTAMP

SHOW VARIABLE 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 VARIABLE READ_TIMESTAMP;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT Title
FROM Albums
ORDER BY Title;

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

COMMIT;

COMMIT_TIMESTAMP

SHOW VARIABLE COMMIT_TIMESTAMP

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 VARIABLE COMMIT_TIMESTAMP;

COMMIT_RESPONSE

SHOW VARIABLE 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 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 RETURN_COMMIT_STATS = true;

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

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

BEGIN [TRANSACTION]

BEGIN [TRANSACTION]

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

  • Use COMMIT ou ROLLBACK para 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.
  • O modo de transação é determinado pela definição READONLY atual para esta ligação. Este valor é definido através do comando SET READONLY = {TRUE | FALSE}.
  • O modo de transação pode ser alterado executando SET TRANSACTION READ ONLY ou SET TRANSACTION READ WRITE diretamente após a execução de BEGIN [TRANSACTION].

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;

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

COMMIT [TRANSACTION]

COMMIT [TRANSACTION]

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

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

REVERTER [TRANSACTION]

ROLLBACK [TRANSACTION]

Faz um ROLLBACK da transação atual. As palavras-chave TRANSACTION são opcionais.

  • 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;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Define o modo de transação 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] 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 READONLY).

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

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  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

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

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

RUN BATCH

RUN BATCH

Envia todas as 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.

ABORT BATCH [TRANSACTION]

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  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

CREATE TABLE Albums (
  AlbumId  INT64 NOT NULL,
  Title    STRING(MAX),
  SingerId INT64,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
) PRIMARY KEY (AlbumId);

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

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 com a declaração SET DATA_BOOST_ENABLED.

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

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

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 DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | 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 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 DataBoostExample.

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

Para ver um exemplo completo, consulte AutoPartitionModeExample.

EXECUTE UMA CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

Executa uma consulta como uma consulta particionada no Spanner. Certifique-se de que DATA_BOOST_ENABLED está definido como true para executar a consulta com o Data Boost:

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

O controlador JDBC do Spanner divide internamente a consulta e executa 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 MAX_PARTITIONED_PARALLELISM.

Para ver um exemplo completo, consulte 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 separada no mesmo cliente ou noutro cliente 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 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 associação associada à mesma base de dados que a base de dados que criou os tokens de partição.

MAX_PARTITIONED_PARALLELISM

Uma propriedade do tipo INT64 que indica o número de threads de trabalho que o controlador JDBC do Spanner usa para executar partições. Este valor é usado para:

  • AUTO_PARTITION_MODE = true
  • RUN PARTITIONED QUERY sql
SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

Define o número máximo de 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.

Declarações de leitura direcionadas

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

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

Para mais informações, consulte o artigo Leituras direcionadas.

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.

SAVEPOINT_SUPPORT

SHOW VARIABLE SAVEPOINT_SUPPORT
SET SAVEPOINT_SUPPORT = { '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 SAVEPOINT_SUPPORT='DISABLED'");
  // The following statement fails because savepoints have been disabled.
  connection.setSavepoint("my_savepoint1");

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

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

O que se segue?

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