Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
O MariaDB e o MySQL compartilham o mesmo protocolo de rede e a maior parte da mesma superfície SQL, então uma migração parece enganosamente simples: fazer o dump, e depois carregar. Na prática, alguns tipos, objetos e comportamentos de dump específicos do MariaDB interrompem uma carga simples no meio do caminho, e um deles muda o tipo armazenado de uma coluna sem gerar erro algum. Este guia cobre o que de fato quebra e como corrigir, com base em um dump real tirado do MariaDB 12.3.3 e carregado no MySQL.

Diferenças de Tipos de Dados e de Valores Padrão

Objetos de Esquema Exclusivos do MariaDB Quebram a Carga

Um esquema que usa CREATE SEQUENCE falha imediatamente ao ser carregado no MySQL, antes de qualquer tabela ser criada, porque o mysqldump escreve as definições de sequence antes das tabelas. Carregar um dump sem modificação que contém uma sequence produz isto, em que os valores de at line N indicam onde a instrução está no seu próprio dump e não vão corresponder aos números mostrados aqui:
Remova o bloco DROP SEQUENCE / CREATE SEQUENCE / DO SETVAL(...) do dump, e substitua qualquer valor padrão de coluna que diga DEFAULT nextval(...) por uma coluna AUTO_INCREMENT simples ou por um valor atribuído pela aplicação. Uma coluna do tipo INET6 falha da mesma forma, mais adiante na mesma carga, quando o carregador chega à tabela que a declara. Este é o único erro deste guia cujo texto depende do servidor em que você carrega. O VillageSQL nomeia o tipo, porque sua gramática aceita nomes de tipos personalizados nessa posição e reporta o que não conseguiu resolver:
O MySQL 8.4 padrão rejeita a mesma instrução com o erro de sintaxe genérico:
Os dois são ERROR 1064, e os dois nomeiam a linha problemática, então a correção é a mesma em ambos os casos. Mude o tipo da coluna para VARCHAR(45) (longo o suficiente para um endereço IPv6 em forma de texto) antes de carregar, ou para um tipo INET fornecido por uma extensão, se houver uma instalada no destino.

Nomes de Restrições de Chave Estrangeira Colidem Entre Tabelas

O mysqldump no MariaDB nomeia automaticamente uma restrição de chave estrangeira sem nome com um inteiro simples, recomeçando de 1 em cada tabela. Duas tabelas no mesmo esquema podem acabar as duas com uma restrição literalmente chamada 1:
O MySQL exige que os nomes das restrições de chave estrangeira sejam únicos em todo o esquema, e não apenas dentro de uma tabela. Carregar o segundo CONSTRAINT 1“ falha com:
Isso só acontece quando as tabelas originais dependiam da nomeação automática do MariaDB (sem CONSTRAINT name no CREATE TABLE). Renomeie cada restrição em conflito para algo único, por exemplo order_items_ibfk_1 e orders_ibfk_1, antes de carregar.

A Coluna JSON É Carregada Sem Erro, como um Tipo Diferente

Ao contrário dos três problemas acima, uma coluna JSON é carregada no MySQL sem erro e sem aviso. O CREATE TABLE do dump para uma coluna JSON do MariaDB tem esta aparência:
O MySQL suporta restrições CHECK e a função JSON_VALID(), então essa instrução roda como está. A coluna acaba como LONGTEXT com uma restrição CHECK do lado do MySQL, e não como o tipo JSON nativo do MySQL. Lê-la de volta com JSON_EXTRACT() e JSON_LENGTH() dá resultados idênticos aos dados de origem, então nada se perde, mas o tipo declarado da coluna é diferente do que um esquema MySQL novo usaria. Se você quer o tipo JSON nativo no destino, altere a coluna depois de carregar:
Isso deixa a restrição original CHECK (json_valid(...)) anexada à coluna. O dump não nomeia essa restrição, então o servidor a nomeou quando o CREATE TABLE rodou, algo como products_chk_1; ela já está lá antes do ALTER. Ela é inofensiva em uma coluna JSON nativa, já que o MySQL já rejeita JSON inválido no nível do tipo, mas é peso morto deixado pela definição LONGTEXT. Remova-a se você quer um esquema limpo:

Diferenças de Autenticação

