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

O driver JDBC (Java Database Connectivity) do Spanner oferece suporte à sessão de gerenciamento de configuração, que permitem modificar o estado da conexão, executar transações e lotes de instruções com eficiência.

Os comandos a seguir se aplicam a bancos de dados com dialeto GoogleSQL.

Instruções de conexão

As instruções a seguir alteram ou exibem as propriedades da conexão atual.

SOMENTE LEITURA

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

SHOW VARIABLE READONLY
SET READONLY = { true | false }

Só é possível mudar o valor desta propriedade quando ela não está ativa transação.

SET READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;

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

SELECT Title
FROM Albums
ORDER BY Title;

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

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

AUTOCOMMIT

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

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

Só é possível alterar o valor desta propriedade quando não há nenhuma transação.

Quando AUTOCOMMIT é definido como falso, uma nova transação é iniciada automaticamente depois que você executa COMMIT ou ROLLBACK. A primeira instrução executada inicia a transação.

-- The default value for AUTOCOMMIT is true.
SHOW VARIABLE AUTOCOMMIT;

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

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

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

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

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

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

RETRY_ABORTS_INTERNALLY

Um booleano que indica se a conexão tenta repetir automaticamente as transações canceladas. O padrão é true.

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }

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

Quando você define RETRY_ABORTS_INTERNALLY como verdadeiro, a conexão mantém uma soma de verificação de todos os dados que a conexão retorna ao aplicativo cliente. 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 aplicativo já tenta de novo com transações canceladas.

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

Os valores possíveis são:

• No modo TRANSACTIONAL, o driver executa instruções DML como transações atômicas separadas. O driver cria uma nova transação, executa a instrução DML e realiza a confirmação da transação após a execução bem-sucedida ou reverte a transação no caso de um erro.
• No modo PARTITIONED_NON_ATOMIC, o driver executa instruções DML como instruções de atualização particionadas. 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.

-- 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 indicando o valor de tempo limite atual para instruções.

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

O valor INT64 é um número inteiro seguido por um sufixo que indica a unidade de tempo. Um valor NULL indica que não há um valor de tempo limite definido. Se um o valor de tempo limite da instrução tenha sido definido, as instruções que levam mais tempo que o o valor de tempo limite especificado causará um erro java.sql.SQLTimeoutException e e invalidar a transação.

Os blocos de tempo compatíveis são estes:

• s: segundos
• ms: milésimos de segundo
• us: microssegundos
• ns: nanossegundos

O padrão é NULL, o que significa que nenhum valor de tempo limite foi definido.

O tempo limite de uma instrução durante uma transação invalida a transação, todas instruções subsequentes na transação invalidada (exceto ROLLBACK) apresentarem falha; e o driver JDBC do Spanner gera uma java.sql.SQLTimeoutException.

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

staleness_type:

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

O valor de inatividade somente leitura se aplica a 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 informa ao Spanner para executar uma leitura forte.
• MAX_STALENESS define o intervalo de tempo que o Spanner usa para executar uma leitura de inatividade limitada, em relação a now().
• MIN_READ_TIMESTAMP define um tempo absoluto que o Spanner usa para executar uma leitura de inatividade limitada.
• EXACT_STALENESS define o intervalo de tempo que o Spanner usa para executar uma leitura exata de inatividade, relativa a now().
• READ_TIMESTAMP define um tempo absoluto que o Spanner usa para executar uma leitura exata de inatividade.

Os carimbo de data/hora precisam usar o seguinte formato:

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

As unidades de tempo compatíveis para definir os valores MAX_STALENESS e EXACT_STALENESS são estes:

• s: segundos
• ms: milésimos de segundo
• us: microssegundos
• ns: nanossegundos

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

-- 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 indicando o versão do otimizador. A versão é um número inteiro ou "LATEST".

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

Define a versão do otimizador a ser usada para todas as instruções a seguir 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 é ''.

-- Set the optimizer version to 5 and execute a query.
SET OPTIMIZER_VERSION = '5';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_STATISTICS_PACKAGE

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

SHOW VARIABLE OPTIMIZER_STATISTICS_PACKAGE
SET OPTIMIZER_STATISTICS_PACKAGE = { 'package'|'' }

