Instruções de migração MySQL → PostgreSQL#

df -h - mostra o uso do espaço em disco em um formato legível

• Verifique se há pelo menos o dobro do espaço livre em relação ao tamanho do seu banco de dados

free -h - mostra informações sobre a memória RAM

• O pgloader requer no mínimo 4 GB de RAM
• Em caso de falta de memória, a migração pode falhar com o erro "Heap exhausted"

docker --version - verifica a versão do Docker

• É necessário Docker 20.10+ para o funcionamento correto de todas as funções

docker compose version - verifica a versão do Docker Compose

• Certifique-se de que o compose suporta a sintaxe moderna

docker ps - mostra os contêineres em execução

• Os contêineres mysql/postgres devem estar visíveis para acesso aos dados

curl -fSL -OJ - baixa arquivos do servidor

• -f - encerra silenciosamente em caso de erros do servidor
• -S - mostra erros mesmo ao usar -f
• -L - segue redirecionamentos
• -O - salva o arquivo com o nome do servidor
• -J - usa o nome do arquivo fornecido pelo servidor

pgloader_image.tar - imagem Docker com a ferramenta pgloader para transferência de dados alpine_image.tar - imagem leve do Linux para operações com arquivos

sudo mkdir -p - cria um diretório com pastas pai

• -p evita erro se o diretório já existir

sudo mv - move arquivos para o novo diretório

• Mover para /opt/SherpaAIServerNew isola os arquivos de migração da instalação atual

docker compose stop - para os serviços especificados sem removê-los

• orchestrator - serviço principal de orquestração
• embed - serviço para trabalhar com embeddings
• nginx - servidor web e proxy
• vllm - serviço de modelo de linguagem

Duas comandos - ambas as versões de sintaxe foram executadas para compatibilidade Serviços restantes - pgembeding (PostgreSQL com embeddings) e orchestrator-db (MySQL) devem continuar funcionando para acesso aos dados

docker volume list - mostra todos os volumes Docker no sistema

• DRIVER - tipo de driver (geralmente local)
• VOLUME NAME - nome único do volume

Prefixo dos nomes - depende do nome da pasta do projeto:

• Para a pasta SherpaAIServer → prefixo sherpaaiserver_
• Para a pasta myproject → prefixo myproject_

Volumes principais:

• *orchestrator-mysql-data - dados do banco de dados MySQL
• *pgdata - dados do banco de dados PostgreSQL
• *storage - armazenamento de arquivos

docker run --rm - executa um contêiner e o remove automaticamente após a execução

• --rm evita o acúmulo de contêineres parados

Montando volumes:

• -v VOLUME_NAME:/data - monta o volume Docker no contêiner
• -v $(pwd)/backup_mysql:/backup - monta a pasta local para salvar o arquivo

tar czf - cria um arquivo compactado

• c - criar arquivo
• z - comprimir usando gzip
• f - especificar o nome do arquivo
• -C /data . - muda o diretório para /data antes da compactação

pgembeding - usa a imagem existente do PostgreSQL com ferramentas

Primeiro volume: sherpaaiserver_orchestrator-mysql-data

• Contém os dados do banco de dados MySQL do orquestrador
• O arquivo é salvo em backup_mysql/mysql_backup.tar.gz

Segundo volume: sherpaaiserver_pgdata

• Contém dados do banco de dados PostgreSQL (se houver)
• O arquivo de backup é salvo em backup_pg/pg_backup.tar.gz

Primeiro volume: myproject_orchestrator-mysql-data

• De forma semelhante, mas com o prefixo myproject_
• Use o nome real da pasta do seu projeto

Segundo volume: myproject_pgdata

• Dados do PostgreSQL com o prefixo correspondente

• Criam arquivos de backup compactados de todos os dados do volume Docker
• Os backups são salvos nas diretórios locais backup_mysql e backup_pg

ls -lh - mostra informações detalhadas sobre os arquivos

• -l - formato longo
• -h - tamanhos em formato legível
• Verifique se os arquivos de backup têm um tamanho razoável

tar -tzf - mostra o conteúdo do arquivo sem descompactar

