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 →
PostgreSQL e MySQL compartilham a sintaxe ANSI SQL, mas divergem de maneiras suficientes para que uma migração exija atenção cuidadosa aos tipos de dados, aos comportamentos padrão e às diferenças de dialeto SQL. A maior parte do trabalho é a tradução do esquema e a correção de consultas que dependem de recursos específicos do PostgreSQL. Este guia cobre a migração do PostgreSQL para o MySQL, a direção comum ao mover para um servidor compatível com MySQL como o VillageSQL — um substituto direto e de código aberto para o MySQL que adiciona um framework de extensões no estilo PostgreSQL por cima. Esse framework é o motivo de este guia ter um lugar para as suas extensões PostgreSQL pousarem, e não só o seu esquema e os seus dados; consulte Trazendo as Suas Extensões abaixo. Se você estiver movendo dados na direção contrária, o mapeamento de tipos e as diferenças de dialeto abaixo ainda se aplicam ao contrário, mas a seção de ferramentas de migração não.

Qual Abordagem Devo Usar

  • Cutover único — dump/restore com pg_dump e LOAD DATA INFILE. Consulte Ferramentas de Migração e Abordagem de Migração abaixo.
  • Precisa que o banco de dados de origem continue ativo e gravável durante a migração, ou uma sincronização contínua — configure o Debezium com um conector JDBC sink para replicação contínua em vez de um dump único.

Ferramentas de Migração

pg_dump + conversão manual do esquema é o caminho principal e não precisa de nada além das ferramentas de cliente padrão do PostgreSQL e do MySQL:
A saída de esquema do pg_dump usa a sintaxe do PostgreSQL (SERIAL, BOOLEAN, cláusulas de CREATE TABLE específicas do PostgreSQL), então o arquivo de esquema precisa de tradução manual usando a tabela de mapeamento de tipos abaixo antes de rodar no MySQL. Não existe uma ferramenta que faça essa tradução automaticamente e corretamente para todos os casos — trate este como o caminho padrão para a maioria das migrações. Debezium com um conector JDBC sink (debezium.io, licença Apache-2.0, mantido ativamente) lê o write-ahead log do PostgreSQL e transmite as mudanças para o MySQL através do Kafka Connect, oferecendo replicação contínua em vez de uma cópia única. É a ferramenta certa quando o banco de dados de origem precisa continuar ativo e gravável durante a migração, ou quando você precisa de sincronização contínua em vez de um cutover. Ele exige um cluster Kafka e Kafka Connect em execução, o que é mais infraestrutura do que uma migração única precisa — para um cutover único, use pg_dump.

Mapeamento de Tipos de Dados

Sequences vs AUTO_INCREMENT

O PostgreSQL usa sequences (objetos independentes) para valores de auto-incremento. O MySQL usa AUTO_INCREMENT como um atributo de coluna: PostgreSQL:
Equivalente MySQL:
Para obter o último ID inserido no MySQL: SELECT LAST_INSERT_ID(); (equivalente ao currval() ou ao RETURNING id do PostgreSQL).

Diferenças de Dialeto SQL

