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 declarações que descritas neste documento podem ser usadas com qualquer cliente ou driver que se conecta ao PGAdapter.

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

Para mais informações sobre o uso do PGAdapter, consulte Iniciar 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 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 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;

COMUNICADO AUTOMÁTICO

Um booleano que indica se a conexão está ou não 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 execute BEGIN e COMMIT para gerenciar transações automaticamente para você. 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á 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 }

Esse comando só pode ser executado depois que uma transação é iniciada (consulte BEGIN [TRANSACTION | WORK]) e antes instruções são executadas dentro da 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 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 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 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 indicando o horário. unidade. Um valor 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 segundo, o que significa que não há tempo limite. Um número da 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 instruções subsequentes na transação invalidada (exceto ROLLBACK) falham.

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 de inatividade exata.

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 desta propriedade quando não há transação.

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

▶ Exemplo: inatividade 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 em a 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 do otimizador com 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 estatísticas devem ser retornadas para transações nesta 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 commit (clique para expandir)

. O exemplo a seguir mostra como visualizar 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 dica de instrução para especificar a prioridade da 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 ISOLAÇÃO DE TRANSAÇÕES

SHOW [ VARIABLE ] TRANSACTION ISOLATION LEVEL

Retorna um conjunto de resultados com uma linha e uma coluna do tipo STRING. A o valor retornado sempre será serializable, que é o único aceito nível de isolamento para bancos de dados de 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 exibir o último carimbo de data/hora de commit de um 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 visualizar a última resposta de confirmação de um 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.

• 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 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 [TRANSAÇÃO | TRABALHO]

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 as bloqueia a transação retida.
• 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 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.

Você poderá executar 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.

Essa instrução define apenas o modo da 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.

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

▶ Exemplo: SET TRANSACTION (Clique para expandir)

. O exemplo a seguir mostra como definir características de transação com 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 as características da sessão com 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 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 Solução de 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 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 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. 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 tags de instrução para a mesma instrução.

Para mais informações, consulte Solução de 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 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 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 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, espera o Spanner executar essas instruções e encerra a DDL atual lote.

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.

Observação :se uma instrução DDL no lote retornar um erro, o Spanner poderá ainda aplicaram as instruções DDL anteriores no mesmo lote à no seu 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: cancelar lote DDL (clique para expandir)

. O exemplo a seguir mostra como cancelar um lote DDL com 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 a seguir mostra como executar um lote DML com 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 do Savepoint

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 com uma 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 funcionam quando há suporte para pontos de salvamento 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 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 do Savepoint estão ativados. Revertendo para um o ponto de salvamento reverte toda a transação. A operação falhará se você tentar use 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 reverte a transação e uma nova tentativa é realizada no ponto de salvamento. Isso falha com um erro AbortedDueToConcurrentModificationException se os dados subjacentes que foram usados pela transação até o ponto de salvamento mudou.

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 dentro da transação atual. Uma transação pode ser revertida para um ponto de salvamento para desfazer todas as operações que executado desde que o ponto de salvamento foi criado.

▶ Exemplo: Savepoint (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

Reverte 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 com uma 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 execute 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 armazenados na memória em PGAdapter.

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

. O exemplo a seguir mostra como criar e executar instruções preparadas com 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 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 da conexão.

Copiar

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

COPY table_name 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 que o limite padrão de mutação de transação.

▶ Exemplo: copiar (clique para expandir)

. Os exemplos a seguir mostram como copiar dados de e para Spanner com 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 de uma consulta para stdout.

Data Boost e instruções de consulta particionadas

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. 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 esta conexão deve usar Otimização de dados para consultas particionadas.

O padrão é false.

▶ Exemplo: executar uma consulta usando a otimização de dados (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 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.
• Também defina SPANNER.DATA_BOOST_ENABLED como true 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 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 Otimização de dados:

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

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 executados em uma conexão separada no mesmo ou em outro PGAdapter instância 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 separada usando 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.