• -t - lista o conteúdo
• -z - descompactar usando gzip
• -f - especificar o nome do arquivo
• | head -20 - mostra os primeiros 20 arquivos

Recomendação: Certifique-se de que os arquivos de backup não estão vazios e contêm os arquivos de banco de dados esperados

tar -xvzf - descompacta o arquivo

• -x - extrair
• -v - saída detalhada
• -z - descompactar usando gzip
• -f - especificar o nome do arquivo

Subcomando para seleção de arquivo:

• ls client_files_*.tgz - encontra todos os arquivos de backup do cliente
• sort -V - ordena por versão (1.0, 1.1, 2.0, etc.)
• tail -n 1 - pega o último (o mais recente) arquivo

Resultado: Uma pasta pgloader é criada com as ferramentas de migração

cd pgloader - muda para a pasta com as ferramentas de migração

• Todos os comandos subsequentes são executados a partir deste diretório
• Contém scripts e configurações para o pgloader

./load_pgloader.sh - script para carregar a imagem Docker

• Importa pgloader_image.tar para o daemon Docker local
• Após a execução, a imagem fica disponível como pgloader:latest
• Pode levar alguns minutos, dependendo do tamanho da imagem

./run.sh build - constrói o contêiner Docker para migração

• Cria um contêiner baseado na imagem pgloader carregada
• Configura todas as dependências e ferramentas necessárias
• Após a construção, o contêiner está pronto para executar a migração

MIGRATE_MYSQL - URI de conexão ao banco de dados MySQL de origem

• Formato: mysql://username:password@host:port/database
• Usado pelo pgloader para ler os dados

MIGRATE_PG - URI de conexão ao banco de dados PostgreSQL de destino

• Formato: postgres://username:password@host:port/database
• Deve estar disponível para gravação de dados

DUMP_ / RESTORE_ ** - parâmetros opcionais para criar/restaurar dumps

• Útil para depuração ou migração em etapas

Parâmetros MySQL:

• Host: 91.206.149.183 (servidor externo)
• Porta: 3306 (padrão para MySQL)
• Banco: orchestrator
• Usuário: root (com todas as permissões)

Parâmetros PostgreSQL:

• Host: o mesmo servidor
• Porta: 5432 (padrão para PostgreSQL)
• Banco: postgres (banco de sistema)
• Usuário: postgres (administrador)

Importante: As senhas devem ser retiradas do config.ini existente

./run.sh dry-run - simulação da migração sem alterações

• Conecta-se a ambos os bancos de dados
• Analisa a estrutura e os dados
• Mostra o plano de migração e problemas potenciais
• Não faz alterações no PostgreSQL

Verifica:

• Disponibilidade e correção das conexões
• Compatibilidade dos tipos de dados MySQL → PostgreSQL
• Existência de todas as tabelas e relacionamentos
• Volume esperado de dados para transferência

Recomendação: Sempre execute um dry-run antes da migração real

./run.sh migrate - executa a migração real dos dados

• Cria o esquema orchestrator no PostgreSQL
• Transfere a estrutura das tabelas com conversão de tipos
• Copia todos os dados do MySQL para o PostgreSQL
• Cria índices e restrições de integridade

Etapas de execução:

1. Verificação das conexões e permissões
2. Criação do esquema do banco de dados
3. Migração da estrutura (tabelas, tipos de dados)
4. Transferência de dados com otimização de desempenho
5. Criação de índices e restrições

Importante: O processo pode ser demorado para grandes bancos de dados

./run.sh rmi - remove a imagem Docker do pgloader

• Libera espaço em disco
• Remove imagens e contêineres temporários
• Opcional - pode ser mantido para reutilização

cd .. - volta para o diretório pai

• Sai da pasta pgloader
• Retorna ao diretório raiz do projeto SherpaAIServer

Recomendação: Execute a limpeza apenas após a conclusão e teste bem-sucedido da migração

docker load -i - importa a imagem Docker de um arquivo tar

• -i - lê de um arquivo tar salvo localmente
• Carrega a imagem no daemon Docker local

Alpine Linux - uma distribuição Linux minimalista

