Comandos de gestão de sessões do PGAdapter

O Spanner PGAdapter suporta declarações de gestão de sessões, que lhe permitem modificar o estado e o comportamento da sua ligação, executar transações e executar eficientemente lotes de declarações. Todas as declarações descritas neste documento podem ser usadas com qualquer cliente ou controlador que se ligue ao PGAdapter.

Para mais informações, consulte uma lista completa de controladores PostgreSQL e ORMs suportados. Os comandos seguintes aplicam-se a bases de dados com dialeto PostgreSQL.

Para mais informações sobre a utilização do PGAdapter, consulte o artigo Inicie o PGAdapter.

Declarações de ligação

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

SPANNER.READONLY

Um valor booleano que indica se a ligação está ou não no modo só de leitura. O valor predefinido é false.

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

Só pode alterar o valor desta propriedade enquanto não existir uma transação ativa.

▶ Exemplo: transação só de leitura (clique para expandir)
 O exemplo seguinte mostra como usar esta propriedade para executar transações de leitura apenas no Spanner.

SET 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 valor booleano que indica se a ligação está ou não no modo de confirmação automática. O valor predefinido é true.

NOTE: normalmente, não precisa de modificar o valor desta variável quando usa um controlador PostgreSQL com o PGAdapter. Estes controladores gerem automaticamente as transações por si executando BEGIN e COMMIT quando necessário. Pode desativar a opção autocommit quando usar ferramentas de linha de comandos, como o psql, para evitar que as modificações acidentais de dados sejam confirmadas automaticamente.

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

Só pode alterar o valor desta propriedade quando não existir nenhuma transação ativa.

Quando AUTOCOMMIT está definido como falso, é iniciada automaticamente uma nova transação depois de executar COMMIT ou ROLLBACK. A primeira declaração que executar inicia a transação.

▶ Exemplo: confirmação automática (clique para expandir)
 O exemplo seguinte mostra como usar a propriedade autocommit.

-- The default value for AUTOCOMMIT is true.
SHOW 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 valor booleano que indica se a ligação tenta novamente as transações anuladas automaticamente. A predefinição é true.

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

Só pode executar este comando depois de iniciar uma transação (consulte BEGIN [TRANSACTION | WORK]) e antes de executar quaisquer declarações na transação.

Quando ativa a SPANNER.RETRY_ABORTS_INTERNALLY, a ligação mantém uma soma de verificação de todos os dados que a ligação devolve à aplicação cliente. Isto é usado para tentar novamente a transação se for anulada pelo Spanner.

Esta definição está ativada por predefinição. Recomendamos que desative esta definição se a sua aplicação já repetir as transações anuladas.

SPANNER.AUTOCOMMIT_DML_MODE

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

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

Os valores possíveis são:

  • No modo TRANSACTIONAL, o controlador executa declarações DML como transações atómicas separadas. O controlador cria uma nova transação, executa a declaração DML e confirma a transação após a execução bem-sucedida ou reverte a transação em caso de erro.
  • No modo PARTITIONED_NON_ATOMIC, o controlador executa declarações DML como declarações de atualização particionadas. Uma declaração de atualização particionada pode ser executada como uma série de muitas transações, cada uma abrangendo um subconjunto das linhas afetadas. A declaração particionada oferece uma semântica mais fraca em troca de uma melhor escalabilidade e desempenho.

A predefinição é TRANSACTIONAL.

▶ Exemplo: DML particionada (clique para expandir)
 O exemplo seguinte mostra como executar DML particionada através do 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 de tempo limite atual para declarações.

SHOW [VARIABLE] STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT {TO|=} { '<int8>{ s | ms | us | ns }' | <int8> | DEFAULT }

O valor int8 é um número inteiro seguido de um sufixo que indica a unidade de tempo. Um valor de DEFAULT indica que não existe um valor de tempo limite definido. Se tiver sido definido um valor de tempo limite da declaração, as declarações que demorarem mais do que o valor de tempo limite especificado causam um erro de tempo limite e invalidam a transação.

As unidades de tempo suportadas são:

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

O valor de DEFAULT é 0 segundos, o que significa que não existe limite de tempo. Um número int8 sem unidades indica int8 ms. Por exemplo, os seguintes comandos definem o limite de tempo da declaração como 2 segundos.

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

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

READ_ONLY_STALENESS

Uma propriedade do tipo STRING que indica a definição de desatualização só de leitura atual que o Spanner usa para transações e consultas só de leitura no modo AUTOCOMMIT.

SHOW [VARIABLE] 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 obsolescência só de leitura aplica-se a todas as transações só de leitura subsequentes e a todas as consultas no modo AUTOCOMMIT.