Define o pacote de estatísticas do otimizador a ser usado para todas as instruções a seguir em a conexão. <package> precisa ser um nome de pacote válido. Se nenhum pacote de estatísticas do otimizador estiver definido, o Spanner vai usar o pacote de estatísticas do otimizador definido no nível do banco de dados.

O padrão é ''.

-- Show the available optimizer statistics packages in this database.
SELECT * FROM INFORMATION_SCHEMA.SPANNER_STATISTICS;

-- Set the optimizer statistics package and execute a query.
SET OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

RETURN_COMMIT_STATS

Uma propriedade do tipo BOOL que indica se as estatísticas precisam ser retornadas para as transações nessa conexão. Para conferir as estatísticas retornadas, execute o comando SHOW VARIABLE COMMIT_RESPONSE.

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }

O padrão é false.

-- 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 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 RPC_PRIORITY
SET RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

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

O padrão é 'NULL'.

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

STATEMENT_TAG

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

SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'

Define a tag de solicitação para a próxima instrução a ser executada. Apenas uma tag pode ser definida por instrução. A tag não abrange várias instruções. Ela precisa ser definida por instrução. Uma tag de solicitação pode ser removida definindo-a como a string vazia ('').

O padrão é ''.

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

Também é possível usar uma dica de instrução para adicionar uma tag de instrução:

@{STATEMENT_TAG='my-tag'} SELECT * FROM Albums

Para mais informações, consulte Resolver problemas com tags de solicitação e tags de transação.

-- Set the statement tag that should be included with the next statement.
SET STATEMENT_TAG = 'tag1';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

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

TRANSACTION_TAG

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

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

Define a tag da transação atual a ser executada. Só um tag pode ser definida por transação. A tag não abrange várias transações. Ela precisa ser definida por transação. Uma tag de transação pode ser removida definindo-o como a string vazia (''). A tag de transação precisa ser definida antes instruções foram executadas na transação.

O padrão é ''.

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

Para mais informações, consulte Resolver problemas com tags de solicitação e tags de transação.

BEGIN;
-- Set the transaction tag for the current transaction.
SET TRANSACTION_TAG = 'transaction-tag-1';

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

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

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

COMMIT;

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

Instruções da transação

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

READ_TIMESTAMP

SHOW VARIABLE READ_TIMESTAMP

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

-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp that was used for the previous query.
SHOW VARIABLE READ_TIMESTAMP;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT Title
FROM Albums
ORDER BY Title;

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

COMMIT;

COMMIT_TIMESTAMP

SHOW VARIABLE COMMIT_TIMESTAMP

Retorna um conjunto de resultados com uma linha e uma coluna do tipo TIMESTAMP que contém o carimbo de data/hora de consolidação da última transação de leitura e gravação confirmada pelo Spanner. Esta instrução retorna um carimbo de data/hora somente quando você a executa depois de confirmar uma transação de leitura/gravação e antes de executar qualquer instrução SELECT, DML ou de mudança de esquema subsequente. Caso contrário, o resultado é NULL.

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

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

COMMIT_RESPONSE

SHOW VARIABLE COMMIT_RESPONSE

Retorna um conjunto de resultados com uma linha e duas colunas:

• COMMIT_TIMESTAMP (type=TIMESTAMP) indica quando o evento transação 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 estará disponível somente se SET RETURN_COMMIT_STATS for definido como true antes da confirmação da transação.

-- Enable returning commit stats in addition to the commit timestamp.
SET RETURN_COMMIT_STATS = true;

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

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

BEGIN [TRANSACTION]

BEGIN [TRANSACTION]

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

• Use COMMIT ou ROLLBACK para encerrar uma transação.
• Se você ativou o modo AUTOCOMMIT, esta instrução temporariamente remove a conexão do modo AUTOCOMMIT. A conexão retorna ao modo AUTOCOMMIT quando a transação termina.
• O modo de transação é determinado pela configuração atual do READONLY para esta uma conexão com a Internet. Esse valor é definido usando o método SET READONLY = {TRUE | FALSE} kubectl.
• Para mudar o modo de transação, execute SET TRANSACTION READ ONLY. ou SET TRANSACTION READ WRITE logo após a execução BEGIN [TRANSACTION]

Execute esta instrução apenas enquanto não houver uma transação ativa.

