Guia MariaDB para PostgreSQL: checklist de migração segura

17 min de leitura  ·  Guia técnico

guia MariaDB para PostgreSQL é um checklist de migração segura para mover dados do MariaDB para PostgreSQL no Alpine Linux 3.22 preservando schema, conteúdo e validações críticas. Para migrar com integridade, siga estes passos:

1. Prepare o Alpine Linux 3.22 com clientes MariaDB e PostgreSQL e confirme acessos.
2. Inventarie tabelas, índices, constraints, encoding e contagens antes de exportar.
3. Gere backup consistente do MariaDB e congele alterações durante a janela final.
4. Converta o schema para sintaxe PostgreSQL e importe primeiro em homologação.
5. Carregue os dados por tabela, valide contagens e teste consultas da aplicação.
6. Faça o cutover somente após validação e mantenha plano de rollback.

Pré-requisitos do guia MariaDB para PostgreSQL

A migração MariaDB para PostgreSQL no Alpine Linux 3.22 exige preparação antes de qualquer exportação, porque os dois bancos não interpretam schema, tipos e funções da mesma forma. Ao rodar os comandos abaixo, você deve estar conectado ao servidor onde executará a operação, preferencialmente em uma sessão estável de SSH e com janela de manutenção definida.

• Acesso root ou usuário com permissões administrativas no Alpine Linux 3.22.
• Credenciais de leitura no MariaDB de origem e permissão para criar banco, schema e tabelas no PostgreSQL de destino.
• Espaço em disco suficiente para dump, arquivos intermediários e logs da migração.
• Lista das tabelas críticas da aplicação, consultas importantes e pontos de validação funcional.
• Janela de manutenção ou mecanismo para pausar gravações no MariaDB durante a migração final.
• Backup externo ou snapshot antes de modificar qualquer banco de produção.

Se você ainda vai acessar o ambiente por SSH, veja também Acessando servidores VPS Linux da AviraHost. Para cenários em que a aplicação usará conexão remota ao PostgreSQL, a referência Conectando remotamente ao PostgreSQL - cPanel ajuda a revisar conceitos de host, porta, usuário e permissão.

cat /etc/alpine-release
apk update
apk add mariadb-client postgresql-client

Output esperado:
3.22.x
fetch de índices do repositório Alpine concluído
mariadb-client instalado
postgresql-client instalado

Atenção: não inicie a importação definitiva antes de testar o processo em um banco PostgreSQL separado. A primeira execução deve servir para descobrir incompatibilidades de tipo, nomes reservados, diferenças em valores booleanos, datas e constraints.

Inventário do banco MariaDB antes da exportação

O checklist de migração segura começa pelo inventário do MariaDB, pois ele cria a linha de base para provar que a importação no PostgreSQL está completa. Nesta etapa, registre tabelas, contagens, engines, colunas, chaves primárias e objetos que a aplicação usa. Não confie apenas no sucesso do comando de dump: uma migração pode terminar sem erro aparente e ainda assim carregar tipos errados, perder constraints ou alterar comportamento de consultas.

1. Confirme que você está apontando para o banco correto.
2. Liste tabelas e contagens estimadas para ter uma visão inicial do volume.
3. Exporte a definição das tabelas separadamente dos dados.
4. Registre rotinas, triggers e eventos, se existirem.
5. Identifique colunas que exigem conversão manual, como auto incremento, enum, booleanos e datas.

mysql -h origem-mariadb -u usuario_mariadb -p -e "SELECT DATABASE();"

mysql -h origem-mariadb -u usuario_mariadb -p -N -e "SELECT TABLE_NAME, TABLE_ROWS FROM information_schema.TABLES WHERE TABLE_SCHEMA='appdb' ORDER BY TABLE_NAME;" > inventario_tabelas_mariadb.txt

mysql -h origem-mariadb -u usuario_mariadb -p -N -e "SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA='appdb' ORDER BY TABLE_NAME, ORDINAL_POSITION;" > inventario_colunas_mariadb.txt

Output esperado:
DATABASE()
appdb

arquivos gerados:
inventario_tabelas_mariadb.txt
inventario_colunas_mariadb.txt

