FAQ do ClickPipes para MySQL

Perguntas frequentes sobre o ClickPipes para MySQL.

​

O ClickPipe do MySQL oferece suporte ao MariaDB?

Sim, o ClickPipe do MySQL é compatível com o MariaDB 10.0 e versões posteriores. A configuração é muito semelhante à do MySQL, usando replicação GTID por padrão.

​

Por que meu pipe falhou devido a um evento de linhas parciais sem suporte do MariaDB?

O MariaDB 12.3 e versões posteriores podem emitir um evento de linhas parciais no binlog, que ainda não é compatível.

Para se recuperar, ressincronize o pipe. Para reduzir a chance de isso ocorrer novamente, você também pode aumentar a configuração binlog_row_event_fragment_threshold na origem, para que menos alterações de linhas sejam fragmentadas — mantenha-a abaixo de max_allowed_packet, pois um único evento de binlog não fragmentado maior que max_allowed_packet fará o stream de replicação falhar (consulte Por que meu pipe está falhando com um erro de binlog relacionado a max_allowed_packet?).

​

Por que meu pipe falhou devido a uma coluna COMPRESSED do MariaDB sem suporte?

Se o seu pipe falhar com um erro semelhante a:

table <database>.<table> has MariaDB COMPRESSED column(s) [<columns>], which cannot be replicated via CDC;
convert them to a non-compressed type or remove the table from the mirror

isso significa que a tabela tem uma ou mais colunas usando a compressão de coluna do MariaDB (COLUMN_FORMAT COMPRESSED). Não é possível descomprimir esses valores a partir do binlog, então a tabela afetada não pode ser replicada via CDC.

Para resolver:

• Converta as colunas comprimidas para um tipo sem compressão na origem (ou remova uma tabela do pipe):
  ALTER TABLE <table> MODIFY <column> <type>; -- sem COLUMN_FORMAT COMPRESSED
  
• ressincronize a tabela ou o pipe

​

O ClickPipe do MySQL é compatível com PlanetScale, Vitess ou TiDB?

Não, eles não são compatíveis com a API de binlog do MySQL.

​

Como a replicação é gerenciada?

Oferecemos suporte à replicação GTID e FilePos. Diferentemente do Postgres, não há slot para gerenciar o offset. Em vez disso, você deve configurar seu servidor MySQL com um período de retenção do binlog suficiente. Se nosso offset no binlog se tornar inválido (por exemplo, se o mirror ficar pausado por muito tempo ou ocorrer um failover do banco de dados durante o uso da replicação FilePos), será necessário ressincronizar o pipe. Certifique-se de otimizar as visões materializadas que dependem das tabelas de destino, pois consultas ineficientes podem desacelerar a ingestão e fazer com que ela fique atrás do período de retenção.

Também é possível que um banco de dados inativo faça a rotação do arquivo de log sem permitir que o ClickPipes avance para um offset mais recente. Talvez seja necessário configurar uma tabela de heartbeat com atualizações agendadas regularmente.

No início de uma carga inicial, registramos o offset do binlog a partir do qual começar. Esse offset ainda precisa ser válido quando a carga inicial terminar para que o CDC avance. Se você estiver fazendo ingestão de um grande volume de dados, configure um período de retenção do binlog adequado. Ao configurar tabelas, você pode acelerar a carga inicial definindo Use a custom partitioning key for initial load para tabelas grandes nas configurações avançadas, para que possamos carregar uma única tabela em paralelo.

​

Por que meu pipe falha com um erro de binlog max_allowed_packet?

Se o seu pipe falhar com um erro semelhante a:

MySQL execute error: ERROR 1236 (HY000): log event entry exceeded max_allowed_packet;
Increase max_allowed_packet on source

isso significa que um único evento do binlog (correspondente à alteração de uma linha) é maior que a configuração max_allowed_packet do seu servidor MySQL. Como o servidor não consegue enviar um evento que exceda esse limite, a leitura do fluxo do binlog é abortada e o CDC não consegue avançar.

Na maioria das vezes, isso é causado por linhas com valores grandes de BLOB, TEXT ou JSON. Para resolver:

• Aumente max_allowed_packet na origem. Defina-o acima do tamanho da sua maior alteração de linha — configurá-lo no valor máximo de 1G geralmente é seguro:
  SET GLOBAL max_allowed_packet = 1073741824; -- 1 GiB
  
  Defina-o também na configuração do seu servidor (por exemplo, my.cnf ou o grupo de parâmetros do DB) para que persista após reinicializações.
• Se uma única linha for maior que 1G: ressincronize o pipe.

​

Por que meu pipe falha com um erro de binlog JSON parcial?

Se o seu pipe falhar com um erro semelhante a:

Received a partial JSON update event while processing <database>.<table>; binlog_row_value_options must be disabled (set to '')

isso significa que o servidor MySQL de origem está com binlog_row_value_options definido como PARTIAL_JSON. Com essa opção ativada, o MySQL registra atualizações em colunas JSON como diferenças parciais (apenas os paths alterados), em vez do documento completo. O ClickPipes não consegue aplicar essas diferenças parciais, portanto o CDC não consegue avançar.