A predefinição é STRONG.

As opções de limite de data/hora são as seguintes:

As indicações de tempo têm de usar o seguinte formato:

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

As unidades de tempo suportadas para definir valores MAX_STALENESS e EXACT_STALENESS são:

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

Só pode modificar o valor desta propriedade enquanto não existir uma transação ativa.

▶ Exemplo: desatualização só de leitura (clique para expandir)
 O exemplo seguinte mostra como executar consultas usando um valor de desatualização personalizado com o 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 que indica a versão do otimizador. A versão é numérica ou "LATEST".

SHOW [VARIABLE] SPANNER.OPTIMIZER_VERSION
SET SPANNER.OPTIMIZER_VERSION {TO|=} { 'version'|'LATEST'|'' }

Define a versão do otimizador a usar para todas as declarações seguintes na ligação. Definir a versão do otimizador como '' (a string vazia) indica que deve ser usada a versão mais recente. Se não estiver definida nenhuma versão do otimizador, o Spanner usa a versão do otimizador definida ao nível da base de dados.

A predefinição é ''.

▶ Exemplo: versão do otimizador (clique para expandir)
 O exemplo seguinte mostra como executar consultas usando uma versão do otimizador específica com o 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 que indica o pacote de estatísticas do otimizador atual usado por esta associação.

SHOW [VARIABLE] SPANNER.OPTIMIZER_STATISTICS_PACKAGE
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE {TO|=} { 'package'|'' }

Define o pacote de estatísticas do otimizador a usar para todas as declarações seguintes na ligação. <package> tem de ser um nome de pacote válido. Se não estiver definido nenhum pacote de estatísticas do otimizador, o Spanner usa o pacote de estatísticas do otimizador que está definido ao nível da base de dados.

A predefinição é ''.

▶ Exemplo: pacote de estatísticas do otimizador (clique para expandir)
 O exemplo seguinte mostra como executar consultas usando um pacote de estatísticas do otimizador específico com o 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 devem ser devolvidas estatísticas para transações nesta associação. Pode ver as estatísticas devolvidas executando o comando SHOW [VARIABLE] COMMIT_RESPONSE.

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

A predefinição é false.

▶ Exemplo: estatísticas de commits (clique para expandir)
 O exemplo seguinte mostra como ver as estatísticas de confirmação de uma transação com o 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 que indica a prioridade relativa dos pedidos do Spanner. A prioridade funciona como uma sugestão para o agendador do Spanner e não garante a ordem de execução.

