# Instruções de migração MySQL → PostgreSQL ### Introdução {% hint style="warning" %} **IMPORTANTE!** SE a sua versão do AI Server for igual ou inferior a 2.0.0, então na sua versão estão sendo usados MySQL e PostgreSQL 16 simultaneamente. Na nova versão 2.1.0+ é utilizado apenas PostgreSQL 17. {% endhint %} Você precisa realizar a migração do MySQL para o PostgreSQL, bem como migrar os dados da versão 16 do PostgreSQL para a versão 17. Este guia descreve o processo de migração do banco de dados Sherpa AI Server do MySQL para o PostgreSQL. A migração inclui a transferência de dados, atualização de configurações e transição para um novo sistema de gerenciamento de banco de dados. {% hint style="info" %} **ATENÇÃO!** Se você tem a opção de ABANDONAR OS DADOS (SE NÃO FOREM NECESSÁRIOS), recomendamos que, em vez de seguir este guia, você acesse as instruções de instalação do zero: {% endhint %} {% embed url="" %} ### Requisitos do sistema #### Requisitos mínimos para migração: * **Espaço livre em disco**: mínimo 2x o tamanho do banco de dados (para dados de origem + migração) * **Memória RAM**: mínimo 4 GB de RAM para pgloader * **Docker**: versão 20.10+ com suporte a Docker Compose * **Conexão de rede**: conexão estável com os bancos de dados #### Verificações preliminares Antes de iniciar a migração, execute as seguintes verificações: ```bash # Verifique o espaço disponível em disco df -h # Verifique a memória RAM disponível free -h # Verifique o status do Docker docker --version docker compose version # Verifique a disponibilidade dos bancos de dados docker ps | grep -E "(mysql|postgres)" ```
💡 Comentários sobre as verificações **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
### Preparação para a migração #### Download dos arquivos necessários Se o ambiente estiver fechado, você precisará baixar antecipadamente os ARQUIVOS PARA INSTALAÇÃO e, além disso, os seguintes arquivos: ```bash curl -fSL -OJ https://sherparpa.ru/downloads/private/SherpaAIServer/pgloader_image.tar curl -fSL -OJ https://sherparpa.ru/downloads/private/SherpaAIServer/alpine_image.tar ```
💡 Comentários sobre o download dos arquivos **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
Crie o diretório `/opt/SherpaAIServerNew` e coloque nele todos os arquivos e ARQUIVOS DA INSTRUÇÃO DE INSTALAÇÃO: ```bash # Crie um novo diretório para a migração sudo mkdir -p /opt/SherpaAIServerNew # Mova os arquivos baixados para o novo diretório (e os arquivos da preparação para download) sudo mv pgloader_image.tar /opt/SherpaAIServerNew/ sudo mv alpine_image.tar /opt/SherpaAIServerNew/ ```
💡 Comentários sobre a preparação do diretório **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
**O que está sendo baixado:** * `pgloader_image.tar` - imagem Docker com pgloader e ferramentas necessárias * `alpine_image.tar` - imagem leve do Alpine Linux para trabalhar com volumes (não afeta seu sistema operacional atual) #### Parando serviços 1. **Parando contêineres além dos bancos de dados:** ```bash # vá para o diretório antigo cd /opt/SherpaAIServer/ docker compose stop orchestrator embed nginx vllm docker-compose stop orchestrator embed nginx vllm # vá para o novo diretório cd /opt/SherpaAIServerNew/ ```
💡 Comentários sobre a parada dos serviços **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
{% hint style="info" %} **Por que paramos os serviços:** Durante a migração, é necessário excluir quaisquer alterações no banco de dados para garantir a consistência dos dados. {% endhint %} {% hint style="info" %} **Nota:** Não é necessário remover os contêineres, apenas pará-los. Devem permanecer `pgembeding` e `orchestrator-db`. {% endhint %} #### Criação de backups **Definindo nomes de volumes:** Primeiro, encontre os nomes corretos dos volumes em seu sistema: ```bash docker volume list ```
💡 Comentários sobre a definição de volumes **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
Exemplo de saída: ``` DRIVER VOLUME NAME local sherpaaiserver_orchestrator-mysql-data local sherpaaiserver_pgdata local sherpaaiserver_storage ``` **Criando backups de volume:** Substitua os nomes dos volumes pelos atuais da sua lista: ```bash # Backup dos dados do MySQL (substitua VOLUME_NAME pelo nome real) docker run --rm -v VOLUME_NAME:/data -v $(pwd)/backup_mysql:/backup pgembeding tar czf /backup/mysql_backup.tar.gz -C /data . # Backup dos dados do PostgreSQL (se existirem) (substitua VOLUME_NAME pelo nome real do postgres) docker run --rm -v VOLUME_NAME:/data -v $(pwd)/backup_pg:/backup pgembeding tar czf /backup/pg_backup.tar.gz -C /data . ```
💡 Comentários sobre a criação de backups **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
**Exemplos com nomes específicos:** Para um projeto na pasta `SherpaAIServer`: ```bash docker run --rm -v sherpaaiserver_orchestrator-mysql-data:/data -v $(pwd)/backup_mysql:/backup pgembeding tar czf /backup/mysql_backup.tar.gz -C /data . docker run --rm -v sherpaaiserver_pgdata:/data -v $(pwd)/backup_pg:/backup pgembeding tar czf /backup/pg_backup.tar.gz -C /data . ```
💡 Exemplo para Sherpa AI Server **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`
Para o projeto na pasta `myproject`: ```bash docker run --rm -v myproject_orchestrator-mysql-data:/data -v $(pwd)/backup_mysql:/backup pgembeding tar czf /backup/mysql_backup.tar.gz -C /data . docker run --rm -v myproject_pgdata:/data -v $(pwd)/backup_pg:/backup pgembeding tar czf /backup/pg_backup.tar.gz -C /data . ```
💡 Exemplo para myproject **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
💡 O que essas comandos fazem * 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`
**Verificação dos backups criados:** ```bash # Verifique o tamanho dos arquivos de backup ls -lh backup_mysql/ backup_pg/ # Verifique o conteúdo dos arquivos de backup tar -tzf backup_mysql/mysql_backup.tar.gz | head -20 ```
💡 Comentários sobre a verificação dos backups **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
### Lógica principal da migração #### Descompactação e preparação das ferramentas 1. **Descompactar os arquivos do cliente:** ```bash tar -xvzf "$(ls client_files_*.tgz | sort -V | tail -n 1)" ```
💡 Comentários sobre a descompactação **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
2. **Mudar para o diretório pgloader:** ```bash cd pgloader ```
💡 Comentários sobre a mudança para o diretório **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
3. **Carregar a imagem Docker do pgloader:** ```bash ./load_pgloader.sh ```
💡 Comentários sobre o carregamento da imagem **./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
4. **Construir o contêiner para migração:** ```bash ./run.sh build ```
💡 Comentários sobre a construção do contêiner **./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
#### Configuração da configuração de migração **Criar o arquivo `.env` com os parâmetros de conexão:** Todas as senhas podem ser encontradas no arquivo `oais/backend/config/config.ini`. ```bash cp .env.template .env nano .env # URI para o banco de dados MySQL de origem MIGRATE_MYSQL="mysql://user:pass@host:port/db" # URI para o banco de dados PostgreSQL de destino MIGRATE_PG="postgres://user:pass@host:port/db" # Parâmetros para criar o dump (opcional) DUMP_PATH="/path/para/o/dump" DUMP_URI="mysql://user:pass@host/db" # Parâmetros para restauração (opcional) RESTORE_URI="postgres://user:pass@host/db" RESTORE_PATH="/path/para/o/dump.sql" ```
💡 Comentários sobre as variáveis de ambiente **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
**Exemplo de configuração funcional:** ```env # Para o banco de dados MySQL DUMP_URI="mysql://root:pass@91.206.149.183:3306/orchestrator" MIGRATE_MYSQL="mysql://root:pass@91.206.149.183:3306/orchestrator" # Para o banco de dados PostgreSQL MIGRATE_PG="postgres://postgres:pass@91.206.149.183:5432/postgres" ```
💡 Exemplo de configuração **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
> **Importante:** Certifique-se de que as portas e hosts estão acessíveis a partir do contêiner Docker. #### Execução da migração **Execução de teste (recomendada)** ```bash ./run.sh dry-run ```
💡 Comentários sobre a execução de teste **./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
**Migração principal** ```bash ./run.sh migrate ```
💡 Comentários sobre a migração principal **./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
**Opções de migração:** * `--force` - executar a migração mesmo que o esquema já exista * `--build` - reconstruir o contêiner antes da execução * `--rmi` - remover a imagem após a conclusão {% hint style="info" %} **Tempo de execução:** Depende do tamanho do banco de dados. Para bancos de até 10 GB - de 30 minutos a várias horas. Para bancos maiores - pode levar várias horas ou dias. {% endhint %} #### Limpeza após a migração ```bash # Remover a imagem Docker do pgloader (opcional) ./run.sh rmi # Voltar para o diretório raiz do projeto cd .. ```
💡 Comentários sobre a limpeza **./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
### Copiando dados para novos volumes Após a migração bem-sucedida do banco de dados, pode ser necessário transferir o armazenamento de arquivos entre os volumes Docker. #### Carregar a imagem Alpine ```bash docker load -i alpine_image.tar ```
💡 Comentários sobre o carregamento do Alpine **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
#### Criando um novo volume ```bash docker volume create aiserver-storage ```
💡 Comentários sobre a criação do volume **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.)
#### Definindo volumes atuais **Encontrar nomes dos volumes utilizados:** ```bash docker volume list ```
💡 Redefinindo volumes **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
Exemplo de saída (nomes dependem do nome da pasta do projeto): ``` DRIVER VOLUME NAME local sherpaaiserver_orchestrator-mysql-data local sherpaaiserver_pgdata local sherpaaiserver_storage ``` Ou, se a pasta do projeto tiver um nome diferente (por exemplo, `myproject`): ``` DRIVER VOLUME NAME local myproject_orchestrator-mysql-data local myproject_pgdata local myproject_storage ``` #### Transferindo dados entre volumes **Definir a fonte de dados:** Na linha de comando abaixo, substitua `STORAGE_DATA` pelo nome do seu volume atual para armazenamento de dados (por exemplo, `sherpaaiserver_storage`): ```bash docker run --rm \ -v STORAGE_DATA:/from \ -v aiserver-storage:/to \ alpine ash -c "cp -av /from/. /to/" ```
💡 Comentários sobre a transferência de dados **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`
**Verificando o sucesso da cópia:** ```bash # Verificar o conteúdo do novo volume docker run --rm -v aiserver-storage:/data alpine ls -la /data # Comparar tamanhos (aproximados) docker run --rm -v STORAGE_DATA:/data alpine du -sh /data docker run --rm -v aiserver-storage:/data alpine du -sh /data ```
💡 Comentários sobre a verificação da cópia **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
### Migração do PostgreSQL 16 para a versão 17 #### Preparação para a atualização da versão do PostgreSQL **Ações preliminares:** 1. **Deixar o antigo banco de dados em execução** - o contêiner `pgembeding` deve continuar funcionando 2. **Descompactar os novos arquivos do cliente** - o arquivo deve conter o `docker-compose.yml` e o `.env` atualizados 3. **Transferir a configuração** - copiar os parâmetros de conexão da versão antiga `/opt/SherpaAIServer/oais/backend/config/config.ini` para o novo `.env` 4. **Alterar a porta** - definir temporariamente a porta 5433 para o novo PostgreSQL, para evitar conflitos #### Descompactação do arquivo com arquivos do cliente ```bash # Encontre e descompacte o arquivo (a versão mais recente é escolhida automaticamente) tar -xvzf "$(ls client_files_*.tgz | sort -V | tail -n 1)" ```
💡 O que este comando faz * `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.
#### Preparação dos scripts para execução ```bash # Acesse o diretório com os scripts cd sh_scripts/ # Torne todos os scripts executáveis chmod +x *.sh # Volte para o diretório raiz do projeto cd .. ```
💡 O que esses comandos fazem * `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
#### Estrutura do arquivo descompactado: Após a descompactação, você deve ver os seguintes arquivos e diretórios: * `sh_scripts/` - diretório com scripts de instalação * `download_all_latest_docker_images.sh` - script para baixar imagens Docker * `load_all_docker_images.sh` - script para carregar imagens no Docker * `extract_models.sh` - script para descompactar modelos de IA * `extract_llama.sh` - script para descompactar modelos LLM * `docker-compose.yml` - configuração do Docker Compose para instalação do cliente * `.env` - arquivo com variáveis de ambiente para configuração do sistema #### Carregamento de imagens Docker ```bash # Execute o script de carregamento de imagens Docker sudo ./sh_scripts/load_all_docker_images.sh ```
💡 O que o script faz 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
#### Descompactação de modelos de IA ```bash # Execute o script de descompactação dos modelos principais sudo ./sh_scripts/extract_models.sh ```
💡 O que o script faz 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
```bash # Execute o script de descompactação do modelo LLM sudo ./sh_scripts/extract_llama.sh ```
💡 O que o script faz 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
#### Estrutura de diretórios após a descompactação (aproximada):\`\`\` ./whisper/ └── models/ ├── base.pt └── ... ./bge\_reranker/ └── models/ └── bge-reranker-large/ ├── config.json ├── model.bin └── ... ./embed-server/app/ └── model-store/ └── sentence-transformers/ └── paraphrase-multilingual-MiniLM-L12-v2/ ├── config.json ├── pytorch\_model.bin └── ... ./llm-server/models/ ├── meta-llama/ │ └── Meta-Llama-3-8B-Instruct/ │ ├── config.json │ ├── model-00001-of-00004.safetensors │ ├── model-00002-of-00004.safetensors │ └── ... └── tokenizer.json ```` #### Execução de uma nova versão do PostgreSQL ```bash docker compose up -d ````
💡 Comentários sobre a execução de uma nova versã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
**Monitoramento da execução:** ```bash # Acompanhar os logs de inicialização docker logs aiserver # Verificar o status dos contêineres docker ps | grep aiserver ```
💡 Comentários sobre o monitoramento **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
#### Parar serviços para transferência de dados **Parar todos os serviços, exceto o novo banco de dados:** ```bash docker-compose stop aiserver aiserver-code_interpreter aiserver-llm-server aiserver-embed aiserver-whisper aiserver-bge_reranker docker compose stop aiserver aiserver-code_interpreter aiserver-llm-server aiserver-embed aiserver-whisper aiserver-bge_reranker ```
💡 Comentários sobre a parada dos serviços **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
#### Transferência de dados entre versões **Executar a sequência de comandos para transferência de dados:** ```bash # 1. Criar um dump do banco de dados antigo docker exec -t postgres pg_dump -U postgres -d postgres -Fc -f /tmp/postgres.dump && \ # 2. Copiar o dump para o host docker cp postgres:/tmp/postgres.dump ./postgres.dump && \ # 3. Deletar o banco de dados antigo no novo contêiner docker exec -it aiserver-pg psql -U postgres -d template1 -c "DROP DATABASE IF EXISTS postgres;" && \ # 4. Criar um novo banco de dados docker exec -it aiserver-pg psql -U postgres -d template1 -c "CREATE DATABASE postgres;" && \ # 5. Criar as extensões necessárias docker exec -it aiserver-pg psql -U postgres -d postgres -c "CREATE EXTENSION IF NOT EXISTS embedding;" && \ docker exec -it aiserver-pg psql -U postgres -d postgres -c "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";" && \ # 6. Copiar o dump para o novo contêiner docker cp ./postgres.dump aiserver-pg:/tmp/postgres.dump && \ # 7. Restaurar os dados docker exec -t aiserver-pg pg_restore -U postgres -d postgres /tmp/postgres.dump ```
💡 Comentários sobre a transferência entre versões do PostgreSQL **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
### Validação dos resultados da migração #### Verificação da correção da transferência de dados **Verificações básicas:** ```bash # Conectar ao novo banco de dados docker exec -it aiserver-pg psql -U postgres -d postgres # Verificar o número de tabelas \dt orchestrator.* # Verificar o número de registros nas tabelas principais SELECT schemaname, tablename, n_tup_ins AS rows FROM pg_stat_user_tables WHERE schemaname = 'orchestrator' ORDER BY n_tup_ins DESC; # Verificar a presença de extensões \dx # Sair do psql \q ```
💡 Comentários sobre as verificações básicas **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
#### Testando a funcionalidade 1. **Iniciar os principais serviços do Sherpa AI Server** 2. **Executar consultas de teste na API** 3. **Verificar o funcionamento da interface web** 4. **Executar operações básicas com dados** ### Diagnóstico e resolução de problemas #### Erros comuns e soluções **Se ocorrerem erros de migração, entre em contato com o suporte técnico, enquanto isso você pode voltar para o diretório antigo /opt/SherpaAIServer e iniciar com as configurações anteriores do Sherpa AI Server** **"Heap exhausted" ou falta de memória** ``` Solução: Aumentar o limite de memória para pgloader export SBCL_DYNAMIC_SPACE_SIZE=8192 ``` **Erro de conexão ao banco de dados** ``` Verificações: - Verificar a disponibilidade das portas: telnet host port - Verificar a correção das credenciais - Verificar a acessibilidade da rede dos contêineres ``` **Violação da integridade dos dados** ``` Ações: 1. Verificar os logs do pgloader: cat migrate.log 2. Comparar o número de registros no banco de dados de origem e no de destino 3. Verificar a presença de todas as tabelas e índices ``` **Interrupção da migração** ``` Ações: - Não reiniciar a migração - Contatar o suporte técnico com os logs - Fornecer: migrate.log, configuração .env, tamanho do banco de dados ```
💡 Comentários sobre o monitoramento da migração **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 ```**watch * 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
### 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. ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sherparpa.ru/pt/obnovleniya/obnovleniya-sherpa-ai-server/versiya-2.2.0/instrukciya-po-migracii-mysql-postgresql.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.