-- This starts a transaction using the current defaults of this connection.
-- The value of READONLY determines whether the transaction is a
-- read-write or a read-only transaction.

BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Set READONLY to TRUE to use read-only transactions by default.
SET READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

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

COMMIT [TRANSACTION]

COMMIT [TRANSACTION]

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

• A confirmação de uma transação de leitura e gravação torna todas as atualizações desta transação visíveis para outras transações e libera todos os bloqueios da transação no Spanner.
• A confirmação de uma transação somente leitura encerra a transação somente leitura atual. Qualquer instrução subsequente inicia uma nova transação. Não há diferença semântica entre COMMIT e ROLLBACK para uma transação somente leitura.

É possível executar essa instrução somente quando houver uma transação ativa.

-- Execute a regular read-write transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Execute a read-only transaction. Read-only transactions also need to be
-- either committed or rolled back in the Spanner JDBC driver in order
-- to mark the end of the transaction.
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

ROLLBACK [TRANSACTION]

ROLLBACK [TRANSACTION]

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

• A realização de um ROLLBACK de uma transação de leitura e gravação limpa todas as mutações armazenadas em buffer, reverte a transação no Spanner e libera todos os bloqueios retidos pela transação.
• Realizar um ROLLBACK de uma transação somente leitura encerra a transação somente leitura atual. Qualquer instrução subsequente inicia uma nova transação. Não há diferença semântica entre COMMIT e ROLLBACK para uma transação somente leitura em uma conexão.

É possível executar essa instrução somente quando houver uma transação ativa.

-- Use ROLLBACK to undo the effects of a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
-- This ensures that the insert statement is not persisted in the database.
ROLLBACK;

-- Read-only transactions also need to be either committed or rolled back in the
-- Spanner JDBC driver in order to mark the end of the transaction.
-- There is no semantic difference between rolling back or committing a
-- read-only transaction.
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Define o modo de transação da transação atual.

Execute essa instrução somente quando AUTOCOMMIT for false ou se você tiver iniciado uma transação executando BEGIN [TRANSACTION] e ainda não tiver executado nenhuma instrução na transação.

Essa instrução define o modo apenas da transação atual. Quando confirmar ou reverter a transação, a próxima transação usará o para a conexão (consulte SET READONLY).

-- Start a transaction and set the transaction mode to read-only.
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Commit the read-only transaction to mark the end of the transaction.
COMMIT;

-- Start a transaction and set the transaction mode to read-write.
BEGIN;
SET TRANSACTION READ WRITE;

INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

Instruções em lote

As instruções a seguir gerenciam lotes de instruções DDL e 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 enviadas ao Spanner como um lote quando você executa RUN BATCH. Executar várias instruções DDL como um lote é, geralmente, mais rápido do que executá-las separadamente.

Execute esta instrução apenas enquanto não houver uma transação ativa.

-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Singers (
  SingerId  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

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

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

RUN BATCH

RUN BATCH

Envia todas as instruções DDL armazenadas em buffer no lote DDL atual para o banco de dados, aguarda o Spanner executar essas instruções e encerra o lote DDL atual.

Se o Spanner não puder executar pelo menos uma instrução DDL, RUN BATCH retorna um erro para a primeira instrução DDL que o Spanner não pode a serem executados. Caso contrário, RUN BATCH retorna com sucesso.

ABORT BATCH [TRANSACTION]

Limpa todas as instruções DDL armazenadas em buffer no lote DDL e encerra o lote.

Execute essa instrução somente quando um lote DDL estiver ativo. É possível usar ABORT BATCH independentemente do lote ter ou não instruções DDL armazenadas em buffer. Todas as instruções DDL anteriores no lote serão canceladas.

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

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;

-- Start a DML batch. All following statements must be a DML statement.
START BATCH DML;

-- The following statements are buffered locally.
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');

-- This sends the statements to Spanner.
RUN BATCH;

-- DML batches can also be part of a read/write transaction.
BEGIN;
-- Insert a row using a single statement.
INSERT INTO MYTABLE (ID, NAME) VALUES (3, 'THREE');

-- Insert two rows using a batch.
START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (4, 'FOUR');
INSERT INTO MYTABLE (ID, NAME) VALUES (5, 'FIVE');
RUN BATCH;

-- Rollback the current transaction. This rolls back both the single DML
-- statement and the DML batch.
ROLLBACK;

Data Boost e instruções de consulta particionadas

A API partitionQuery divide uma consulta em partes menores, ou partições, e usa várias máquinas para buscar as partições em paralelo. Cada partição é identificada 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.

O Data Boost permite executar consultas de análise e exportações de dados com impacto quase zero nas cargas de trabalho atuais na instância provisionada do Spanner. O Data Boost só é compatível com consultas particionadas.

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

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

• SET AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql seguido por vários RUN PARTITION 'partition-token'

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

DATA_BOOST_ENABLED

Uma propriedade do tipo BOOL que indica se essa conexão precisa usar o Data Boost para consultas particionadas. O padrão é false.

SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

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

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

Para conferir um exemplo completo, consulte DataBoostExample.

AUTO_PARTITION_MODE

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

SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}

