Comandos de gerenciamento de sessão do PGAdapter

O PGAdapter do Spanner dá suporte a instruções de gerenciamento de sessão, que permitem modificar o estado e o comportamento da conexão, executar transações e executar lotes de instruções com eficiência. Todas as instruções descritas neste documento podem ser usadas com qualquer cliente ou driver que se conecte ao PGAdapter.

Para mais informações, consulte a lista completa de drivers do PostgreSQL compatíveis e ORMs. O os comandos a seguir se aplicam aos bancos de dados de dialetos PostgreSQL.

Para mais informações sobre o uso do PGAdapter, consulte Iniciar o PGAdapter.

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á no modo somente leitura. O padrão é false.

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

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

▶ Exemplo: transação somente leitura (clique para expandir)

O exemplo a seguir mostra como usar essa propriedade para executar códigos 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 first_name, last_name
FROM singers
ORDER BY last_name;

SELECT first_name, last_name
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 will
-- start 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.

OBSERVAÇÃO: normalmente não é necessário modificar o valor dessa variável ao usando um driver PostgreSQL com PGAdapter. Esses motoristas para gerenciar transações automaticamente, executando BEGIN e COMMIT. quando necessário. Você pode desativar o autocommit ao usar ferramentas de linha de comando como psql para evitar o commit de modificações acidentais de dados automaticamente.

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

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

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

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 }

Esse comando só pode ser executado depois que uma transação é iniciada (consulte BEGIN [TRANSACTION | WORK]) e antes que qualquer instrução seja executada na transação.

Quando você ativa SPANNER.RETRY_ABORTS_INTERNALLY, a conexão mantém uma checksum 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.

Essa configuração é ativada por padrão. Recomendamos desativar essa configuração se o aplicativo já tenta novamente as transações canceladas.

SPANNER.AUTOCOMMIT_DML_MODE

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

SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }

Os valores possíveis são:

• No modo TRANSACTIONAL, o 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. Uma instruçã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 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 o PGAdapter.

-- Change autocommit DML mode to use Partitioned DML.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'PARTITIONED_NON_ATOMIC';

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

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

STATEMENT_TIMEOUT

Uma propriedade do tipo STRING que indica o valor atual do tempo limite 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. Um valor de DEFAULT 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 de tempo limite e invalidará o transação.

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

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

O DEFAULT é de 0 segundos, o que significa que não há tempo limite. Um número int8 sem unidades indica int8 ms. Por exemplo, os comandos a seguir definem o tempo limite da instrução para 2 segundos.

SET STATEMENT_TIMEOUT TO 2000;
SET STATEMENT_TIMEOUT TO '2s';

O tempo limite de uma instrução durante uma transação invalida a transação, todas as instruções subsequentes na transação invalidada falham (exceto ROLLBACK).

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 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, em relação 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]D [[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.

Observação :só é possível usar os valores MIN_READ_TIMESTAMP e MAX_STALENESS para consultas no modo AUTOCOMMIT.

▶ Exemplo: desatuação somente leitura (clique para expandir)

O exemplo a seguir mostra como executar consultas usando uma inatividade personalizada. com PGAdapter.

-- 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 will return results that are up to
-- 10 seconds stale.
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is however 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 first_name, last_name
FROM singers
ORDER BY last_name;

SELECT title, singer_id
FROM albums
ORDER BY title;

COMMIT;

-- Read staleness can also be an exact timestamp.
SET SPANNER.READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.OPTIMIZER_VERSION

Uma propriedade do tipo STRING indicando o versão do otimizador. A versão é um valor numérico ou de "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 na conexão. Definir a versão do otimizador como '' (a string vazia) indica usar 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 versão específica do otimizador com o PGAdapter.

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

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 a seguir em a 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 PGAdapter.

-- 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 first_name, last_name
FROM singers
ORDER BY last_name;

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.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] SPANNER.RETURN_COMMIT_STATS
SET SPANNER.RETURN_COMMIT_STATS {TO|=} { true | false }

O padrão é false.

▶ Exemplo: estatísticas de confirmação (clique para expandir)

O exemplo a seguir mostra como conferir as estatísticas de confirmação de uma transação com o PGAdapter.

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

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

O padrão é 'NULL'.

Também é possível usar uma sugestão de instrução para especificar a prioridade do RPC:

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

Para ver mais informações, consulte Priority.

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, porque esse é o único nível de isolamento com suporte para bancos de dados com dialeto PostgreSQL do Spanner.

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

-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows 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 first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows 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 first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows 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 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 será NULL.

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

O exemplo a seguir mostra como conferir o último carimbo de data/hora de confirmação de uma operação de gravação com o PGAdapter.

-- 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=int8) 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 estará disponível somente se SET RETURN_COMMIT_STATS for definido como true antes da confirmação da transação.

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