• Tamanho da imagem ~5-10 MB (em comparação com Ubuntu ~100+ MB)
• Contém apenas as ferramentas necessárias (cp, ls, tar, etc.)
• Ideal para operações com arquivos em contêineres

Uso: Para copiar dados entre volumes Docker

docker volume create - cria um novo volume Docker nomeado

• aiserver-storage - nome para o novo volume
• O volume é criado vazio e pronto para uso

Características do volume:

• Gerenciado automaticamente pelo Docker
• Disponível para todos os contêineres no host
• Mantido após a reinicialização do daemon Docker
• Suporta operações de snapshot e backup

Finalidade: Armazenamento de arquivos do Sherpa AIServer (downloads, cache, logs, etc.)

docker volume list - verifica novamente a lista de volumes

• Certifique-se de que todos os volumes estão disponíveis
• Verifique a correção dos nomes antes de copiar dados

Importante: Compare com os resultados da primeira verificação

• Certifique-se de que os volumes não foram excluídos acidentalmente
• Verifique a disponibilidade de todos os dados necessários

docker run --rm - executa um contêiner temporário Alpine

• --rm - o contêiner será removido após a execução

Montando volumes:

• -v STORAGE_DATA:/from - o volume de origem é montado em /from
• -v aiserver-storage:/to - o volume de destino é montado em /to

ash -c - executa o comando no shell Alpine

• ash - Almquist shell (leve)
• -c - executar o comando

cp -av /from/. /to/ - copia todos os arquivos

• -a - modo de arquivamento (mantém permissões, proprietários, timestamps)
• -v - saída detalhada
• /from/. - copia o conteúdo, não a própria pasta /from
• /to/ - para o diretório de destino

Exemplo de substituição: STORAGE_DATA → sherpaaiserver_storage

docker run --rm -v aiserver-storage:/data alpine ls -la /data

• Verifica o conteúdo do novo volume
• ls -la mostra todos os arquivos com permissões e tamanhos
• Certifique-se de que os arquivos foram copiados corretamente

docker run --rm -v STORAGE_DATA:/data alpine du -sh /data

• Verifica o tamanho do volume de origem
• du -sh - uso de disco, resumo, formato legível por humanos
• Compara tamanhos para verificar a integridade da cópia

Expectativas:

• O número de arquivos deve coincidir
• Os tamanhos devem ser aproximadamente iguais
• A estrutura de diretórios deve ser idêntica

Se os tamanhos diferirem: Verifique os logs de cópia em busca de erros

• ls client_files_*.tgz - encontra todos os arquivos de arquivo
• sort -V - classifica as versões de forma natural (1.0 < 1.1 < 1.10)
• tail -n 1 - seleciona o arquivo mais recente
• tar -xvzf - descompacta o arquivo com saída do conteúdo

Resultado esperado: Um diretório sh_scripts/ será criado com scripts executáveis e outros arquivos necessários.

• chmod +x *.sh - define permissões de execução para todos os scripts shell
• Isso é necessário para executar os scripts nas próximas etapas da instalação

1. Carrega todas as imagens Docker dos arquivos .tar.gz baixados
2. Importa as imagens no registro Docker local
3. Verifica o sucesso do carregamento

1. Descompacta o modelo Whisper para reconhecimento de fala
2. Descompacta o modelo BGE Reranker para melhorar a busca
3. Descompacta modelos para geração de embeddings
4. Cria os diretórios necessários
5. Verifica o sucesso da descompactação

1. Descompacta o modelo Llama 3 para modelagem de linguagem
2. Remove o prefixo model-store/ dos caminhos dos arquivos
3. Coloca os arquivos diretamente no diretório dos modelos
4. Verifica o conteúdo após a descompactação

docker compose up -d - inicia os serviços em segundo plano

• -d - modo destacado (execução em segundo plano)
• Inicia todos os serviços do docker-compose.yml
• Inclui o PostgreSQL 17 no contêiner aiserver-pg

Importante:

• O banco de dados antigo deve continuar funcionando
• A nova versão é iniciada em outra porta (5433)
• O processo de inicialização pode levar alguns minutos