• Defina essa variável como true se quiser que a conexão use particionada para todas as consultas executadas.
• Defina DATA_BOOST_ENABLED como true se quiser que a conexão use o Data Boost para todas as consultas.

O padrão é false.

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

Para um exemplo completo, consulte AutoPartitionModeExample.

EXECUTAR CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

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

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

O driver JDBC do Spanner particiona internamente a consulta e executa partições em paralelo. Os resultados são mesclados em um conjunto de resultados e retornados ao aplicativo. O número de linhas de execução de workers que executam partições pode ser definido com a variável MAX_PARTITIONED_PARALLELISM.

Para conferir um exemplo completo, consulte RunPartitionedQueryExample.

PARTITION <SQL>

PARTITION <sql>

Cria uma lista de partições para executar uma consulta no Spanner e retorna uma lista de tokens de partição. Cada token de partição pode ser executadas em uma conexão separada no mesmo cliente ou em outro, usando o RUN PARTITION 'partition-token'.

-- Partition a query. This returns a list of partition tokens that can be
-- executed either on this connection or on any other connection to the same
-- database.
PARTITION SELECT FirstName, LastName FROM Singers;

-- Run the partitions that were returned from the previous statement.
RUN PARTITION 'partition-token-1';
RUN PARTITION 'partition-token-2';

Para conferir um exemplo completo, consulte PartitionQueryExample.

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

Executa uma partição de consulta que foi retornada anteriormente pelo comando PARTITION. O comando pode ser executado em qualquer conexão conectada ao mesmo banco de dados que criou os tokens de partição.

MAX_PARTITIONED_PARALLELISM

Uma propriedade do tipo INT64 que indica o número de linhas de execução de worker que o driver JDBC do Spanner usa para executar partições. Esse valor é usado para:

• AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

Define o número máximo de linhas de execução de worker que o driver JDBC do Spanner que pode ser usado para executar partições. A definição desse valor como 0 instrui o driver JDBC do Spanner a usar o número de núcleos de CPU na máquina cliente como o máximo.

O padrão é 0.

Instruções de leitura direcionadas

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

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

Para mais informações, consulte Leituras direcionadas.

Comandos do Savepoint

As instruções a seguir ativam e desativam emulados savepoints 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 pontos de salvamento são emulados mantendo o controle de uma soma de verificação em execução para os resultados retornados por instruções na transação. Ao reverter para um ponto de salvamento, o driver JDBC do Spanner reverte a transação e tenta novamente até o ponto em que o ponto de salvamento foi definido. A soma de verificação dos nova tentativa é comparada à soma de verificação da transação inicial para verificar se o resultados iguais foram retornados.

SAVEPOINT_SUPPORT

SHOW VARIABLE SAVEPOINT_SUPPORT
SET SAVEPOINT_SUPPORT = { '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 de ponto de salvamento são desativados e vão falhar.
• 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 falha se você tentar usá-la após 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.

try (Connection connection =
    DriverManager.getConnection(
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            "my-project", "my-instance", "my-database"))) {
  // Savepoints can only be used when AutoCommit=false.
  connection.setAutoCommit(false);

  // Disables setting a savepoint.
  connection.createStatement().execute("SET SAVEPOINT_SUPPORT='DISABLED'");
  // The following statement fails because savepoints have been disabled.
  connection.setSavepoint("my_savepoint1");

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

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

A seguir

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