O exemplo a seguir mostra como conferir a última resposta de confirmação de uma operação de gravação com o PGAdapter.

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

{ INÍCIO | COMEÇAR } [ TRANSAÇÃO | TRABALHO ]

{ START | BEGIN } [ TRANSACTION | WORK ] [{ READ ONLY | READ WRITE }]

Inicia uma nova transação. As palavras-chave TRANSACTION e WORK são opcionais, equivalentes e não têm efeito.

• Use COMMIT ou ROLLBACK para encerrar uma transação.
• Se você ativou o modo AUTOCOMMIT, esta instrução temporariamente remove a conexão do modo AUTOCOMMIT. A conexão retorna ao modo AUTOCOMMIT quando a transação termina.
• Se READ ONLY ou READ WRITE não for especificado, o modo de transação será é determinado pelo modo de transação padrão da sessão. O padrão é: definido usando o comando SET SESSION CHARACTERISTICS AS TRANSACTION.

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

-- This starts a transaction using the current defaults of this connection.
-- The value of SPANNER.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 SPANNER.READONLY to TRUE to use read-only transactions by default.
SET SPANNER.READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

-- Use the 'READ WRITE' or 'READ ONLY' qualifier in the BEGIN statement to
-- override the current default of the connection.
SET SPANNER.READONLY=FALSE;
BEGIN READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

COMPROMETAR [TRANSAÇÃO | TRABALHO]

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.

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

▶ Exemplo: COMMIT TRANSACTION (clique para expandir)

O exemplo a seguir mostra como confirmar uma transação com PGAdapter.

-- 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 PGAdapter in order to mark the
-- end of the transaction.
BEGIN READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

ROLLBACK [TRANSACTION | WORK]

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

▶ Exemplo: ROLLBACK TRANSACTION (clique para expandir)

O exemplo a seguir mostra como reverter uma transação com o PGAdapter.

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

-- Read-only transactions also need to be either committed or rolled back in
-- PGAdapter 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 first_name, last_name
FROM singers
ORDER BY last_name;
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ê iniciou uma transação executando BEGIN [TRANSACTION | WORK] e ainda não executaram nenhuma instrução na transação.

Esta instrução define o modo de transação apenas para a transação atual. Quando a transação é confirmada ou revertida, a próxima transação usa o modo padrão da conexão. Consulte SET SESSION CHARACTERISTICS.

Observação: não é possível definir o modo de transação como READ WRITE se a conexão estiver no modo READ ONLY.

▶ Exemplo: SET TRANSACTION (Clique para expandir)

O exemplo a seguir mostra como definir as características da transação com o PGAdapter.

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

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

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

▶ Exemplo: SET SESSION PERSONISTICS (Clique para expandir)

O exemplo a seguir mostra como definir características de sessão com o PGAdapter.

-- Set the default transaction mode to read-only.
SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;

-- This will now start a read-only transaction.
BEGIN;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

-- You can override the default transaction mode with the SET TRANSACTION
-- statement.
SET SESSION CHARACTERISTICS AS TRANSACTION READ WRITE;
BEGIN;
SET TRANSACTION READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

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 que a próxima instrução seja executada. Só um tag pode ser definida por instrução. A tag não abrange várias instruções. precisa 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.

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 Solução de problemas com tags de solicitação e tags de transação.

▶ Exemplo: tags de instrução (clique para expandir)

O exemplo abaixo mostra como definir tags de instrução com PGAdapter.

-- Set the statement tag that should be included with the next statement.
SET SPANNER.STATEMENT_TAG = 'tag1';
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- 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 track_number, title
FROM tracks
WHERE album_id=1 AND singer_id=1
ORDER BY track_number;

SPANNER.TRANSACTION_TAG

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

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

Define a tag da transação para que a transação atual seja executada. Só um 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-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 Solução de problemas com tags de solicitação e tags de transação.

▶ Exemplo: tags de transação (clique para expandir)

O exemplo a seguir mostra como definir tags de transação com PGAdapter.

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 first_name, last_name
FROM singers
ORDER BY last_name;

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

▶ Exemplo: lote DDL (clique para expandir)