Os clientes do MariaDB e do MySQL falam o mesmo protocolo de rede, e uma conexão simples autenticada por senha de um para o outro funciona. O que não se transfere é a definição da conta em si. O mysqldump não faz o dump da tabela mysql.user por padrão, então as contas e as concessões precisam ser recriadas à mão no destino, e a sintaxe para fazer isso é diferente. Uma conta do MariaDB criada com senha aparece assim:
A mesma instrução no MySQL ou no VillageSQL, usando o plugin padrão caching_sha2_password, tem esta aparência:
Não copie uma instrução SHOW CREATE USER do MariaDB para o MySQL. Crie a conta do zero com CREATE USER ... IDENTIFIED BY '<password>' no destino e deixe-o escolher o seu próprio plugin padrão, e então emita novamente as instruções GRANT. Se você está testando uma migração em uma instalação do MariaDB que acabou de configurar (uma instalação nova do Homebrew, por exemplo), e uma conta nomeada com senha é rejeitada com “Access denied” mesmo com a senha certa, verifique primeiro se há contas anônimas:
Uma instalação não protegida do MariaDB pode deixar ''@'localhost' e ''@'<hostname>' no lugar. Como a correspondência por host é mais específica do que a correspondência por nome de usuário, uma conexão que resolve para localhost corresponde à conta anônima antes de corresponder à sua conta nomeada, e é rejeitada porque a conta anônima não espera senha. Esse é um problema da instalação de origem do MariaDB, e não algo que acompanha os dados até o MySQL, mas ele pode tornar os testes do lado da origem confusos até que as contas anônimas sejam removidas.

Abordagem de Migração

  1. Faça o dump do esquema e dos dados com mysqldump (em um host MariaDB isso normalmente é um link simbólico para o mariadb-dump do próprio MariaDB; execute mysqldump --version para confirmar qual você tem).
  2. Procure CREATE SEQUENCE, INET6 e RETURNING no dump antes de tentar uma carga. Nenhum dos três produz um erro útil até que a carga já esteja no meio do caminho.
  3. Tente primeiro uma carga em um banco de dados descartável. Uma falha de CREATE SEQUENCE ou INET6 aborta o script inteiro naquela instrução, então as tabelas definidas antes no arquivo já estão carregadas e as tabelas definidas depois não estão. Corrija o dump e recarregue em um banco de dados novo em vez de remendar um carregado pela metade.
  4. Verifique colisões de nomes de restrições de chave estrangeira se o esquema de origem dependia de chaves estrangeiras sem nome. grep -o 'CONSTRAINT \[0-9]*`’ dump.sql` as encontra.
  5. Recrie as contas e as concessões à mão. O mysqldump não as inclui, e a sintaxe de CREATE USER / SHOW CREATE USER difere entre os dois servidores.
  6. Verifique as contagens de linhas e confira por amostragem as colunas JSON. Uma coluna JSON é carregada silenciosamente como LONGTEXT; confirme com JSON_EXTRACT() que os dados foram carregados intactos antes de decidir se vai convertê-la em uma coluna JSON nativa.

Perguntas Frequentes

Um arquivo de mysqldump do MariaDB precisa de alguma edição para um destino MySQL da mesma família de versões?

Se o esquema não usa sequences, INET6, RETURNING nem chaves estrangeiras sem nome, o mesmo dump frequentemente é carregado sem alterações. Teste a carga em um banco de dados descartável primeiro, em vez de presumir que ela vai funcionar por o esquema ser “só tabelas e dados”.

Uma coluna JSON nativa do MySQL faz a ida e volta corretamente por um dump do MariaDB?

Os valores fazem a ida e volta corretamente. O tipo da coluna, não: o MariaDB faz o dump das suas colunas JSON como LONGTEXT com uma restrição CHECK, e é exatamente isso que é carregado no MySQL, a menos que você execute explicitamente ALTER TABLE ... MODIFY na coluna para JSON depois.

Posso me conectar a um servidor MariaDB com um cliente MySQL, ou o inverso?

Sim, para conexões comuns autenticadas por senha. Os dois usam o mesmo protocolo de rede, e um cliente compilado com uma biblioteca consegue se autenticar em uma conta no outro servidor, uma vez que a conta em si exista com uma senha. O SQL que cada servidor aceita é onde eles divergem, e não a conexão.

Solução de Problemas

Veja também