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. 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 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
: segundosms
: milésimos de segundous
: microssegundosns
: 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 anow()
.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 anow()
.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
: segundosms
: milésimos de segundous
: microssegundosns
: nanossegundos
Só é possível modificar o valor desta propriedade quando não há transação.
▶ 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
. O
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 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 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
ouROLLBACK
para encerrar uma transação. - Se você ativou o modo
AUTOCOMMIT
, esta instrução temporariamente remove a conexão do modoAUTOCOMMIT
. A conexão retorna ao modoAUTOCOMMIT
quando a transação termina. - Se
READ ONLY
ouREAD WRITE
não for especificado, o modo de transação será é determinado pelo modo de transação padrão da sessão. O padrão é: definido usando o comandoSET 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
eROLLBACK
para uma transação somente leitura.
É possível executar essa instrução somente quando houver uma transação ativa.
▶ Exemplo: COMMIT TRANSACTION (clique para expandir)
.
O exemplo a seguir mostra como confirmar uma transação com
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 entreCOMMIT
eROLLBACK
para uma transação somente leitura em uma conexão.
É possível executar essa instrução somente quando houver uma transação ativa.
▶ Exemplo: ROLLBACK TRANSACTION (clique para expandir)
.
O exemplo a seguir mostra como reverter uma transação com
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 o modo apenas da transação atual. Quando
confirmar ou reverter a transação, a próxima transação usará o
para a conexão. Consulte SET SESSION CHARACTERISTICS
.
▶ 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.
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 erroAbortedDueToConcurrentModificationException
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: cópia (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áriosRUN 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
comotrue
se quiser que a conexão para usar o Data Boost para todos consultas.
O padrão é false
.
▶ Exemplo: executar (clique para expandir)
.
Este exemplo executa duas consultas com 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.