O exemplo a seguir mostra como executar um lote DDL com PGAdapter.

-- 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 (
  id bigint primary key,
  first_name varchar,
  last_name varchar
);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE albums (
  id bigint primary key,
  title varchar,
  singer_id bigint,
  constraint fk_albums_singers foreign key (singer_id) references singers (id)
);

-- 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 retornará um erro para a primeira instrução DDL que o Spanner não puder executar. Caso contrário, RUN BATCH retorna com sucesso.

Observação: se uma instrução DDL no lote retornar um erro, o Spanner ainda poderá ter aplicado as instruções DDL anteriores no mesmo lote ao banco de dados.

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 abortar um lote de DDL com o PGAdapter.

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

-- The following statements are buffered locally.
CREATE TABLE singers (
  id bigint primary key,
  first_name varchar,
  last_name varchar
);
CREATE TABLE albums (
  id bigint primary key,
  title varchar,
  singer_id bigint,
  constraint fk_albums_singers foreign key (singer_id) references singers (id)
);

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

START BATCH DML

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 DML (clique para expandir)

O exemplo abaixo mostra como executar um lote de DML com o PGAdapter.

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

Comandos de ponto de salvamento

Os pontos de salvamento no PGAdapter são emulados. Como reverter para um ponto de salvamento retorna toda a transação e tenta novamente até o ponto em que o ponto de salvamento foi definido. A operação vai falhar AbortedDueToConcurrentModificationException se os dados subjacentes que foi usado pela transação até o ponto de salvamento for alterado.

A criação e a liberação de pontos de salvamento sempre são bem-sucedidas quando o suporte a pontos de salvamento está ativado.

As instruções a seguir ativam e desativam pontos de salvamento emulados nas transações.

SPANNER.SAVEPOINT_SUPPORT

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

Uma propriedade do tipo STRING que indica a configuração atual de SAVEPOINT_SUPPORT. 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 operação falha se você tentar usar a transação após reverter para um ponto de salvamento.
• ENABLED: todos os comandos de ponto de salvamento estão ativados. A reversão para um ponto de salvamento reverterá a transação, e a 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 é ENABLED.

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

Nome do ponto de salvamento do SAVEPOINT

SAVEPOINT savepoint-name;

SAVEPOINT cria um novo ponto de salvamento na transação atual. Uma transação pode ser revertida para um ponto de salvamento para desfazer todas as operações que foram executadas desde a criação do ponto de salvamento.

▶ Exemplo: ponto de salvamento (clique para expandir)

O exemplo a seguir mostra como salvar pontos com PGAdapter.

-- Start a transaction and execute an insert statement.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);

-- Set a savepoint and then execute another insert statement.
SAVEPOINT one_row_inserted;
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);

-- Roll back to the savepoint. This will undo all statements that have been
-- executed after the savepoint.
ROLLBACK TO one_row_inserted;

-- This only commits the first insert statement.
COMMIT;

ROLLBACK para savepoint_name

ROLLBACK TO savepoint_name

Desfaz a transação atual para o ponto de salvamento com o nome especificado.

Não há garantia de que a reversão para um ponto de salvamento será bem-sucedida em todos os casos. Reverter para um ponto de salvamento reverte toda a transação e tenta novamente ao ponto em que o ponto de salvamento foi definido. A operação vai falhar AbortedDueToConcurrentModificationException se os dados subjacentes que foram usado pela transação até o ponto de salvamento for alterado.

SOLICITAR [SAVEPOINT] nome do ponto de salvamento

RELEASE savepoint_name

Remove o ponto de salvamento da transação atual. Ele não pode mais ser usado para executar uma instrução ROLLBACK TO savepoint_name.

Declarações preparadas

As instruções a seguir criam e executam instruções preparadas.

PREPARAR

PREPARE statement_name [(data_type, ...)] AS statement

Prepara uma instrução nessa conexão. A instrução é analisada e validada pelo Spanner e armazenada na memória no PGAdapter.

▶ Exemplo: declarações preparadas (clique para expandir)

O exemplo a seguir mostra como criar e executar instruções preparadas com o PGAdapter.

-- Create a prepared statement that can be used to insert a single row.
PREPARE insert_t AS INSERT INTO T (id, col_a, col_b) VALUES ($1, $2, $3);

-- The prepared statement can be used to insert rows both in autocommit, in a
-- transaction, and in DML batches.

-- Execute in autocommit.
EXECUTE insert_t (1, 100, 1);