Ao abrir os arquivos, você verá os nomes das tabelas e os tipos usados no MariaDB. Marque tudo que não deve ser convertido automaticamente sem revisão: colunas com auto incremento, enumerações, campos de data com valor padrão, colunas textuais com encoding específico e chaves estrangeiras. Essa documentação será usada mais tarde para comparar o PostgreSQL depois da importação.

Backup consistente do MariaDB no Alpine Linux 3.22

O backup consistente do MariaDB é a sua proteção contra falhas de conversão e também o ponto de retorno caso a aplicação precise voltar ao banco antigo. Para bases em uso, prefira uma janela de manutenção ou bloqueio de gravações pela aplicação. O objetivo é garantir que o dump e os arquivos exportados representem o mesmo momento lógico do banco.

Atenção: os comandos abaixo criam arquivos de backup, mas podem expor dados sensíveis no servidor. Salve os dumps em diretório restrito, não envie por canais inseguros e remova cópias temporárias quando a migração estiver validada.

mkdir -p /root/migracao-mariadb-postgresql
chmod 700 /root/migracao-mariadb-postgresql
cd /root/migracao-mariadb-postgresql

mysqldump -h origem-mariadb -u usuario_mariadb -p --single-transaction --routines --triggers --events --default-character-set=utf8mb4 appdb > appdb_mariadb_backup.sql

ls -lh appdb_mariadb_backup.sql

Output esperado:
arquivo appdb_mariadb_backup.sql criado
permissões restritas ao diretório de migração
tamanho do arquivo exibido pelo ls

Esse dump completo não deve ser importado diretamente no PostgreSQL como se fosse SQL compatível. Ele serve como backup auditável e referência do estado original. Em seguida, gere um arquivo apenas com o schema para facilitar a conversão manual e um plano de carga dos dados por tabela.

mysqldump -h origem-mariadb -u usuario_mariadb -p --no-data --skip-comments appdb > schema_mariadb.sql

ls -lh schema_mariadb.sql

Output esperado:
schema_mariadb.sql criado
arquivo menor que o dump completo
definições de tabelas disponíveis para revisão

Revise o schema antes de seguir. Em uma migração real, esta é uma das etapas mais importantes: nomes com aspas, tipos numéricos, texto longo, valores padrão e funções internas podem precisar de ajustes para o PostgreSQL aceitar o DDL e manter o mesmo significado de negócio.

Conversão de schema MariaDB para PostgreSQL

A conversão de schema MariaDB para PostgreSQL precisa ser tratada como uma etapa de engenharia, não como simples troca de extensão de arquivo. O PostgreSQL usa regras próprias para tipos, identificadores, chaves, sequências, defaults e funções. Por isso, crie um arquivo de DDL PostgreSQL revisado e importe em um banco de homologação antes de tocar na produção.

1. Crie o banco PostgreSQL de destino em ambiente de teste.
2. Traduza o DDL do MariaDB para sintaxe PostgreSQL.
3. Remova opções específicas do MariaDB que não existem no PostgreSQL.
4. Recrie chaves primárias, índices e constraints com nomes claros.
5. Execute o schema e corrija erros até a criação ficar limpa.

createdb -h destino-postgresql -U usuario_pg appdb_pg

psql -h destino-postgresql -U usuario_pg -d appdb_pg -c "SELECT current_database();"

Output esperado:
CREATE DATABASE concluído ou banco já preparado
current_database
appdb_pg

Crie o arquivo schema_postgresql.sql com as tabelas convertidas. Como referência prática, revise principalmente colunas de incremento automático, booleanos, campos de data, enumerações e defaults. Não transforme tudo às cegas: se uma coluna guarda valores de negócio específicos, preserve o significado antes de escolher o tipo no PostgreSQL.

psql -h destino-postgresql -U usuario_pg -d appdb_pg -f schema_postgresql.sql

Output esperado:
CREATE TABLE
CREATE INDEX
ALTER TABLE
schema criado sem erros críticos

Se o comando retornar erro de sintaxe, pare e ajuste o DDL. Continuar com uma importação parcial aumenta o risco de dados órfãos, colunas ausentes e validação enganosa. Ao final, liste as tabelas criadas no PostgreSQL e compare com o inventário original.

psql -h destino-postgresql -U usuario_pg -d appdb_pg -c "\dt"

