Nesta página, descrevemos como criar, modificar e visualizar os fluxos de alterações do Spanner. Para saber mais sobre os fluxo de alterações, consulte Sobre os fluxos de alterações.
Como os fluxo de alterações são objetos de esquema, você os cria e os gerencia por meio das mesmas atualizações de esquema orientadas por DDL usadas para qualquer outro tipo de trabalho de definição de banco de dados, como criação de tabelas ou adição de índices.
O Spanner inicia uma operação de longa duração depois que você envia uma instrução DDL que altera o esquema, incluindo aquelas usadas para criar, alterar ou excluir fluxo de alterações. Um fluxo de alterações novo ou alterado começará a observar as colunas ou tabelas especificadas pela nova configuração após a conclusão dessa operação de longa duração.
Criar um stream de alterações
Para criar um fluxo de alterações, você precisa fornecer o nome e os objetos de esquema que ele observará: todo o banco de dados ou uma lista de tabelas e colunas específicas. Também é possível especificar o seguinte:
- período de armazenamento para substituir o período de armazenamento padrão de um dia.
- tipo de captura de valor para substituir o tipo de captura de valor padrão
OLD_AND_NEW_VALUES
. - Filtro de exclusões baseadas em TTL, se você quiser filtrar exclusões baseadas em TTL dos seus fluxo de alterações
excluir modificações da tabela para excluir todas as modificações da tabela
INSERT
,UPDATE
ouDELETE
GoogleSQL
A sintaxe DDL para criar um fluxo de alterações usando o GoogleSQL é semelhante a esta:
CREATE CHANGE STREAM change_stream_name [FOR column_or_table_watching_definition[, ... ] ] [ OPTIONS ( retention_period = timespan, value_capture_type = type, exclude_ttl_deletes = boolean, exclude_insert = boolean, exclude_update = boolean, exclude_delete = boolean ) ]
PostgreSQL
A sintaxe DDL para criar um fluxo de alterações usando o PostgreSQL é semelhante a esta:
CREATE CHANGE STREAM change_stream_name [FOR column_or_table_watching_definition[, ... ] ] [ WITH ( retention_period = timespan, value_capture_type = type, exclude_ttl_deletes = boolean, exclude_insert = boolean, exclude_update = boolean, exclude_delete = boolean ) ]
Um novo fluxo de alterações começa a observar os objetos de esquema atribuídos assim que a operação de longa duração que o criou é concluída.
Os exemplos a seguir ilustram a criação de fluxo de alterações com várias configurações.
Monitorar um banco de dados inteiro
Para criar um fluxo de alterações que monitore cada alteração de dados realizada nas tabelas de um banco de dados, use a palavra-chave ALL
:
CREATE CHANGE STREAM EverythingStream
FOR ALL;
A configuração ALL
inclui implicitamente todas as tabelas e colunas de dados futuros do banco de dados, assim que elas são criadas. Ele não inclui visualizações, tabelas de esquemas de informações ou outros objetos além das tabelas de dados normais.
Observar tabelas específicas
Para limitar o escopo de um fluxo de alterações a tabelas específicas, em vez de um banco de dados inteiro, especifique uma lista de uma ou mais tabelas:
CREATE CHANGE STREAM SingerAlbumStream
FOR Singers, Albums;
O Spanner atualiza automaticamente os streams de alterações que observam tabelas inteiras para refletir as alterações de esquema que as afetam, como colunas adicionadas ou descartadas.
Monitorar colunas específicas
Use a sintaxe table(column_1[, column_2,
...])
para observar as alterações em uma ou mais colunas específicas e não chave nas tabelas que você nomear:
CREATE CHANGE STREAM NamesAndTitles
FOR Singers(FirstName, LastName), Albums(Title);
Não é possível especificar colunas de chave primária aqui, porque cada fluxo de alterações sempre rastreia as chaves primárias de todas as tabelas monitoradas. Isso permite que cada registro de mudança de dados identifique a linha alterada pela chave primária.
Observar tabelas e colunas em um único stream
É possível combinar as sintaxes de observação de tabelas e colunas dos dois exemplos anteriores em um único fluxo de alterações:
CREATE CHANGE STREAM NamesAndAlbums
FOR Singers(FirstName, LastName), Albums;
Especificar um período de armazenamento mais longo
Para especificar um período de armazenamento de dados de fluxo de mudanças
maior que o padrão de um dia, defina retention_period
como um período
de até uma semana, expresso como horas (h
) ou dias (d
).
Dois exemplos:
GoogleSQL
CREATE CHANGE STREAM LongerDataRetention
FOR ALL
OPTIONS ( retention_period = '36h' );
CREATE CHANGE STREAM MaximumDataRetention
FOR ALL
OPTIONS ( retention_period = '7d' );
PostgreSQL
CREATE CHANGE STREAM LongerDataRetention
FOR ALL
WITH ( retention_period = '36h' );
CREATE CHANGE STREAM MaximumDataRetention
FOR ALL
WITH ( retention_period = '7d' );
Especificar um tipo de captura de valor diferente
Para especificar um tipo de captura de valor do fluxo de mudanças
diferente de OLD_AND_NEW_VALUES
, defina value_capture_type
como
NEW_VALUES
ou NEW_ROW
, conforme mostrado nos exemplos abaixo:
GoogleSQL
CREATE CHANGE STREAM NewRowChangeStream
FOR ALL
OPTIONS ( value_capture_type = 'NEW_ROW' );
CREATE CHANGE STREAM NewValuesChangeStream
FOR ALL
OPTIONS ( value_capture_type = 'NEW_VALUES' );
PostgreSQL
CREATE CHANGE STREAM NewRowChangeStream
FOR ALL
WITH ( value_capture_type = 'NEW_ROW' );
CREATE CHANGE STREAM NewValuesChangeStream
FOR ALL
WITH ( value_capture_type = 'NEW_VALUES' );
Filtrar exclusões baseadas em TTL
É possível filtrar exclusões baseadas em TTL
do escopo do fluxo de alterações usando o filtro exclude_ttl_deletes
.
Para mais informações sobre como esse filtro funciona, consulte Filtro de exclusões baseadas em time to live.
GoogleSQL
Para criar um fluxo de alterações com o filtro de exclusões baseadas em TTL, use o seguinte:
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
OPTIONS (exclude_ttl_deletes = true)
Substitua:
- CHANGE_STREAM_NAME: o nome do novo fluxo de alterações.
O exemplo a seguir cria um fluxo de alterações chamado NewFilterChangeStream
que exclui todas as exclusões baseadas em TTL:
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
OPTIONS (exclude_ttl_deletes = true)
PostgreSQL
Para criar um fluxo de alterações com o filtro de exclusões baseadas em TTL, use o seguinte:
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
WITH (exclude_ttl_deletes = true)
Substitua:
- STREAM_NAME: o nome do novo fluxo de alterações.
O exemplo a seguir cria um fluxo de alterações chamado NewFilterChangeStream
que exclui todas as exclusões baseadas em TTL:
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
WITH (exclude_ttl_deletes = true)
Para adicionar ou remover o filtro de exclusões baseadas em TTL de um fluxo de alterações existente, consulte Modificar filtro de exclusões baseadas em TTL. É possível confirmar os filtros de fluxo de alterações visualizando as definições do fluxo de alterações como DDL.
Filtrar por tipo de modificação da tabela
Filtre uma ou mais dessas modificações de tabela do escopo do fluxo de alterações usando as seguintes opções de filtro disponíveis:
exclude_insert
: exclui todas asINSERT
modificações da tabelaexclude_update
: exclui todas asUPDATE
modificações da tabelaexclude_delete
: exclui todas asDELETE
modificações da tabela
Para mais informações sobre como esses filtros funcionam, consulte Filtros de tipo de modificação de tabela.
GoogleSQL
Para criar um fluxo de alterações com um ou mais filtros de tipo de modificação de tabela, use o seguinte:
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
OPTIONS (MOD_TYPE_FILTER_NAME = true)
Substitua:
- CHANGE_STREAM_NAME: o nome do novo fluxo de alterações.
- MOD_TYPE_FILTER_NAME: o filtro que você
quer adicionar:
exclude_insert
,exclude_update
ouexclude_delete
. Ao adicionar mais de um filtro por vez, separe cada um com uma vírgula.
O exemplo a seguir cria um fluxo de alterações chamado NewFilterChangeStream
que exclui os tipos de modificação de tabela INSERT
e UPDATE
:
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
OPTIONS (exclude_insert = true, exclude_update = true)
PostgreSQL
Para criar um fluxo de alterações com um ou mais filtros de tipo de modificação de tabela, use o seguinte:
CREATE CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
WITH (MOD_TYPE_FILTER_NAME = true)
Substitua:
- CHANGE_STREAM_NAME: o nome do fluxo de alterações existente.
- MOD_TYPE_FILTER_NAME: o filtro que você
quer adicionar:
exclude_insert
,exclude_update
ouexclude_delete
. Ao adicionar mais de um filtro por vez, separe cada um com uma vírgula.
O exemplo a seguir cria um fluxo de alterações chamado NewFilterChangeStream
que exclui os tipos de transação de modificação de tabela INSERT
e UPDATE
:
CREATE CHANGE STREAM NewFilterChangeStream FOR ALL
WITH (exclude_insert = true, exclude_update = true)
Para adicionar ou remover um filtro de tipo de modificação de tabela de um fluxo de alterações atual, consulte Modificar filtro por tipo de modificação de tabela. Para confirmar quais filtros de tipo de modificação de tabela existem para seu fluxo de alterações, visualize as definições do fluxo de alterações como DDL.
Modificar um fluxo de alterações
Para modificar a configuração de um fluxo de alterações, use uma instrução DDL ALTER CHANGE STREAM
. Ela usa uma sintaxe semelhante a CREATE CHANGE STREAM
. É possível
alterar quais colunas um stream assiste ou a duração do período de armazenamento de dados. Também é possível suspender o monitoramento completamente enquanto
mantém os registros de alteração de dados.
Modificar o que um fluxo de alterações assiste
Este exemplo adiciona toda a tabela Songs
ao fluxo de alterações
NamesAndAlbums
configurado anteriormente:
ALTER CHANGE STREAM NamesAndAlbums
SET FOR Singers(FirstName, LastName), Albums, Songs;
O Spanner substitui o comportamento do fluxo de alterações nomeado pela nova configuração após a conclusão da operação de longa duração que atualiza a definição do fluxo de alterações no esquema do banco de dados.
Modificar o período de armazenamento de dados de um fluxo de alterações
Para modificar o período em que um fluxo de alterações retém os registros internos, defina o retention_period
em uma instrução DDL ALTER CHANGE STREAM
.
Este exemplo ajusta o período de armazenamento de dados para o fluxo de alterações NamesAndAlbums
criado anteriormente:
GoogleSQL
ALTER CHANGE STREAM NamesAndAlbums
SET OPTIONS ( retention_period = '36h' );
PostgreSQL
ALTER CHANGE STREAM NamesAndAlbums
SET ( retention_period = '36h' );
Modificar o tipo de captura de valor de um fluxo de alterações
Para modificar o tipo de captura de valor de um fluxo de alterações, defina a cláusula value_capture_type
em uma instrução DDL ALTER CHANGE STREAM
.
Neste exemplo, ajustamos o tipo de captura de valor para NEW_VALUES
.
GoogleSQL
ALTER CHANGE STREAM NamesAndAlbums
SET OPTIONS ( value_capture_type = 'NEW_VALUES' );
PostgreSQL
ALTER CHANGE STREAM NamesAndAlbums
SET ( value_capture_type = 'NEW_VALUES' );
Modificar filtro de exclusões baseadas em TTL
Para modificar o filtro de exclusões baseadas em TTL de um fluxo
de alterações, defina o filtro exclude_ttl_deletes
em uma instrução DDL
ALTER CHANGE STREAM
. É possível usar isso para adicionar ou remover o filtro de
seus fluxo de alterações atuais.
Para mais informações sobre como esses filtros funcionam, consulte Filtro de exclusões baseadas em time to live.
Adicionar o filtro de exclusões com base em TTL a um fluxo de alterações existente
GoogleSQL
Para adicionar o filtro de exclusões baseadas em TTL a um fluxo de alterações existente,
use o seguinte para definir o filtro como true
:
ALTER CHANGE STREAM CHANGE_STREAM_NAME FOR ALL
SET OPTIONS (exclude_ttl_deletes = true)
Substitua:
- CHANGE_STREAM_NAME: o nome do fluxo de alterações existente.
No exemplo a seguir, o filtro exclude_ttl_deletes
é adicionado a um
fluxo de alterações existente chamado NewFilterChangeStream
:
que exclui todas as exclusões baseadas em TTL:
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET OPTIONS (exclude_ttl_deletes = true)
Isso exclui todas as exclusões baseadas em TTL do fluxo de alterações.
PostgreSQL
Para adicionar o filtro de exclusões baseadas em TTL a um fluxo de alterações existente,
use o seguinte para definir o filtro como True
:
ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET (exclude_ttl_deletes = true)
Substitua:
- STREAM_NAME: o nome do fluxo de alterações existente.
No exemplo a seguir, o filtro exclude_ttl_deletes
é adicionado a um
fluxo de alterações existente chamado NewFilterChangeStream
:
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET (exclude_ttl_deletes = true)
Isso exclui todas as exclusões futuras baseadas em TTL do fluxo de alterações.
Remover o filtro de exclusões baseadas em TTL de um fluxo de alterações existente
GoogleSQL
Para remover o filtro de exclusões com base em TTL de um fluxo de alterações existente,
use o seguinte para definir o filtro como False
:
ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET OPTIONS (exclude_ttl_deletes = false)
Substitua:
- STREAM_NAME: o nome do novo fluxo de alterações.
No exemplo a seguir, o filtro exclude_ttl_deletes
é removido de um
fluxo de alterações existente chamado NewFilterChangeStream
:
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET OPTIONS (exclude_ttl_deletes = false)
Isso inclui todas as exclusões futuras baseadas em TTL no fluxo de alterações.
Também é possível definir o filtro como null
para remover o filtro de exclusões com base em TTL.
PostgreSQL
Para remover o filtro de exclusões com base em TTL de um fluxo de alterações existente,
use o seguinte para definir o filtro como False
:
ALTER CHANGE STREAM STREAM_NAME FOR ALL
SET (exclude_ttl_deletes = false)
Substitua:
- STREAM_NAME: o nome do novo fluxo de alterações.
No exemplo a seguir, o filtro exclude_ttl_deletes
é removido de um
fluxo de alterações existente chamado NewFilterChangeStream
:
ALTER CHANGE STREAM NewFilterChangeStream FOR ALL
SET (exclude_ttl_deletes = false)
Isso inclui todas as exclusões futuras baseadas em TTL no fluxo de alterações.
Também é possível definir o filtro como null
para remover o filtro de exclusões com base em TTL.
Modificar filtro por tipo de modificação de tabela
Para modificar os filtros de tipo de modificação de tabela de um fluxo de alterações, defina o tipo de filtro em uma instrução DDL ALTER CHANGE STREAM
. É possível usar isso para adicionar um novo filtro ou remover um filtro existente do seu fluxo de alterações.
Adicionar um filtro de tipo de modificação de tabela a um fluxo de alterações
GoogleSQL
Se quiser adicionar um ou mais filtros novos de tipo de modificação de tabela a um fluxo de alterações, use o seguinte para definir o filtro como true
:
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET OPTIONS (MOD_TYPE_FILTER_NAME = true)
Substitua:
- CHANGE_STREAM_NAME: substitua pelo nome do fluxo de alterações existente.
- MOD_TYPE_FILTER_NAME: substitua pelo filtro que você
quer adicionar:
exclude_insert
,exclude_update
ouexclude_delete
. Ao adicionar mais de um filtro por vez, separe cada um com uma vírgula.
No exemplo a seguir, o filtro exclude_delete
é adicionado a um fluxo de alterações
chamado NewFilterChangeStream
:
ALTER CHANGE STREAM NewFilterChangeStream
SET OPTIONS (exclude_delete = true)
PostgreSQL
Se quiser adicionar um ou mais filtros novos de tipo de modificação de tabela a um fluxo de alterações, use o seguinte para definir o filtro como true
:
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET (MOD_TYPE_FILTER_NAME = true)
Substitua:
- CHANGE_STREAM_NAME: substitua pelo nome do fluxo de alterações existente.
- MOD_TYPE_FILTER_NAME: substitua pelo filtro que você
quer adicionar:
exclude_insert
,exclude_update
ouexclude_delete
. Ao adicionar mais de um filtro por vez, separe cada um com uma vírgula.
No exemplo a seguir, o filtro exclude_delete
é adicionado a um fluxo de alterações
chamado NewFilterChangeStream
:
ALTER CHANGE STREAM NewFilterChangeStream
SET (exclude_delete = true)
Remover um filtro de tipo de modificação de tabela de um fluxo de alterações atual
GoogleSQL
Para remover um ou mais filtros de tipo de modificação de tabela no fluxo de alterações, use o seguinte para definir o filtro como false
:
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET OPTIONS (MOD_TYPE_FILTER_NAME = false)
Substitua:
- CHANGE_STREAM_NAME: substitua pelo nome do fluxo de alterações existente.
- MOD_TYPE_FILTER_NAME: substitua pelo filtro que você
quer remover:
exclude_insert
,exclude_update
ouexclude_delete
. Ao remover mais de um filtro por vez, separe cada um com uma vírgula.
No exemplo a seguir, o filtro exclude_delete
é removido de um fluxo de alterações
chamado NewFilterChangeStream
:
ALTER CHANGE STREAM NewFilterChangeStream
SET OPTIONS (exclude_delete = false)
Também é possível remover um filtro de modificação de tabela definindo o filtro de volta para o valor padrão. Para fazer isso, defina o valor do filtro como null
.
PostgreSQL
Para remover um ou mais filtros de tipo de modificação de tabela no fluxo de alterações, use o seguinte para definir o filtro como False
:
ALTER CHANGE STREAM CHANGE_STREAM_NAME
SET (MOD_TYPE_FILTER_NAME = false)
Substitua:
- CHANGE_STREAM_NAME: substitua pelo nome do fluxo de alterações existente.
- MOD_TYPE_FILTER_NAME: substitua pelo filtro que você
quer adicionar:
exclude_insert
,exclude_update
ouexclude_delete
. Ao adicionar mais de um filtro por vez, separe cada um com uma vírgula.
No exemplo a seguir, o filtro exclude_delete
é removido de um fluxo de alterações
chamado NewFilterChangeStream
:
ALTER CHANGE STREAM NewFilterChangeStream
SET (exclude_delete = false)
Também é possível remover um filtro de modificação de tabela definindo o filtro de volta para o valor padrão. Para fazer isso, defina o valor do filtro como null
.
Suspender um fluxo de alterações
Se você quiser que um fluxo de alterações interrompa a atividade, mas mantenha os registros internos (pelo menos durante o período de armazenamento de dados), altere-o para que ele não monitore nada.
Para fazer isso, emita uma instrução DDL ALTER CHANGE STREAM
que substitua a definição do fluxo de alterações pela frase especial DROP FOR ALL
.
Exemplo:
ALTER CHANGE STREAM MyStream DROP FOR ALL;
O fluxo continua a existir no banco de dados, mas não observa objetos e não gera mais registros de alteração de dados. Os registros de alterações atuais permanecem intactos, sujeitos à política de retenção de dados do stream.
Para retomar um stream suspenso, emita outra instrução ALTER CHANGE STREAM
com a configuração anterior.
Excluir um fluxo de alterações
Para excluir permanentemente um fluxo de alterações, emita uma instrução DROP CHANGE STREAM
que inclua o nome do fluxo:
DROP CHANGE STREAM NamesAndAlbums;
O Spanner interrompe imediatamente o stream, remove-o do esquema do banco de dados e exclui os registros de alteração de dados.
Listar e visualizar fluxo de alterações
O console do Google Cloud fornece uma interface da Web para listar e analisar as definições de fluxo de alterações de um banco de dados. Também é possível visualizar a estrutura dos fluxo de alterações como instruções DDL equivalentes ou consultando o esquema de informações do banco de dados.
Acessar fluxo de alterações com o console do Google Cloud
Para conferir uma lista dos fluxo de alterações de um banco de dados e revisar as definições deles:
Acesse a página "Instâncias do Spanner" no console do Google Cloud.
Navegue até a instância e o banco de dados apropriados.
Clique em Alterar streams no menu de navegação.
Isso exibe uma lista de todos os fluxo de alterações do banco de dados e resume a configuração de cada um. Clique no nome de um stream para revelar mais detalhes sobre as tabelas e colunas que ele monitora.
Visualizar definições de fluxo de alterações como DDL
A visualização do esquema de um banco de dados como DDL inclui descrições de todos os
fluxo de alterações, em que eles aparecem como instruções CREATE CHANGE STREAM
.
Para fazer isso no console, clique no link Mostrar DDL equivalente na página do banco de dados no console do Google Cloud.
Para fazer isso na linha de comando, use o comando
ddl describe
da Google Cloud CLI.
Consultar o esquema de informações sobre fluxo de alterações
É possível consultar diretamente o esquema de informações de um banco de dados sobre os fluxo de alterações. As tabelas a seguir contêm os metadados que definem nomes dos fluxo de alterações, as tabelas e colunas que eles observam e os períodos de retenção:
Práticas recomendadas para fluxos de alterações
Veja a seguir algumas práticas recomendadas para configurar e gerenciar fluxos de alterações.
Considere um banco de dados de metadados separado
Os fluxos de alterações usam um banco de dados de metadados para manter o estado interno. O banco de dados de metadados pode ser igual ou diferente do banco de dados que contém os fluxo de alterações. Recomendamos a criação de um banco de dados separado para armazenamento de metadados.
O conector de fluxo de alterações do Spanner precisa de permissões de leitura e gravação no banco de dados de metadados. Você não precisa preparar esse banco de dados com um esquema, o conector cuida disso.
O uso de um banco de dados de metadados separado elimina as complexidades que podem surgir ao permitir que o conector grave diretamente no banco de dados do aplicativo:
Ao separar o banco de dados de metadados do banco de dados de produção com o fluxo de alterações, o conector precisa apenas de permissões de leitura para o banco de dados de produção.
Ao restringir o tráfego do conector a um banco de dados de metadados separado, as gravações realizadas pelo próprio conector não são incluídas nos fluxo de alterações de produção. Isso é especialmente relevante para fluxo de alterações que observam todo o banco de dados.
Se nenhum banco de dados separado estiver sendo usado para armazenar os metadados, recomendamos monitorar o impacto da CPU do conector de fluxo de alterações nas instâncias.
Comparar novos fluxo de alterações e redimensionar, se necessário
Antes de adicionar novos fluxo de alterações à instância de produção, compare uma carga de trabalho realista em uma instância de preparo com os fluxos de alterações ativados. Isso permite que você determine se precisa adicionar nós à instância para aumentar as capacidades de computação e armazenamento.
Execute esses testes até que as métricas de CPU e armazenamento estejam estabilizadas. O ideal é que a utilização da CPU da instância permaneça abaixo do máximo recomendado e o uso de armazenamento não ultrapasse o limite da instância.
Use regiões diferentes para balancear a carga
Ao usar fluxo de alterações em uma configuração de instância multirregional, considere executar os pipelines de processamento em uma região diferente da região líder padrão. Isso ajuda a distribuir a carga de streaming entre as réplicas não líderes. No entanto, se você precisar priorizar o menor atraso de streaming possível sobre o balanceamento de carga, execute a carga de streaming na região líder.
A seguir
Use modelos para conectar rapidamente um fluxo de alterações ao BigQuery, Cloud Storage ou Pub/Sub.