Para resolver:

• Desative PARTIAL_JSON na origem. Redefina o valor como vazio:
  SET GLOBAL binlog_row_value_options = '';
  
  Remova essa configuração também da configuração do servidor (por exemplo, my.cnf ou o DB Parameter Group) para que a alteração persista após reinicializações.
• Ressincronize o pipe para que a replicação seja retomada a partir de um offset limpo.

​

Por que meu pipe falha com um erro require_secure_transport?

Se o pipe falhar com um erro semelhante a:

MySQL execute error: handleAuthResult: ERROR 3159 (HY000): Connections using insecure transport
are prohibited while --require_secure_transport=ON.

isso significa que o servidor de origem está com require_secure_transport ativado — ele rejeita conexões não criptografadas —, enquanto o TLS está desativado no ClickPipe. No RDS para MySQL, essa configuração vem do DB Parameter Group da instância. No Aurora MySQL, ela pertence ao grupo de parâmetros do cluster de DB e não está disponível nos grupos de parâmetros da instância. Nenhum dos dois requer reinicialização para entrar em vigor. No Aurora MySQL 8.4, o padrão é ON, enquanto nas versões 2 e 3 é OFF; portanto, um pipe que vinha replicando sem problemas pode começar a falhar após uma alteração de parâmetro ou um upgrade de versão, sem nenhuma alteração no próprio pipe.

Para resolver:

• Reative o TLS no pipe. Em Settings do pipe, abra as configurações de conexão e desative o toggle Disable TLS. Se ocorrer um erro de certificado ao salvar, consulte Por que estou recebendo um erro de validação de certificado TLS ao conectar ao MySQL? para saber como definir um host TLS, fazer upload de uma CA raiz ou ignorar a verificação de certificados.
• Ou desative require_secure_transport na origem — no DB Parameter Group no RDS ou no grupo de parâmetros do cluster de DB no Aurora — se conexões não criptografadas forem aceitáveis no seu ambiente.

A replicação é retomada de onde parou assim que a conexão for estabelecida. Se o pipe falhou por mais tempo do que o período de retenção do binlog (consulte Como a replicação é gerenciada?), será necessário ressincronizá-lo.

​

Por que estou recebendo um erro de validação de certificado TLS ao me conectar ao MySQL?

Ao se conectar ao MySQL, você pode encontrar erros de certificado como x509: certificate is not valid for any names ou x509: certificate signed by unknown authority. Isso acontece porque o ClickPipes habilita a criptografia TLS por padrão.

Você tem várias opções para resolver esses problemas:

1. Defina o campo TLS Host - Quando o hostname da sua conexão for diferente do certificado (algo comum com AWS PrivateLink via Endpoint Service), defina “TLS Host (optional)” para corresponder ao Common Name (CN) ou Subject Alternative Name (SAN) do certificado.

2. Faça upload da sua CA raiz - Para servidores MySQL que usam autoridades certificadoras internas ou o Google Cloud SQL na configuração padrão de CA por instância. Para mais informações sobre como acessar certificados do Google Cloud SQL, consulte esta seção.

3. Configure o certificado do servidor - Atualize o certificado SSL do seu servidor para incluir todos os hostnames de conexão e usar uma autoridade certificadora confiável.

4. Ignore a verificação do certificado - Para MySQL ou MariaDB self-hosted, cujas configurações padrão provisionam um certificado autoassinado que não conseguimos validar (MySQL, MariaDB). Confiar nesse certificado criptografa os dados em trânsito, mas traz o risco de falsificação de identidade do servidor. Recomendamos certificados devidamente assinados para ambientes de produção, mas essa opção é útil para testes em uma instância isolada ou para conexão com infraestrutura legada.

​

Há suporte a alterações de esquema?

Consulte a página ClickPipes for MySQL: suporte à propagação de alterações de esquema para mais informações.

​

Há suporte para replicar exclusões em cascata de chave estrangeira do MySQL ON DELETE CASCADE?

Devido à forma como o MySQL trata exclusões em cascata, elas não são gravadas no binlog. Portanto, não é possível que o ClickPipes (ou qualquer ferramenta de CDC) as replique. Isso pode levar a inconsistências nos dados. Recomenda-se usar gatilhos para dar suporte a exclusões em cascata.

​

Por que não consigo replicar minha tabela que tem um ponto no nome?

No momento, o PeerDB tem uma limitação: pontos nos identificadores da tabela de origem — ou seja, no nome do schema ou no nome da tabela — não são compatíveis com a replicação, pois, nesse caso, o PeerDB não consegue distinguir o que é schema e o que é tabela, já que faz a separação pelo ponto. Está sendo feito um esforço para permitir a entrada de schema e tabela separadamente e, assim, contornar essa limitação.

​

Posso incluir colunas que excluí inicialmente da replicação?

Isso ainda não é compatível; uma alternativa seria ressincronizar a tabela da qual você deseja incluir as colunas.