Output esperado:
lista de tabelas do schema público ou do schema definido
nomes compatíveis com o inventário do MariaDB

Importação dos dados no PostgreSQL com validação

A importação dos dados no PostgreSQL deve ser repetível, registrada e validada por tabela. Uma abordagem segura é exportar dados do MariaDB em formato tabular por tabela, importar com comando de cópia no PostgreSQL e comparar contagens imediatamente. Em bancos grandes, faça primeiro um subconjunto representativo para confirmar conversão de caracteres, nulos, datas e relacionamentos.

O exemplo abaixo usa uma tabela chamada users. Adapte a lista de colunas para cada tabela. Declarar as colunas explicitamente reduz risco quando a ordem do schema muda ou quando há campos gerados no PostgreSQL.

mysql -h origem-mariadb -u usuario_mariadb -p --batch --raw --skip-column-names -e "SELECT id, email, created_at FROM appdb.users ORDER BY id;" > users.tsv

psql -h destino-postgresql -U usuario_pg -d appdb_pg -c "\copy users(id, email, created_at) FROM 'users.tsv' WITH DELIMITER E'\t' NULL ''"

Output esperado:
arquivo users.tsv criado
COPY quantidade_de_linhas

Depois da carga, compare a contagem da origem e do destino. Faça isso para todas as tabelas, priorizando as que concentram dados financeiros, autenticação, pedidos, logs de auditoria ou qualquer entidade crítica da aplicação.

mysql -h origem-mariadb -u usuario_mariadb -p -N -e "SELECT COUNT(*) FROM appdb.users;"

psql -h destino-postgresql -U usuario_pg -d appdb_pg -t -c "SELECT COUNT(*) FROM users;"

Output esperado:
o número retornado no MariaDB deve ser igual ao número retornado no PostgreSQL
diferença de contagem exige interromper a migração e investigar

Além de contagens, execute consultas reais usadas pela aplicação. Teste filtros por data, ordenações, joins, paginação, autenticação e escrita em tabelas temporárias de homologação. A integridade de dados não é apenas quantidade de linhas: ela inclui comportamento esperado, constraints ativas, índices adequados e compatibilidade com o código da aplicação.

Cutover seguro e rollback planejado

O cutover MariaDB para PostgreSQL é o momento em que a aplicação deixa de escrever no banco antigo e passa a usar o banco novo. Essa troca deve acontecer somente depois que a importação em homologação foi repetida com sucesso e documentada. O processo final precisa ser curto, previsível e reversível.

1. Avise usuários ou equipe sobre a janela de manutenção.
2. Coloque a aplicação em modo sem escrita ou interrompa temporariamente tarefas que gravam no banco.
3. Gere o backup final do MariaDB e repita a exportação dos dados alterados.
4. Importe no PostgreSQL definitivo usando o procedimento já testado.
5. Valide contagens, constraints e consultas críticas.
6. Altere a configuração da aplicação para apontar ao PostgreSQL.
7. Mantenha o MariaDB intacto até confirmar estabilidade operacional.

psql -h destino-postgresql -U usuario_pg -d appdb_pg -c "SELECT now();"

psql -h destino-postgresql -U usuario_pg -d appdb_pg -c "SELECT COUNT(*) FROM users;"

Output esperado:
conexão PostgreSQL funcionando
horário retornado pelo banco
contagem validada na tabela testada

Atenção: não remova o banco MariaDB imediatamente após o cutover. Mantenha-o preservado por tempo suficiente para auditoria e possível rollback. O rollback deve estar documentado antes da troca: quais arquivos restaurar, qual configuração da aplicação reverter e quem autoriza a decisão.

Problemas comuns e como resolver

Sintoma: erro de sintaxe ao importar o schema no PostgreSQL

Causa: o arquivo de schema ainda contém construções específicas do MariaDB, como opções de engine, tipos incompatíveis, defaults não aceitos ou identificadores que precisam ser ajustados.

Solução: volte ao arquivo schema_postgresql.sql, corrija uma tabela por vez e execute novamente em banco de homologação. Não tente importar dados enquanto o DDL não estiver limpo, porque isso pode mascarar falhas estruturais.

Sintoma: contagem de linhas diferente entre MariaDB e PostgreSQL