SHOW [VARIABLE] SPANNER.RPC_PRIORITY
SET SPANNER.RPC_PRIORITY {TO|=} {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

'NULL' significa que não deve ser incluída nenhuma sugestão no pedido.

A predefinição é 'NULL'.

Também pode usar uma sugestão de declaração para especificar a prioridade do RPC:

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

Para mais informações, consulte Priority.

Extratos de transações

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

NÍVEL DE ISOLAMENTO DE TRANSAÇÕES

SHOW [ VARIABLE ] TRANSACTION ISOLATION LEVEL

Devolve um conjunto de resultados com uma linha e uma coluna do tipo STRING. O valor devolvido é sempre serializable, uma vez que este é o único nível de isolamento suportado para bases de dados com dialeto PostgreSQL do Spanner.

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

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

▶ Exemplo: ler data/hora (clique para expandir)
 O exemplo seguinte mostra como ver a data/hora da última leitura para uma operação só de leitura com o 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

Devolve um conjunto de resultados com uma linha e uma coluna do tipo TIMESTAMP que contém a data/hora de confirmação da última transação de leitura/escrita que o Spanner confirmou. Esta declaração devolve uma data/hora apenas quando a executa depois de confirmar uma transação de leitura/escrita e antes de executar quaisquer declarações SELECT, DML ou de alteração do esquema subsequentes. Caso contrário, o resultado é NULL.

▶ Exemplo: data/hora de confirmação (clique para expandir)
 O exemplo seguinte mostra como ver a data/hora da última confirmação de uma operação de escrita com o 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

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

  • COMMIT_TIMESTAMP (type=TIMESTAMP) Indica quando a transação mais recente foi confirmada.
  • MUTATION_COUNT (type=int8) Indica quantas mutações foram aplicadas na transação confirmada. Este valor está sempre vazio quando executado no emulador.

A contagem de mutações só está disponível se SET RETURN_COMMIT_STATS tiver sido definido como true antes da consolidação da transação.

▶ Exemplo: resposta de confirmação (clique para expandir)
 O exemplo seguinte mostra como ver a última resposta de confirmação para uma operação de escrita com o 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;

{ START | BEGIN } [ TRANSACTION | WORK ]

{ 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 qualquer efeito.

  • Use COMMIT ou ROLLBACK para terminar uma transação.
  • Se tiver ativado o modo AUTOCOMMIT, esta declaração retira temporariamente a ligação do modo AUTOCOMMIT. A ligação volta ao modo AUTOCOMMIT quando a transação termina.
  • Se READ ONLY ou READ WRITE não for especificado, o modo de transação é determinado pelo modo de transação predefinido da sessão. Esta predefinição é definida através do comando SET SESSION CHARACTERISTICS AS TRANSACTION.

Só pode executar esta declaração quando não existir nenhuma transação ativa.

▶ Exemplo: BEGIN TRANSACTION (clique para expandir)
 O exemplo seguinte mostra como iniciar diferentes tipos de transações com o 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;

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

  • A confirmação de uma transação de leitura/escrita torna todas as atualizações desta transação visíveis para outras transações e liberta todos os bloqueios da transação no Spanner.
  • A confirmação de uma transação só de leitura termina a transação só de leitura atual. Qualquer declaração subsequente inicia uma nova transação. Não existe diferença semântica entre COMMIT e ROLLBACK para uma transação de leitura.

Só pode executar esta declaração enquanto existir uma transação ativa.

▶ Exemplo: COMMIT TRANSACTION (Clique para expandir)
 O exemplo seguinte mostra como confirmar uma transação com o 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]

Faz um ROLLBACK da transação atual. As palavras-chave TRANSACTION e WORK são opcionais e equivalentes, e não têm qualquer efeito.

  • A execução de um ROLLBACK de uma transação de leitura/escrita limpa todas as mutações em buffer, reverte a transação no Spanner e liberta todos os bloqueios que a transação detinha.
  • A execução de um ROLLBACK de uma transação só de leitura termina a transação só de leitura atual. Todas as declarações subsequentes iniciam uma nova transação. Não existe diferença semântica entre COMMIT e ROLLBACK para uma transação só de leitura numa ligação.

Só pode executar esta declaração enquanto existir uma transação ativa.

▶ Exemplo: ROLLBACK TRANSACTION (clique para expandir)
 O exemplo seguinte mostra como reverter uma transação com 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 para a transação atual.

Só pode executar esta declaração quando AUTOCOMMIT for false ou se tiver iniciado uma transação executando BEGIN [TRANSACTION | WORK] e ainda não tiver executado nenhuma declaração na transação.

Esta declaração define o modo de transação apenas para a transação atual. Quando a transação é confirmada ou revertida, a transação seguinte usa o modo predefinido para a ligação. (Consulte SET SESSION CHARACTERISTICS.)

▶ Exemplo: SET TRANSACTION (Clique para expandir)
 O exemplo seguinte mostra como definir as caraterí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;

DEFINA AS CARATERÍSTICAS DA SESSÃO

SET SESSION CHARACTERISTICS AS TRANSACTION { READ ONLY | READ WRITE }

Define o modo de transação predefinido para transações na sessão como READ ONLY ou READ WRITE. Esta declaração só é permitida quando não existe nenhuma transação ativa.

O comando SET TRANSACTION pode substituir esta definição.

▶ Exemplo: SET SESSION CHARACTERISTICS (Clique para expandir)
 O exemplo seguinte mostra como definir as caraterísticas da 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 etiqueta de pedido para a declaração seguinte.

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

Define a etiqueta de pedido para a próxima declaração a ser executada. Só é possível definir uma etiqueta por declaração. A etiqueta não abrange várias declarações. Tem de ser definida por declaração. Pode remover uma etiqueta de pedido definindo-a como a string vazia ('').

A predefinição é ''.

Pode definir etiquetas de transação e etiquetas de extrato para o mesmo extrato.

Também pode usar uma sugestão de declaração para adicionar uma etiqueta de declaração:

/*@STATEMENT_TAG='my-tag'*/ SELECT * FROM albums

Para mais informações, consulte o artigo Resolução de problemas com etiquetas de pedidos e etiquetas de transações.

▶ Exemplo: etiquetas de declaração (clique para expandir)
 O exemplo seguinte mostra como definir etiquetas de declaração com o 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 etiqueta de transação para a próxima transação.

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

Define a etiqueta de transação para a transação atual a ser executada. Só é possível definir uma etiqueta por transação. A etiqueta não abrange várias transações. Tem de ser definida por transação. Pode remover uma etiqueta de transação definindo-a como a string vazia (''). A etiqueta de transação tem de ser definida antes de serem executadas quaisquer declarações na transação.

A predefinição é ''.

Pode definir etiquetas de transação e etiquetas de extrato para o mesmo extrato.

Para mais informações, consulte o artigo Resolução de problemas com etiquetas de pedidos e etiquetas de transações.

▶ Exemplo: etiquetas de transações (clique para expandir)
 O exemplo seguinte mostra como definir etiquetas de transação com o 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;

Extratos em lote

As seguintes declarações gerem lotes de declarações DDL e enviam esses lotes para o Spanner.

INICIE O LDD EM LOTE

START BATCH DDL

Inicia um lote de declarações DDL na ligação. Todas as declarações subsequentes durante o lote têm de ser declarações DDL. As declarações DDL são armazenadas em buffer localmente e enviadas para o Spanner como um lote quando executa RUN BATCH. A execução de várias declarações DDL como um lote é normalmente mais rápida do que a execução das declarações em separado.

Só pode executar esta declaração quando não existir nenhuma transação ativa.

▶ Exemplo: lote de DDL (clique para expandir)
 O exemplo seguinte mostra como executar um lote de DDL com o 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 declarações DDL em buffer no lote DDL atual para a base de dados, aguarda que o Spanner execute estas declarações e termina o lote DDL atual.

Se o Spanner não conseguir executar, pelo menos, uma declaração DDL, RUN BATCH devolve um erro para a primeira declaração DDL que o Spanner não consegue executar. Caso contrário, RUN BATCH é devolvido com êxito.

ABORT BATCH

Limpa todas as declarações DDL em buffer no lote DDL atual e termina o lote.

Só pode executar esta declaração quando um lote de LDD está ativo. Pode usar ABORT BATCH independentemente de o lote ter ou não instruções DDL em buffer. Todas as declarações DDL anteriores no lote são anuladas.

▶ Exemplo: anular lote de DDL (clique para expandir)
 O exemplo seguinte mostra como anular um lote de DDL com o 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 seguintes declarações agrupam as duas declarações DML e enviam-nas numa chamada para o servidor. Um lote de DML pode ser executado como parte de uma transação ou no modo de confirmação automática.

START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
RUN BATCH;

▶ Exemplo: lote de DML (clique para expandir)
 O exemplo seguinte mostra como executar um lote de DML com o 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 gravação

Os pontos de salvaguarda no PGAdapter são emulados. A reversão para um ponto de salvaguarda reverte toda a transação e tenta novamente até ao ponto em que o ponto de salvaguarda foi definido. Esta operação falha com um erro AbortedDueToConcurrentModificationException se os dados subjacentes que foram usados pela transação até ao ponto de salvaguarda tiverem sido alterados.

A criação e a publicação de pontos de reposição têm sempre êxito quando o suporte de pontos de reposição está ativado.

As seguintes declarações ativam e desativam os pontos de salvaguarda 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 SAVEPOINT_SUPPORT configuração atual. Os valores possíveis são os seguintes:

  • DISABLED: todos os comandos de ponto de salvaguarda estão desativados e vão falhar.
  • FAIL_AFTER_ROLLBACK: os comandos Savepoint estão ativados. A reversão para um ponto de reposição reverte toda a transação. A operação falha se tentar usar a transação depois de reverter para um ponto de reposição.
  • ENABLED: todos os comandos de ponto de salvaguarda estão ativados. A reversão para um ponto de salvaguarda reverte a transação e a repetição é realizada para o ponto de salvaguarda. Esta operação falha com um erro AbortedDueToConcurrentModificationException se os dados subjacentes que foram usados pela transação até ao ponto de salvaguarda tiverem sido alterados.

O valor predefinido é ENABLED.

Só pode executar esta declaração quando não existir nenhuma transação ativa.

SAVEPOINT savepoint_name

SAVEPOINT savepoint-name;

SAVEPOINT cria um novo ponto de reposição na transação atual. Uma transação pode ser revertida para um ponto de salvaguarda para anular todas as operações que foram executadas desde que o ponto de salvaguarda foi criado.

▶ Exemplo: Savepoint (clique para expandir)
 O exemplo seguinte mostra como usar savepoints 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 TO savepoint_name

ROLLBACK TO savepoint_name

Reverte a transação atual para o ponto de salvaguarda com o nome especificado.

A reversão para um ponto de salvaguarda não tem garantia de sucesso em todos os casos. A reversão para um ponto de salvaguarda reverte toda a transação e tenta novamente até ao ponto em que o ponto de salvaguarda foi definido. Esta operação falha com um AbortedDueToConcurrentModificationException se os dados subjacentes que foram usados pela transação até ao ponto de reposição tiverem sido alterados.

RELEASE [SAVEPOINT] nome_ponto_gravação

RELEASE savepoint_name

Remove o ponto de reposição da transação atual. Já não pode ser usado para executar uma declaração ROLLBACK TO savepoint_name.

Declarações preparadas

As seguintes declarações criam e executam declarações preparadas.

PREPARE

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

Prepara uma declaração sobre esta associação. A declaração é analisada e validada pelo Spanner e armazenada na memória no PGAdapter.

▶ Exemplo: declarações preparadas (clique para expandir)
 O exemplo seguinte mostra como criar e executar declaraçõ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 declaração que foi criada nesta ligação com PREPARE.

▶ Exemplo: Execute (clique para expandir)
 O exemplo seguinte mostra como preparar e executar declaraçõ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');

DEALLOCATE

DEALLOCATE statement_name

Remove uma declaração preparada desta ligação.

Copiar

O PGAdapter suporta um subconjunto do comando COPY do PostgreSQL.

COPY table_name FROM STDIN

COPY table_name FROM STDIN [BINARY]

Copia dados do stdin para o Spanner. É mais eficiente usar o comando COPY para importar um grande conjunto de dados para o Spanner do que executar declarações INSERT.

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

▶ Exemplo: copiar (clique para expandir)
 Os exemplos seguintes mostram como copiar dados para e a partir do Spanner com o PGAdapter.

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

Execute uma operação atómica COPY:

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

Este exemplo pressupõe que o PostgreSQL é executado na porta 5432 e o PGAdapter é executado na porta 5433.

Para mais exemplos, consulte o artigo PGAdapter - COPY support.

COPY table_name TO STDOUT [BINARY]

COPY table_name TO STDOUT [BINARY]

Copia os dados de uma tabela ou de uma consulta para o stdout.

Data Boost e declarações de consultas particionadas

O Data Boost permite-lhe executar consultas de estatísticas e exportações de dados com um impacto quase nulo nos fluxos de trabalho existentes na instância do Spanner aprovisionada. O aumento de dados só é suportado para consultas particionadas.

Pode ativar o aumento de dados com a declaração SET SPANNER.DATA_BOOST_ENABLED.

O PGAdapter suporta três alternativas para executar consultas particionadas:

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

Cada um destes métodos é descrito nas secções seguintes.

SPANNER.DATA_BOOST_ENABLED

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

Define se esta associação deve usar a Otimização de dados para consultas particionadas.

A predefinição é false.

▶ Exemplo: execute uma consulta com o aumento de dados (clique para expandir)
 O exemplo seguinte mostra como fazer uma consulta usando a Otimização de dados com o 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 ligação usa automaticamente consultas particionadas para todas as consultas que são executadas.

  • Defina esta variável como true se quiser que a ligação use consultas particionadas para todas as consultas executadas.
  • Defina também SPANNER.DATA_BOOST_ENABLED como true se quiser que a ligação use o Data Boost para todas as consultas.

A predefinição é false.

▶ Exemplo: Execute (clique para expandir)
 Este exemplo executa duas consultas com o PGAdapter usando o Data Boost

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

EXECUTE UMA CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

Executa uma consulta como uma consulta particionada no Spanner. Certifique-se de que 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 faz a partição interna da consulta e executa as partições em paralelo. Os resultados são unidos num conjunto de resultados e devolvidos à aplicação. O número de threads de trabalho que executam partições pode ser definido com a variável SPANNER.MAX_PARTITIONED_PARALLELISM.

PARTITION <SQL>

PARTITION <sql>

Cria uma lista de partições para executar uma consulta no Spanner e devolve uma lista de tokens de partição. Cada token de partição pode ser executado numa ligação separada na mesma ou noutra instância do PGAdapter através do comando RUN PARTITION 'partition-token'.

▶ Exemplo: consulta de partição (clique para expandir)
 O exemplo seguinte mostra como particionar uma consulta e, em seguida, executar cada partição separadamente através do 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 foi devolvida anteriormente pelo comando PARTITION. O comando pode ser executado em qualquer associação associada à mesma base de dados que a base de dados que criou os tokens de partição.

SPANNER.MAX_PARTITIONED_PARALLELISM

Uma propriedade do tipo bigint que indica o número de threads de trabalho que o PGAdapter usa para executar partições. Este 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 threads de trabalho que o PGAdapter pode usar para executar partições. Se definir este valor como 0, indica ao PGAdapter que deve usar o número de núcleos do CPU na máquina cliente como o máximo.

A predefinição é 0.

O que se segue?