-- Execute in transaction.
BEGIN;
EXECUTE insert_t (2, 200, 2);
EXECUTE insert_t (3, 300, 3);
COMMIT;

-- Execute in a DML batch.
START BATCH DML;
EXECUTE insert_t (4, 400, 4);
EXECUTE insert_t (5, 500, 5);
RUN BATCH;

-- Prepared statements can be removed with the DEALLOCATE command.
DEALLOCATE insert_t;

EXECUTE

EXECUTE statement_name [(value, ...)]

Executa uma instrução que foi criada nessa conexão com PREPARE.

▶ Exemplo: executar (clique para expandir)

O exemplo a seguir mostra como preparar e executar instruções com o PGAdapter.

-- Create a prepared statement.
PREPARE my_statement AS insert into my_table (id, value) values ($1, $2);

-- Execute the statement twice with different parameter values.
EXECUTE my_statement (1, 'One');
EXECUTE my_statement (2, 'Two');

DESALOCAR

DEALLOCATE statement_name

Remove uma instrução preparada desta conexão.

Copiar

O PGAdapter é compatível com um subconjunto do comando COPY do PostgreSQL.

COPY nome_da_tabela FROM STDIN

COPY table_name FROM STDIN [BINARY]

Copia dados de stdin para o Spanner. É mais eficiente usar COPY para importar um grande conjunto de dados para o Spanner em vez de executar instruções INSERT.

COPY pode ser combinado com SPANNER.AUTOCOMMIT_DML_MODE para executar uma transação não atômica. Isso permite que a transação execute mais mutações do que o limite padrão de mutação de transações.

▶ Exemplo: cópia (clique para expandir)

Os exemplos a seguir mostram como copiar dados para e do Spanner com o PGAdapter.

create table numbers (number bigint not null primary key, name varchar);

Execute uma operação COPY atômica:

cat numbers.txt | psql -h /tmp -d test-db -c "copy numbers from stdin;"

Execute uma operação COPY não atômica:

cat numbers.txt | psql -h /tmp -d test-db \
  -c "set spanner.autocommit_dml_mode='partitioned_non_atomic'; copy numbers from stdin;"

Copie dados do PostgreSQL para o Spanner:

psql -h localhost -p 5432 -d my-local-db \
  -c "copy (select i, to_char(i, 'fm000') from generate_series(1, 1000000) s(i)) to stdout binary" \
  | psql -h localhost -p 5433 -d my-spanner-db \
  -c "set spanner.autocommit_dml_mode='partitioned_non_atomic'; copy numbers from stdin binary;"

Neste exemplo, presumimos que o PostgreSQL é executado na porta 5432 e O PGAdapter é executado na porta 5433.

Para mais exemplos, consulte PGAdapter: suporte a TEXTO.

COPIAR table_name PARA STDOUT [BINARY]

COPY table_name TO STDOUT [BINARY]

Copia os dados de uma tabela ou consulta para stdout.

Data Boost e instruções de consulta particionadas

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. Aumento de dados só é compatível com consultas particionadas.

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

O PGAdapter oferece suporte a três alternativas para a execução de consultas particionadas:

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

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

SPANNER.DATA_BOOST_ENABLED

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

Define se essa conexão precisa usar o Data Boost 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 PGAdapter.

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

SPANNER.AUTO_PARTITION_MODE

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

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

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

O padrão é false.

▶ Exemplo: Executar (clique para expandir)

Este exemplo executa duas consultas com PGAdapter usando Otimização de dados

SET SPANNER.AUTO_PARTITION_MODE = true
SET SPANNER.DATA_BOOST_ENABLED = true
SELECT first_name, last_name FROM singers
SELECT singer_id, title FROM albums

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 o Data Boost:

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

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

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 separada na mesma ou em outra instância do PGAdapter 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 partição separadamente usando o PGAdapter.

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

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 conectada o mesmo banco de dados que criou os tokens de partição.

SPANNER.MAX_PARTITIONED_PARALLELISM

Uma propriedade do tipo bigint indicando o número de linhas de execução de worker. O PGAdapter usa para executar partições. Esse valor é usado para:

• SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM {TO|=} <bigint>

Define o número máximo de linhas de execução de worker que o PGAdapter pode usar para executar partições. Definir esse valor como 0 instrui o PGAdapter a usar o número de núcleos de CPU na máquina cliente como o máximo.

O padrão é 0.

A seguir

• Saiba como iniciar o PGAdapter.
• Confira a lista completa de drivers e ORMs do PostgreSQL compatíveis.