Causa: a origem recebeu gravações durante a exportação, alguma tabela foi exportada com filtro incorreto ou a importação parou antes de concluir todos os registros.

Solução: coloque a aplicação em modo sem escrita, gere nova exportação da tabela afetada e repita a carga no PostgreSQL. Compare novamente com COUNT e valide amostras de registros antes de seguir para o cutover.

Sintoma: caracteres acentuados aparecem quebrados após a importação

Causa: houve divergência de encoding entre a exportação do MariaDB, o arquivo intermediário e o banco PostgreSQL de destino.

Solução: confirme o charset usado na exportação, gere novamente o arquivo com configuração consistente e teste em uma tabela pequena antes de importar todo o banco. Também valide campos com acentos, símbolos e textos longos.

Sintoma: aplicação conecta, mas consultas retornam erro

Causa: diferenças de SQL entre MariaDB e PostgreSQL podem afetar aspas, funções, concatenação, booleanos, paginação, ordenação e tratamento de datas.

Solução: liste as consultas críticas da aplicação e ajuste o código para a sintaxe PostgreSQL. Teste autenticação, cadastro, atualização, relatórios e rotinas agendadas antes de liberar tráfego real.

Perguntas frequentes sobre guia MariaDB para PostgreSQL

Como migrar MariaDB para PostgreSQL no Alpine Linux 3.22 sem perder dados?

Para migrar sem perder dados, faça um backup consistente do MariaDB, registre schema e contagens de linhas, converta tipos incompatíveis e importe primeiro em um banco PostgreSQL de homologação. Só aponte a aplicação para o PostgreSQL após validar integridade, encoding, chaves, índices e consultas críticas.

Quais cuidados tomar antes de exportar um banco MariaDB para PostgreSQL?

Antes da exportação, confirme espaço em disco, versão do Alpine Linux 3.22, acesso root ou sudo, credenciais do MariaDB e permissões no PostgreSQL. Também é essencial congelar alterações ou planejar janela de manutenção para evitar divergência entre o dump exportado e os dados em produção.

MariaDB e PostgreSQL usam os mesmos tipos de dados?

Não. MariaDB e PostgreSQL têm diferenças em tipos, auto incremento, funções, aspas, booleanos, datas, enumerações e comportamento de SQL. Por isso, a migração exige revisão do schema e testes de compatibilidade antes de importar os dados definitivos.

Como validar a integridade após importar dados no PostgreSQL?

Valide a integridade comparando contagens de linhas por tabela, amostras de registros, constraints, índices e resultados de consultas usadas pela aplicação. Também confira encoding, valores nulos, campos de data e relacionamentos para identificar diferenças antes da troca final.

Posso fazer a migração MariaDB para PostgreSQL direto em produção?

Não é recomendado fazer a primeira tentativa diretamente em produção, porque erros de conversão podem interromper a aplicação ou gerar dados inconsistentes. O caminho seguro é executar a migração em ambiente de teste, documentar ajustes e repetir o processo validado em uma janela controlada.

Conclusão

Migrar MariaDB para PostgreSQL no Alpine Linux 3.22 com segurança depende menos de um comando único e mais de um processo verificável: inventário, backup, conversão de schema, carga controlada, validação e cutover com rollback. Ao executar cada etapa em homologação antes da produção, você reduz risco de indisponibilidade e aumenta a confiança na integridade dos dados.

• Documente tabelas, colunas, contagens e consultas críticas antes de exportar qualquer dado.
• Converta o schema manualmente e valide no PostgreSQL antes de importar a base completa.
• Faça o cutover apenas em janela controlada, com backup final e plano de retorno definido.

Leia também

• Checklist para Configurar e Testar Backups Automatizados com Rsync em VPS Linux e Servidor Dedicado
• Otimizar MariaDB 10.11 no Debian 12: tuning essencial
• Otimizar MariaDB 10.11 no Rocky Linux 9: tuning essencial

Precisa de ajuda com migração MariaDB para PostgreSQL?

Se sua aplicação depende de banco de dados e a migração precisa ser feita com cuidado, uma infraestrutura bem preparada ajuda a reduzir riscos durante testes, importação e validação. A AviraHost oferece ambientes de hospedagem para projetos que exigem banco de dados, acesso técnico e previsibilidade operacional.

Conheça as opções de hospedagem da AviraHost