O driver JDBC (Java Database Connectivity) do Spanner oferece suporte a instruções de gerenciamento de sessão, que permitem modificar o estado da conexão, executar transações e executar lotes de instruções com eficiência.
Os comandos a seguir se aplicam aos bancos de dados de dialeto PostgreSQL.
Instruções de conexão
As instruções a seguir alteram ou exibem as propriedades da conexão atual.
SPANNER.READONLY
Um booleano que indica se a conexão está ou não no modo somente leitura. O
padrão é false
.
SHOW [VARIABLE] SPANNER.READONLY
SET SPANNER.READONLY {TO|=} { true | false }
Só é possível mudar o valor dessa propriedade enquanto não há uma transação ativa.
▶ Exemplo: transação somente leitura (clique para expandir)
O exemplo a seguir mostra como usar essa propriedade para executar operações
transações no Spanner.
SET SPANNER.READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;
-- The following two queries both use the read-only transaction.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
SELECT Title
FROM Albums
ORDER BY Title;
-- This shows the read timestamp that was used for the two queries.
SHOW SPANNER.READ_TIMESTAMP;
-- This marks the end of the read-only transaction. The next statement starts
-- a new read-only transaction.
COMMIT;
AUTOCOMMIT
Um booleano que indica se a conexão está ou não no modo de confirmação automática. O
padrão é true
.
SHOW [VARIABLE] AUTOCOMMIT
SET AUTOCOMMIT {TO|=} { true | false }
Só é possível mudar o valor dessa propriedade quando não há nenhuma transação.
Quando AUTOCOMMIT
for definido como falso, uma nova transação será iniciada automaticamente
depois de executar COMMIT
ou ROLLBACK
. A primeira instrução executada
inicia a transação.
▶ Exemplo: confirmação automática (clique para expandir)
O exemplo a seguir mostra como usar a propriedade autocommit
.
-- The default value for AUTOCOMMIT is true.
SHOW AUTOCOMMIT;
-- This insert statement is automatically committed after it is executed, as
-- the connection is in autocommit mode.
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);
-- Turning off autocommit means that a new transaction is automatically started
-- when the next statement is executed.
SET AUTOCOMMIT = FALSE;
-- The following statement starts a new transaction.
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);
-- This statement uses the same transaction as the previous statement.
INSERT INTO T (id, col_a, col_b) VALUES (3, 300, 3);
-- Commit the current transaction with the two INSERT statements.
COMMIT;
-- Transactions can also be executed in autocommit mode by executing the BEGIN
-- statement.
SET AUTOCOMMIT = FALSE;
-- Execute a transaction while in autocommit mode.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (4, 400, 4);
INSERT INTO T (id, col_a, col_b) VALUES (5, 500, 5);
COMMIT;
SPANNER.RETRY_ABORTS_INTERNALLY
Um booleano que indica se a conexão é cancelada automaticamente e de novo
transações. O padrão é true
.
SHOW [VARIABLE] SPANNER.RETRY_ABORTS_INTERNALLY
SET SPANNER.RETRY_ABORTS_INTERNALLY {TO|=} { true | false }
Só é possível mudar o valor dessa propriedade depois que uma transação é iniciada
(consulte BEGIN TRANSACTION
) e antes
instruções são executadas dentro da transação.
Quando você define SPANNER.RETRY_ABORTS_INTERNALLY
como verdadeiro, a conexão mantém uma soma de verificação de todos os dados que a conexão retorna ao aplicativo cliente. Isso
é usado para repetir a transação se ela for cancelada pelo Spanner.
O valor padrão é true
. Recomendamos definir esse valor como false
se
seu aplicativo já tenta novamente as transações canceladas.
SPANNER.AUTOCOMMIT_DML_MODE
Uma propriedade STRING
indicando o modo de confirmação automática para
Instruções de linguagem de manipulação de dados (DML, na sigla em inglês).
SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }
Os valores possíveis são:
- No modo
TRANSACTIONAL
, o driver executa instruções DML como transações atômicas separadas. O driver cria uma nova transação, executa a instrução DML e realiza a confirmação da transação após a execução bem-sucedida ou reverte a transação no caso de um erro. - No modo
PARTITIONED_NON_ATOMIC
, o driver executa instruções DML como instruções de atualização particionadas. Um particionado update pode ser executada como uma série de diversas transações, cada uma cobrindo um subconjunto das linhas afetadas. A instrução particionada fornece semântica enfraquecida em troca de melhor escalonabilidade e desempenho.
O padrão é TRANSACTIONAL
.
▶ Exemplo: DML particionada (clique para expandir)
O exemplo a seguir mostra como executar
DML particionada usando a
Driver JDBC do Spanner.
-- Change autocommit DML mode to use Partitioned DML.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'PARTITIONED_NON_ATOMIC';
-- Delete all singers that have been marked as inactive.
-- This statement is executed using Partitioned DML.
DELETE
FROM singers
WHERE active=false;
-- Change DML mode back to standard `TRANSACTIONAL`.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';
STATEMENT_TIMEOUT
Uma propriedade do tipo STRING
indicando o valor de tempo limite atual para instruções.
SHOW [VARIABLE] STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT {TO|=} { '<int8>{ s | ms | us | ns }' | <int8> | DEFAULT }
O valor int8
é um número inteiro seguido por um sufixo que indica a unidade de
tempo. DEFAULT
significa 0 segundo, equivalente a nenhum tempo limite. Um
O número int8
sem unidades indica em ms. Se um valor de tempo limite da instrução tiver sido
definido, as instruções que demoram mais do que o valor de tempo limite especificado causarão uma
java.sql.SQLTimeoutException
e invalidar a transação.
Os blocos de tempo compatíveis são estes:
s
: segundosms
: milésimos de segundous
: microssegundosns
: nanossegundos
O padrão é 0, o que significa que não há tempo limite.
O tempo limite de uma instrução durante uma transação invalida a transação, todas
instruções subsequentes na transação invalidada (exceto ROLLBACK
) falham;
e o driver JDBC do Spanner gera uma java.sql.SQLTimeoutException
.
SPANNER.READ_ONLY_STALENESS
Uma propriedade do tipo STRING
indicando o valor
de inatividade somente leitura
O Spanner usa para consultas e transações somente leitura em AUTOCOMMIT
modo
SHOW [VARIABLE] SPANNER.READ_ONLY_STALENESS SET SPANNER.READ_ONLY_STALENESS {TO|=} staleness_type staleness_type: { 'STRONG' | 'MIN_READ_TIMESTAMP timestamp' | 'READ_TIMESTAMP timestamp' | 'MAX_STALENESS <int8>{ s | ms | us | ns }' | 'EXACT_STALENESS <int8>{ s | ms | us | ns }' }
O valor de inatividade somente leitura se aplica a todos
transações somente leitura subsequentes e para todas as consultas no modo AUTOCOMMIT
.
O padrão é STRONG
.
As opções de limite de carimbo de data/hora são as seguintes:
STRONG
diz ao Spanner para executar uma leitura forte.MAX_STALENESS
define o intervalo de tempo que o Spanner usa para realizar uma leitura de inatividade limitada, relativa anow()
.MIN_READ_TIMESTAMP
define um tempo absoluto que o Spanner usa para perform uma leitura de inatividade limitada.EXACT_STALENESS
define o intervalo de tempo que o Spanner usa para realizar uma leitura exata de inatividade, relativa anow()
.READ_TIMESTAMP
define um tempo absoluto que o Spanner usa para executar uma leitura de inatividade exata.
Os carimbo de data/hora precisam usar o seguinte formato:
YYYY-[M]M-[D]DT[[H]H:[M]M:[S]S[.DDDDDD]][timezone]
As unidades de tempo compatíveis para definir os valores MAX_STALENESS
e EXACT_STALENESS
são estes:
s
: segundosms
: milésimos de segundous
: microssegundosns
: nanossegundos
Só é possível modificar o valor desta propriedade quando não há transação.
▶ Exemplo: desatuação somente leitura (clique para expandir)
O exemplo a seguir mostra como executar consultas usando uma inatividade personalizada.
com o driver JDBC do Spanner.
-- Set the read-only staleness to MAX_STALENESS 10 seconds.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 10s';
-- Execute a query in auto-commit mode. This returns results that are up to
-- 10 seconds stale.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is only allowed for queries in autocommit mode.
-- Change the staleness to EXACT_STALENESS and start a read-only transaction.
SET SPANNER.READ_ONLY_STALENESS = 'EXACT_STALENESS 10s';
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
SELECT Title, SingerId
FROM Albums
ORDER BY Title;
COMMIT;
-- Set the read staleness to an exact timestamp.
SET SPANNER.READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
SPANNER.OPTIMIZER_VERSION
Uma propriedade do tipo STRING
indicando o
versão do otimizador. A versão é
um número inteiro ou "LATEST
".
SHOW [VARIABLE] SPANNER.OPTIMIZER_VERSION
SET SPANNER.OPTIMIZER_VERSION {TO|=} { 'version'|'LATEST'|'' }
Define a versão do otimizador a ser usada para todas as instruções a seguir em
a conexão. Se a versão do otimizador estiver definida como ''
(a string vazia),
O Spanner usa a versão mais recente. Se nenhuma versão do otimizador for definida,
O Spanner usa a versão do otimizador definida no banco de dados
nível
O padrão é ''
.
▶ Exemplo: versão do otimizador (clique para expandir)
O exemplo a seguir mostra como executar consultas usando uma
da versão do otimizador com a
Driver JDBC do Spanner.
-- Set the optimizer version to 5 and execute a query.
SET SPANNER.OPTIMIZER_VERSION = '5';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Execute the same query with the latest optimizer version.
SET SPANNER.OPTIMIZER_VERSION = 'LATEST';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Revert back to using the default optimizer version that has been set for the
-- database.
SET SPANNER.OPTIMIZER_VERSION = '';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
SPANNER.OPTIMIZER_STATISTICS_PACKAGE
Uma propriedade do tipo STRING
indicando o valor
pacote de estatísticas do otimizador
que é usado por essa conexão.
SHOW [VARIABLE] SPANNER.OPTIMIZER_STATISTICS_PACKAGE
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE {TO|=} { 'package'|'' }
Define o pacote de estatísticas do otimizador a ser usado para todas as instruções seguintes na
conexão. <package>
precisa ser um nome de pacote válido. Se não houver otimizador
o pacote de estatísticas estiver definido, o Spanner vai usar as estatísticas do otimizador
que é definido no nível do banco de dados.
O padrão é ''
.
▶ Exemplo: pacote de estatísticas do otimizador (clique para expandir)
O exemplo a seguir mostra como executar consultas usando uma
pacote de estatísticas do otimizador com
e o driver JDBC do Spanner.
-- Show the available optimizer statistics packages in this database.
SELECT * FROM INFORMATION_SCHEMA.SPANNER_STATISTICS;
-- Set the optimizer statistics package and execute a query.
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Execute the same query with the default optimizer statistics package.
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE = '';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
SPANNER.RETURN_COMMIT_STATS
Uma propriedade do tipo BOOL
que indica se estatísticas devem ser retornadas para
transações nesta conexão. Você pode conferir as estatísticas retornadas executando
o comando SHOW SPANNER.COMMIT_RESPONSE
.
SHOW [VARIABLE] SPANNER.RETURN_COMMIT_STATS
SET SPANNER.RETURN_COMMIT_STATS {TO|=} { true | false }
O padrão é false
.
▶ Exemplo: estatísticas de commit (clique para expandir)
O exemplo a seguir mostra como visualizar estatísticas de confirmação de uma transação
com o driver JDBC do Spanner.
-- Enable the returning of commit stats.
SET SPANNER.RETURN_COMMIT_STATS = true;
-- Execute a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);
COMMIT;
-- View the commit response with the transaction statistics for the last
-- transaction that was committed.
SHOW SPANNER.COMMIT_RESPONSE;
SPANNER.RPC_PRIORITY
Uma propriedade do tipo STRING
indicando a prioridade relativa para
solicitações do Spanner. A prioridade serve como uma dica para a
Programador do Spanner e não garante a ordem de execução.
SHOW [VARIABLE] SPANNER.RPC_PRIORITY
SET SPANNER.RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}
'NULL'
significa que nenhuma dica precisa ser incluída na solicitação.
O padrão é 'NULL'
.
Também é possível usar uma dica de instrução para especificar a prioridade da RPC:
/*@RPC_PRIORITY=PRIORITY_LOW*/ SELECT * FROM Albums
Para ver mais informações, consulte Priority
.
Tags
As instruções a seguir gerenciam as tags de solicitação e de transação.
SPANNER.STATEMENT_TAG
Uma propriedade do tipo STRING
que contém a tag de solicitação para o próximo
instrução.
SHOW [VARIABLE] SPANNER.STATEMENT_TAG
SET SPANNER.STATEMENT_TAG {TO|=} 'tag-name'
Define a tag de solicitação para a próxima instrução a ser executada. Só um
tag pode ser definida por instrução. A tag não abrange várias instruções.
deve ser definido por instrução. Para remover uma tag de solicitação, configure-a
à string vazia (''
).
O padrão é ''
.
É possível definir tags de transação e tags de instrução para a mesma instrução.
Você também pode usar uma dica de instrução para adicionar uma tag de instrução:
/*@STATEMENT_TAG='my-tag'*/ SELECT * FROM Albums
Para mais informações, consulte Resolver problemas com tags de solicitação e de transação
▶ Exemplo: tags de instrução (clique para expandir)
O exemplo abaixo mostra como definir tags de instrução com o
Driver JDBC do Spanner.
-- Set the statement tag that should be included with the next statement.
SET SPANNER.STATEMENT_TAG = 'tag1';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- The statement tag property is cleared after each statement execution.
SHOW SPANNER.STATEMENT_TAG;
-- Set another tag for the next statement.
SET SPANNER.STATEMENT_TAG = 'tag2';
SELECT Title
FROM Albums
ORDER BY Title;
-- Set a statement tag with a query hint.
/*@STATEMENT_TAG='tag3'*/
SELECT TrackNumber, Title
FROM Tracks
WHERE AlbumId=1 AND SingerId=1
ORDER BY TrackNumber;
SPANNER.TRANSACTION_TAG
Uma propriedade do tipo STRING
que contém a tag de transação para o próximo
transação.
SHOW [VARIABLE] SPANNER.TRANSACTION_TAG
SET SPANNER.TRANSACTION_TAG {TO|=} 'tag-name'
Define a tag da transação atual a ser executada. Apenas uma tag pode ser definida por transação. A tag não abrange várias transações.
precisam ser definidos por transação. Uma tag de transação pode ser removida
definindo-a como uma string vazia (''
). A tag de transação precisa ser definida antes
de qualquer instrução ser executada na transação.
O padrão é ''
.
É possível definir tags de transação e tags de instrução para a mesma instrução.
Para mais informações, consulte Resolver problemas com tags de solicitação e de transação
▶ Exemplo: tags de transação (clique para expandir)
O exemplo a seguir mostra como definir tags de transação com o
Driver JDBC do Spanner.
BEGIN;
-- Set the transaction tag for the current transaction.
SET SPANNER.TRANSACTION_TAG = 'transaction-tag-1';
-- Set the statement tag that should be included with the next statement.
-- The statement will include both the statement tag and the transaction tag.
SET SPANNER.STATEMENT_TAG = 'select-statement';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- The statement tag property is cleared after each statement execution.
SHOW SPANNER.STATEMENT_TAG;
-- Set another tag for the next statement.
SET SPANNER.STATEMENT_TAG = 'insert-statement';
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;
-- The transaction tag property is cleared when the transaction finishes.
SHOW SPANNER.TRANSACTION_TAG;
Instruções da transação
As instruções a seguir gerenciam e confirmam as transações do Spanner.
NÍVEL DE ISOLAMENTO DE TRANSAÇÃO
SHOW [VARIABLE] TRANSACTION ISOLATION LEVEL
Retorna um conjunto de resultados com uma linha e uma coluna do tipo STRING
. O valor
retornado é sempre serializable
.
SPANNER.READ_TIMESTAMP
SHOW [VARIABLE] SPANNER.READ_TIMESTAMP
Retorna um conjunto de resultados com uma linha e uma coluna do tipo TIMESTAMP
que contém a leitura do carimbo de data/hora da transação somente leitura mais recente. Essa instrução retorna um carimbo de data/hora apenas quando uma transação somente leitura ainda está ativa e executou pelo menos uma consulta ou imediatamente após uma transação somente leitura ser confirmada e antes de uma nova transação. Caso contrário, o resultado será NULL
.
▶ Exemplo: leitura de carimbo de data/hora (clique para expandir)
O exemplo a seguir mostra como exibir o carimbo de data/hora da última leitura de um
operação somente leitura com o driver JDBC do Spanner.
-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Show the read timestamp that was used for the previous query.
SHOW SPANNER.READ_TIMESTAMP;
-- Set a non-deterministic read-only staleness and execute the same query.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 20s';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Show the read timestamp that was used for the previous query. The timestamp
-- is determined by Spanner, and is guaranteed to be no less than
-- 20 seconds stale.
SHOW SPANNER.READ_TIMESTAMP;
-- The read timestamp of a read-only transaction can also be retrieved.
SET SPANNER.READ_ONLY_STALENESS = 'STRONG';
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Show the read timestamp of the current read-only transaction. All queries in
-- this transaction will use this read timestamp.
SHOW SPANNER.READ_TIMESTAMP;
SELECT Title
FROM Albums
ORDER BY Title;
-- The read timestamp is the same as for the previous query, as all queries in
-- the same transaction use the same read timestamp.
SHOW SPANNER.READ_TIMESTAMP;
COMMIT;
SPANNER.COMMIT_TIMESTAMP
SHOW [VARIABLE] SPANNER.COMMIT_TIMESTAMP
Retorna um conjunto de resultados com uma linha e uma coluna do tipo TIMESTAMP
contendo
o carimbo de data/hora de confirmação da última transação de leitura/gravação que
O Spanner está comprometido. Essa instrução retorna um carimbo de data/hora apenas quando você o executa, depois de confirmar uma transação de leitura e gravação e antes de executar qualquer SELECT
, DML
ou instruções de alteração de esquema subsequentes. Caso contrário, o
resultado é NULL
.
▶ Exemplo: carimbo de data/hora de confirmação (clique para expandir)
O exemplo a seguir mostra como exibir o último carimbo de data/hora de commit de um
com o driver JDBC do Spanner.
-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);
-- Show the timestamp that the statement was committed.
SHOW SPANNER.COMMIT_TIMESTAMP;
SPANNER.COMMIT_RESPONSE
SHOW [VARIABLE] SPANNER.COMMIT_RESPONSE
Retorna um conjunto de resultados com uma linha e duas colunas:
COMMIT_TIMESTAMP
(type=TIMESTAMP
) indica quando o evento transação foi confirmada.MUTATION_COUNT
(type=INT64
) indica quantas mutações foram aplicadas em a transação confirmada. Este valor está sempre vazio quando executado no emulador.
A contagem de mutações só estará disponível se SET SPANNER.RETURN_COMMIT_STATS
tiver sido
definido como true
antes da confirmação da transação.
▶ Exemplo: resposta de confirmação (clique para expandir)
O exemplo a seguir mostra como visualizar a última resposta de confirmação de um
com o driver JDBC do Spanner.
-- Enable returning commit stats in addition to the commit timestamp.
SET SPANNER.RETURN_COMMIT_STATS = true;
-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);
-- Show the timestamp that the statement was committed.
SHOW SPANNER.COMMIT_RESPONSE;
{ START | COMEÇAR } [ TRANSAÇÃO | TRABALHO ]
{ START | BEGIN } [ TRANSACTION | WORK ] [{ READ ONLY | READ WRITE }]
Inicia uma nova transação. As palavras-chave TRANSACTION
e WORK
são opcionais,
equivalentes e não têm efeito.
- Use
COMMIT
ouROLLBACK
para encerrar uma transação. - Se você ativou o modo
AUTOCOMMIT
, esta instrução temporariamente remove a conexão do modoAUTOCOMMIT
. A conexão retorna ao modoAUTOCOMMIT
quando a transação termina. - Se
READ ONLY
ouREAD WRITE
não for especificado, o modo de transação será determinado pelo modo de transação padrão da sessão. Esse padrão é definido usando o comandoSET SESSION CHARACTERISTICS AS TRANSACTION
ou definindo a variávelREADONLY
.
Execute esta instrução apenas enquanto não houver uma transação ativa.
▶ Exemplo: "BEGIN TRANSACTION" (clique para expandir)
O exemplo a seguir mostra como iniciar diferentes tipos de transações com
e o driver JDBC do Spanner.
-- This starts a transaction using the current defaults of this connection.
-- The value of READONLY determines whether the transaction is a
-- read-write or a read-only transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;
-- Set READONLY to TRUE to use read-only transactions by default.
SET READONLY=TRUE;
-- This starts a read-only transaction.
BEGIN;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;
-- Add 'READ WRITE' or 'READ ONLY' to the 'BEGIN' command to
-- override the current default of the connection.
SET READONLY=FALSE;
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;
COMMIT [TRANSACTION | WORK]
COMMIT [ TRANSACTION | WORK ]
Confirma a transação atual. As palavras-chave TRANSACTION
e WORK
são
opcionais e equivalentes, e não têm efeito.
- Confirmar uma transação de leitura e gravação faz todas as atualizações dessa transação fica visível para outras transações e libera todos os bloqueios da transação no Spanner.
- A confirmação de uma transação somente leitura encerra a transação somente leitura atual. Qualquer instrução subsequente inicia uma nova transação. Não há diferença semântica entre
COMMIT
eROLLBACK
para uma transação somente leitura.
É possível executar essa instrução somente quando houver uma transação ativa.
▶ Exemplo: COMMIT TRANSACTION (clique para expandir)
O exemplo a seguir mostra como confirmar uma transação com o
Driver JDBC do Spanner.
-- Execute a regular read-write transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;
-- Execute a read-only transaction. Read-only transactions also need to be
-- either committed or rolled back in the Spanner JDBC driver in order
-- to mark the end of the transaction.
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;
{ ABORT | ROLLBACK } [TRANSACTION | WORK]
{ ABORT | ROLLBACK } [TRANSACTION | WORK]
Executa um ROLLBACK
da transação atual. As palavras-chave TRANSACTION
e
WORK
são opcionais e equivalentes e não têm efeito.
- Realizar uma
ROLLBACK
de uma transação de leitura/gravação limpa todos os dados em buffer mutações, reverte a transação no Spanner e libera qualquer bloqueio que a transação tenha. - Realizar um
ROLLBACK
de uma transação somente leitura encerra a transação somente leitura atual. Qualquer instrução subsequente inicia uma nova transação. Não há diferença semântica entreCOMMIT
eROLLBACK
para uma transação somente leitura em uma conexão.
É possível executar essa instrução somente quando houver uma transação ativa.
▶ Exemplo: ROLLBACK TRANSACTION (clique para expandir)
O exemplo a seguir mostra como reverter uma transação com o
Driver JDBC do Spanner.
-- Use ROLLBACK to undo the effects of a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
-- This ensures that the insert statement is not persisted in the database.
ROLLBACK;
-- Read-only transactions also need to be either committed or rolled back in the
-- Spanner JDBC driver in order to mark the end of the transaction.
-- There is no semantic difference between rolling back or committing a
-- read-only transaction.
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;
SET TRANSACTION
SET TRANSACTION { READ ONLY | READ WRITE }
Define o modo de transação da transação atual.
Execute essa instrução somente quando AUTOCOMMIT
for false
ou se você tiver
iniciou uma transação executando BEGIN [TRANSACTION | WORK]
e não
mas executou quaisquer instruções na transação.
Essa instrução define o modo de transação apenas para a transação atual. Quando
confirmar ou reverter a transação, a próxima transação usará o
para a conexão.
Consulte SET SESSION CHARACTERISTICS
.
▶ Exemplo: SET TRANSACTION (clique para expandir)
O exemplo a seguir mostra como definir características de transação com o driver JDBC do Spanner.
-- Start a transaction and set the transaction mode to read-only.
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
-- Commit the read-only transaction to mark the end of the transaction.
COMMIT;
-- Start a transaction and set the transaction mode to read-write.
BEGIN;
SET TRANSACTION READ WRITE;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;
DEFINIR CARACTERÍSTICAS DA SESSÃO
SET SESSION CHARACTERISTICS AS TRANSACTION { READ ONLY | READ WRITE }
Define o modo de transação padrão para transações na sessão como
READ ONLY
ou READ WRITE
. Esta instrução só é permitida quando não há
transação ativa.
O comando SET TRANSACTION
pode substituir essa configuração.
Instruções em lote
As instruções a seguir gerenciam lotes de instruções DDL e enviam-nos para o Spanner.
START BATCH DDL
START BATCH DDL
Inicia um lote de instruções DDL na conexão. Todas as instruções subsequentes durante o lote precisam ser instruções DDL. As instruções DDL são armazenadas em buffer localmente
e enviada ao Spanner como um lote quando você executa RUN BATCH
.
Executar várias instruções DDL como um lote é, geralmente, mais rápido do que executá-las separadamente.
Execute esta instrução apenas enquanto não houver uma transação ativa.
▶ Exemplo: lote DDL (clique para expandir)
O exemplo a seguir mostra como executar um lote DDL com as
Driver JDBC do Spanner.
-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;
-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Singers (
SingerId BIGINT NOT NULL PRIMARY KEY,
FirstName VARCHAR,
LastName VARCHAR
);
-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Albums (
AlbumId BIGINT NOT NULL PRIMARY KEY,
Title VARCHAR,
SingerId BIGINT,
CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
);
-- This runs the DDL statements as one batch.
RUN BATCH;
RUN BATCH
RUN BATCH
Envia todas as instruções DDL armazenadas em buffer no lote DDL atual para o banco de dados, espera que o Spanner execute essas instruções e encerra a no lote de DDL atual.
Se o Spanner não puder executar pelo menos uma instrução DDL, RUN BATCH
retornará um erro para a primeira instrução DDL que o Spanner não puder
executar. Caso contrário, RUN BATCH
retorna com sucesso.
ABORT BATCH
ABORT BATCH
Limpa todas as instruções DDL armazenadas em buffer no lote DDL e encerra o lote.
Execute essa instrução somente quando um lote DDL estiver ativo. É possível usar ABORT BATCH
independentemente do lote ter ou não instruções DDL armazenadas em buffer. Todas as instruções DDL anteriores no lote serão canceladas.
▶ Exemplo: interromper o lote de DDL (clique para expandir)
O exemplo a seguir mostra como cancelar um lote DDL com as
Driver JDBC do Spanner.
-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;
-- The following statements are buffered locally.
CREATE TABLE Singers (
SingerId BIGINT NOT NULL PRIMARY KEY,
FirstName VARCHAR,
LastName VARCHAR
);
-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Albums (
AlbumId BIGINT NOT NULL PRIMARY KEY,
Title VARCHAR,
SingerId BIGINT,
CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
);
-- This aborts the DDL batch and removes the DDL statements from the buffer.
ABORT BATCH;
INICIAR BATCH DML e EXECUTAR LOTE
As instruções a seguir agrupam as duas instruções DML e as enviam em uma chamada para o servidor. Um lote DML pode ser executado como parte de uma transação ou no modo de confirmação automática.
START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
RUN BATCH;
▶ Exemplo: lote de DML (clique para expandir)
O exemplo a seguir mostra como executar um lote DML com a
Driver JDBC do Spanner.
-- Start a DML batch. All following statements must be a DML statement.
START BATCH DML;
-- The following statements are buffered locally.
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
-- This sends the statements to Spanner.
RUN BATCH;
-- DML batches can also be part of a read/write transaction.
BEGIN;
-- Insert a row using a single statement.
INSERT INTO MYTABLE (ID, NAME) VALUES (3, 'THREE');
-- Insert two rows using a batch.
START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (4, 'FOUR');
INSERT INTO MYTABLE (ID, NAME) VALUES (5, 'FIVE');
RUN BATCH;
-- Rollback the current transaction. This rolls back both the single DML
-- statement and the DML batch.
ROLLBACK;
Data Boost e instruções de consulta particionadas
A partitionQuery divide a consulta em partes menores, ou partições, e usa várias para buscar as partições em paralelo. Cada partição é identificada por uma token de partição. A API PartitionQuery tem latência maior que a API API de consulta, já que ela se destina apenas a operações em massa, como exportar ou verificar todo o banco de dados.
Otimização de dados você executa consultas analíticas e exportações de dados com nas cargas de trabalho atuais na instância provisionada do Spanner. O Data Boost só é compatível com consultas particionadas.
É possível ativar o Data Boost na conexão atual com o
Instrução SET SPANNER.DATA_BOOST_ENABLED
.
O driver JDBC oferece suporte a três alternativas para executar consultas particionadas:
SET SPANNER.AUTO_PARTITION_MODE = true
RUN PARTITIONED QUERY sql
PARTITION sql
seguido por váriosRUN PARTITION 'partition-token'
Cada um desses métodos é descrito nas seções a seguir.
SPANNER.DATA_BOOST_ENABLED
Uma propriedade do tipo BOOL
que indica se essa conexão deve usar
Otimização de dados para consultas particionadas. O padrão
é false
.
SHOW [VARIABLE] SPANNER.DATA_BOOST_ENABLED
SET SPANNER.DATA_BOOST_ENABLED {TO|=} { true | false }
Define se esta conexão deve usar Otimização de dados para consultas particionadas.
O padrão é false
.
▶ Exemplo: executar uma consulta usando o Data Boost (clique para expandir)
O exemplo a seguir mostra como fazer uma consulta usando o Data Boost com o
Driver JDBC do Spanner.
-- Enable Data Boost on this connection.
SET SPANNER.DATA_BOOST_ENABLED = true;
-- Execute a partitioned query. Data Boost is only used for partitioned queries.
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers;
Para um exemplo completo, consulte PostgreSQL DataBoostExample.
SPANNER.AUTO_PARTITION_MODE
Uma propriedade do tipo BOOL
que indica se a conexão usa automaticamente
particionadas para todas as consultas executadas.
SHOW [VARIABLE] SPANNER.AUTO_PARTITION_MODE
SET SPANNER.AUTO_PARTITION_MODE {TO|=} { true | false}
- Defina essa variável como
true
se quiser que a conexão use particionada para todas as consultas executadas. - Também defina
SPANNER.DATA_BOOST_ENABLED
comotrue
se quiser que a conexão para usar o Data Boost para todos consultas.
O padrão é false
.
▶ Exemplo: executar (clique para expandir)
Este exemplo executa duas consultas com o driver JDBC do Spanner usando
Otimização de dados
SET SPANNER.AUTO_PARTITION_MODE = true
SET SPANNER.DATA_BOOST_ENABLED = true
SELECT FirstName, LastName FROM Singers
SELECT SingerId, Title FROM Albums
Para um exemplo completo, consulte PostgreSQL AutoPartitionModeExample.
EXECUTAR CONSULTA PARTICIONADA
RUN PARTITIONED QUERY <sql>
Executa uma consulta como uma consulta particionada no Spanner. Verifique se
SPANNER.DATA_BOOST_ENABLED
está definido como true
para executar a consulta com
Otimização de dados:
SET SPANNER.DATA_BOOST_ENABLED = true
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers
O driver JDBC particiona internamente a consulta e executa partições
em paralelo. Os resultados são mesclados em um conjunto de resultados e retornados ao
para o aplicativo. O número de linhas de execução de trabalho que executam partições pode ser definido com
a variável SPANNER.MAX_PARTITIONED_PARALLELISM
.
Para conferir um exemplo completo, consulte PostgreSQL RunPartitionedQueryExample.
PARTIÇÃO <SQL>
PARTITION <sql>
Cria uma lista de partições para executar uma consulta no Spanner e
retorna uma lista de tokens de partição. Cada token de partição pode ser executado
em uma conexão JDBC separada no mesmo host ou em outro usando o
comando RUN PARTITION 'partition-token'
.
▶ Exemplo: consulta de partição (clique para expandir)
O exemplo a seguir mostra como particionar uma consulta e executar cada
separadamente usando o driver JDBC do Spanner.
-- Partition a query. This returns a list of partition tokens that can be
-- executed either on this connection or on any other connection to the same
-- database.
PARTITION SELECT FirstName, LastName FROM Singers;
-- Run the partitions that were returned from the previous statement.
RUN PARTITION 'partition-token-1';
RUN PARTITION 'partition-token-2';
Para um exemplo completo, consulte PostgreSQL PartitionQueryExample.
RUN PARTITION 'partition-token'
RUN PARTITION 'partition-token'
Executa uma partição de consulta que já foi retornada por PARTITION
.
kubectl. O comando pode ser executado em qualquer conexão JDBC conectada
o mesmo banco de dados que criou os tokens de partição.
Para um exemplo completo, consulte PostgreSQL PartitionQueryExample.
SPANNER.MAX_PARTITIONED_PARALLELISM
Uma propriedade do tipo int8
indicando o número de linhas de execução de worker que
O driver JDBC do Spanner usa para executar partições. Esse valor é usado para:
SPANNER.AUTO_PARTITION_MODE = true
RUN PARTITIONED QUERY sql
SHOW [VARIABLE] SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM = <int8>
Define o número máximo de linhas de execução de worker que o driver JDBC do Spanner
que pode ser usado para executar partições. Definir esse valor como 0
instrui o
O driver JDBC do Spanner para usar o número de núcleos de CPU no cliente
máquina, como o máximo.
O padrão é 0
.
Comandos do Savepoint
As instruções a seguir ativam e desativam emulados
pontos de salvamento
nas transações. É possível criar um ponto de salvamento chamando o
java.sql.Connection#setSavepoint()
.
O driver JDBC do Spanner emula pontos de salvamento para oferecer suporte a frameworks que dependem deles para transações aninhadas. Os Savepoints são emulados ao acompanhar de uma soma de verificação em execução para os resultados que foram retornados por instruções em a transação. Ao reverter para um ponto de salvamento, o O driver JDBC do Spanner reverte a transação e tenta novamente até o ponto em que o ponto de salvamento foi definido. A soma de verificação da tentativa é comparada à soma de verificação da transação inicial para verificar se os mesmos resultados foram retornados.
SPANNER.SAVEPOINT_SUPPORT
SHOW [VARIABLE] SPANNER.SAVEPOINT_SUPPORT
SET SPANNER.SAVEPOINT_SUPPORT {TO|=} { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }
Uma propriedade do tipo STRING
indicando o SAVEPOINT_SUPPORT
atual.
configuração do Terraform. Os valores possíveis são:
DISABLED
: todos os comandos do ponto de salvamento estão desativados e falharão.FAIL_AFTER_ROLLBACK
: os comandos de ponto de salvamento estão ativados. Revertendo para um o ponto de salvamento reverte toda a transação. A transação vai falhar se você tentar para usar a transação depois de reverter para um ponto de salvamento.ENABLED
: todos os comandos do ponto de salvamento estão ativados. Como reverter para um ponto de salvamento vai reverter a transação e uma nova tentativa será realizada no ponto de salvamento. Essa operação falha com um erroAbortedDueToConcurrentModificationException
se os dados usados pela transação até o ponto de salvamento tiverem mudado.
O valor padrão é FAIL_AFTER_ROLLBACK
.
Só é possível mudar o valor desta variável quando ela não está ativa transação.
▶ Exemplo: compatibilidade com Savepoint (clique para expandir)
O exemplo a seguir mostra como ativar e desativar o suporte a pontos de salvamento em
e o driver JDBC do Spanner.
try (Connection connection =
DriverManager.getConnection(
String.format(
"jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
"my-project", "my-instance", "my-database"))) {
// Savepoints can only be used when AutoCommit=false.
connection.setAutoCommit(false);
// Disables setting a savepoint.
connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='DISABLED'");
// The following statement fails because savepoints have been disabled.
connection.setSavepoint("my_savepoint1");
// Enables setting a savepoint and releasing a savepoint.
// Rolling back to a savepoint is disabled.
connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='FAIL_AFTER_ROLLBACK'");
Savepoint mySavepoint2 = connection.setSavepoint("my_savepoint2");
connection.createStatement().execute("insert into my_table (id, value) values (1, 'One')");
connection.releaseSavepoint(mySavepoint2);
connection.commit();
// Enables setting, releasing and rolling back to a savepoint.
connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='ENABLED'");
Savepoint mySavepoint3 = connection.setSavepoint("my_savepoint3");
connection.createStatement().execute("insert into my_table (id, value) values (2, 'Two')");
connection.rollback(mySavepoint3);
}
A seguir
Saiba como conectar o JDBC a um banco de dados de dialeto PostgreSQL.