Concatenação de strings:
Aspas em strings:
O MySQL aceita aspas duplas para identificadores somente quando o modo SQL ANSI_QUOTES está habilitado. ILIKE (LIKE sem distinção de maiúsculas e minúsculas):
As comparações de strings no MySQL não distinguem maiúsculas de minúsculas por padrão com utf8mb4_0900_ai_ci (o padrão do MySQL 8.x) ou collations _ci semelhantes. Se você precisar de correspondência com distinção de maiúsculas e minúsculas, use uma collation _bin. Cláusula RETURNING:
LIMIT / OFFSET:
Schemas vs bancos de dados: O PostgreSQL usa schemas dentro de um banco de dados (mydb.public.orders). O MySQL usa “schemas” e “bancos de dados” de forma intercambiável — não existe o conceito de um schema dentro de um banco de dados. O que o PostgreSQL chama de schema, o MySQL chama de banco de dados. Tratamento de NULL em índices UNIQUE: O PostgreSQL permite vários valores NULL em uma coluna com restrição UNIQUE (NULLs não são iguais entre si). O MySQL (InnoDB) também permite vários NULLs em índices únicos — o comportamento é o mesmo. CTEs: O MySQL suporta CTEs, incluindo CTEs recursivas. Consulte Expressões de tabela comuns no MySQL. Funções de janela: O MySQL suporta funções de janela. Consulte Funções de Janela no MySQL. Stored procedures e funções: O PostgreSQL escreve lógica procedural em PL/pgSQL, com tratamento de exceções e controle de fluxo rico. O MySQL usa o seu próprio dialeto SQL procedural, não tem suporte a PL/pgSQL e exige uma mudança de DELIMITER nas ferramentas de cliente para que os pontos e vírgulas dentro do corpo da procedure não sejam interpretados como o fim da instrução:
Não existe tradução automatizada de PL/pgSQL para a sintaxe procedural do MySQL — reescreva cada procedure à mão, e espere que a lógica de tratamento de exceções (blocos EXCEPTION WHEN ...) precise do maior retrabalho, já que o DECLARE ... HANDLER do MySQL funciona de forma diferente. Consulte Stored Procedures no MySQL. Distinção de maiúsculas e minúsculas em identificadores: O PostgreSQL converte identificadores sem aspas para minúsculas e trata identificadores com aspas ("MyTable") com distinção de maiúsculas e minúsculas. A regra do MySQL é diferente: se os nomes de bancos de dados e tabelas distinguem maiúsculas de minúsculas depende da variável de sistema lower_case_table_names e do sistema de arquivos subjacente, não das aspas. Nomes de colunas, índices e rotinas armazenadas nunca distinguem maiúsculas de minúsculas para fins de busca, independentemente da plataforma. Não presuma que um esquema que dependia de nomes de tabela do PostgreSQL com distinção de maiúsculas e minúsculas vai se comportar de forma idêntica após a migração — verifique lower_case_table_names no servidor de destino.

Recursos Sem Equivalente no MySQL

Alguns recursos do PostgreSQL não têm equivalente direto:

Trazendo as Suas Extensões

O PostgreSQL depende de extensões como pgcrypto, pg_trgm e uuid-ossp para funcionalidades que ele não traz nativamente. O MySQL padrão não tem um mecanismo equivalente para adicionar esse tipo de funcionalidade — mas o VillageSQL tem: o VillageSQL Extension Framework (VEF) permite instalar funções e tipos SQL personalizados no servidor com INSTALL EXTENSION. Algumas das extensões do VillageSQL são ports diretos das extensões PostgreSQL acima: Se o seu banco de dados PostgreSQL depende de uma extensão que não está listada aqui, ela pode ainda não ter um equivalente no VillageSQL — verifique o catálogo de extensões na documentação do VillageSQL antes de presumir que a funcionalidade se foi de vez. E se a dependência for uma extensão PostgreSQL personalizada que a sua própria equipe escreveu, o VEF também é a ferramenta para portá-la: a skill vsql-extension-builder conduz um agente de codificação com IA pela reconstrução de uma extensão personalizada no VillageSQL, dos requisitos até um pacote .veb testado e documentado.

Abordagem de Migração

  1. Exporte o esquema do PostgreSQL (pg_dump --schema-only) e traduza cada tabela manualmente, usando o mapeamento de tipos acima.
  2. Exporte os dados do PostgreSQL como CSV (COPY table TO '/tmp/table.csv' CSV HEADER).
  3. Carregue os dados no MySQL com LOAD DATA INFILE ou mysqlimport.
  4. Teste as consultas — encontre toda a sintaxe específica do PostgreSQL e reescreva-a.
  5. Verifique contagens e checksums — SELECT COUNT(*) em todas as tabelas; confira por amostragem as linhas principais.

Perguntas Frequentes

O MySQL suporta UPSERT como o ON CONFLICT do PostgreSQL?

Sim, usando uma sintaxe diferente. Consulte UPSERT no MySQL. O INSERT ... ON DUPLICATE KEY UPDATE e o REPLACE INTO do MySQL cobrem o mesmo caso de uso que o ON CONFLICT DO UPDATE e o ON CONFLICT DO NOTHING do PostgreSQL.

Como lidar com as colunas BOOLEAN do PostgreSQL no MySQL?

Use TINYINT(1). Armazene 1 para verdadeiro e 0 para falso. A maioria das bibliotecas de cliente e ORMs do MySQL lida com isso automaticamente e apresenta colunas TINYINT(1) como booleanos. Você também pode usar BIT(1), mas TINYINT(1) tem suporte mais amplo nas ferramentas.

Solução de Problemas

Veja também