docker logs aiserver - mostra os logs do contêiner

• Acompanha o processo de inicialização do PostgreSQL
• Procura mensagens de sucesso na inicialização e aplicação de migrações
• Pode ser interrompido com Ctrl+C

docker ps | grep aiserver - verifica o status

• docker ps - mostra os contêineres em execução
• grep aiserver - filtra pelo nome
• Deve mostrar o contêiner aiserver-pg no estado Up

docker compose stop - para os serviços especificados

• Ambas as versões da sintaxe são executadas para compatibilidade
• Para todos os serviços do Sherpa AIServer, exceto o banco de dados

Serviços parados:

• aiserver - servidor web principal
• aiserver-code_interpreter - interpretador de código
• aiserver-llm-server - modelo de linguagem
• aiserver-embed - serviço de embeddings
• aiserver-whisper - serviço de reconhecimento de fala
• aiserver-bge_reranker - serviço de ranqueamento

Resultado: Apenas aiserver-pg (novo PostgreSQL) continua funcionando

Passo 1: Criar um dump do banco de dados antigo

• docker exec -t postgres - executa o comando no contêiner postgres (versão 16)
• pg_dump -U postgres -d postgres -Fc - cria um dump em formato especial
• -Fc - formato especial comprimido (melhor para grandes bancos de dados)
• Salvo em /tmp/postgres.dump dentro do contêiner

Passo 2: Copiar o dump para o host

• docker cp postgres:/tmp/postgres.dump ./postgres.dump
• Transfere o dump do contêiner para o disco local
• Necessário para a transferência entre contêineres

Passo 3: Deletar o banco de dados antigo no novo contêiner

• Conecta-se ao banco de dados do sistema template1
• Deleta o banco de dados existente postgres (se houver)

Passo 4: Criar um novo banco de dados

• Cria um banco de dados postgres limpo no contêiner aiserver-pg

Passo 5: Criar extensões

• embedding - extensão para embeddings vetoriais
• uuid-ossp - geração de UUID (necessário para algumas tabelas)

Passo 6: Copiar o dump para o novo contêiner

• Operação inversa de cópia
• Coloca o dump no contêiner aiserver-pg

Passo 7: Restaurar os dados

• pg_restore - restaura a partir do dump em formato especial
• -t - aloca TTY para progresso
• Cria automaticamente tabelas, índices e dados

docker exec -it aiserver-pg psql -U postgres -d postgres

• Conecta-se ao PostgreSQL em modo interativo
• -it - terminal interativo
• -U postgres - usuário postgres
• -d postgres - banco de dados postgres

\dt orchestrator.* - mostra todas as tabelas no esquema orchestrator

• \dt - lista de tabelas
• orchestrator.* - filtro pelo esquema

SELECT ... FROM pg_stat_user_tables - estatísticas sobre as tabelas

• n_tup_ins - número de linhas inseridas (número aproximado de registros)
• A ordenação decrescente mostra as maiores tabelas

\dx - mostra as extensões instaladas

• Devem ser visíveis embedding e uuid-ossp

\q - sair do psql

tail -f migrate.log - acompanha os logs em tempo real

• -f - acompanhar (atualiza ao adicionar novas linhas)
• Mostra o progresso da migração do pgloader
• Procura erros ou avisos

docker stats - monitora o uso de recursos pelos contêineres

• Mostra CPU, memória, rede, disco para todos os contêineres
• Útil para rastrear a carga do sistema
• Pode ser interrompido com Ctrl+C

* Conta o número total de registros em todas as tabelas do orchestrator
* `watch` - utilitário para execução periódica de comandos
* `-n 30` - intervalo de 30 segundos

**Uso:** Manter esses comandos em terminais separados durante a migração

</details>

### Conclusão da migração

**Após a execução bem-sucedida de todas as etapas:**

1. **Iniciar todos os serviços do Sherpa AI Server**
2. **Realizar testes finais do sistema**
3. **Remover arquivos temporários e contêineres antigos** (se necessário)

> **Recomendação:** Salve os logs da migração e os arquivos de configuração para referência futura.