Executar script SQL

O script não para no primeiro erro e não há desfazer automático: entenda o estado parcial, os avisos toleráveis e os problemas de codificação.

A opção Roda Script executa um arquivo .sql no banco informado.

Para que serve

Use quando precisar aplicar comandos SQL prontos em um banco: ajustes, correções pontuais ou criação de objetos.

Para escrever e testar SQL interativamente, o lugar certo é o QueryConsole. O Roda Script é para aplicar um arquivo que já está pronto e revisado.

O comportamento mais importante de entender

Por isso, nunca assuma que “deu erro” significa “nada foi alterado”. Significa o contrário: é preciso descobrir o que já entrou antes de rodar o arquivo de novo.

Antes de começar

• Confirme que o arquivo .sql é o correto e já foi revisado.
• Confirme host, porta e nome do banco de destino.
• Tenha backup do banco se o script alterar dados existentes.
• Prefira rodar primeiro em um banco de teste quando o script for novo.

Como fazer

1. Abra Restaurar o Banco de Dados.
2. Preencha Host, Porta e Banco de Dados.
3. Marque Roda Script. O botão muda para Rodar Script e a opção de criar banco em branco fica desativada.
4. Clique em Selecionar Arquivo e escolha o arquivo.
5. Clique em Rodar Script.
6. Acompanhe as mensagens na tela até o fim.

Somente arquivos .sql aparecem na seleção. Um script dentro de .zip ou de outro formato precisa ser extraído antes.

O que acontece durante

O RestauraDB conecta no banco informado e aplica o arquivo comando a comando, mostrando as mensagens na área de log da tela enquanto executa. Não há pré-visualização do conteúdo do arquivo — ele é aplicado como está.

A execução pode ser cancelada. Como não há desfazer, um cancelamento no meio também deixa estado parcial.

Como ler o resultado

Esta é a parte que mais gera confusão. Existem três desfechos diferentes:

Avisos toleráveis x erros reais

Nem toda linha vermelha é problema. O RestauraDB separa dois tipos:

• Conflitos esperados de atualização — “objeto já existe”, “objeto não existe”, duplicidade. São comuns em scripts de atualização que rodam mais de uma vez e normalmente podem ser ignorados.
• Erros de verdade — sintaxe inválida, coluna ausente, violação de regra do banco. Esses indicam que aquele comando não foi aplicado.

Se o log só tem conflitos esperados, o script provavelmente cumpriu o objetivo. Se há erros de verdade, trate como execução parcial.

Codificação: quando os acentos atrapalham

Arquivos .sql gerados em outra máquina ou por outro sistema podem estar gravados com uma codificação diferente da que o banco espera. O RestauraDB não converte o arquivo automaticamente.

Sinais de que o problema é esse:

• o log mostra caracteres estranhos no lugar de acentos;
• aparece erro mencionando sequência de bytes inválida;
• os dados entram no banco com acentuação errada.

O que fazer:

1. Abra o arquivo em um editor de texto apenas para conferir se o conteúdo está legível.
2. Se estiver, salve uma cópia em UTF-8.
3. Rode a cópia.

Se o texto já aparece corrompido no próprio editor, o problema veio da origem: peça o arquivo novamente a quem o gerou.

O que pode dar errado

Como identificar que o script não foi concluído

• a mensagem final fala em falha, e não em conclusão;
• o log termina no meio, sem chegar aos últimos comandos do arquivo;
• a mensagem menciona avisos ou pendências e o log tem erros de verdade.

Em qualquer um desses casos, considere que parte do script foi aplicada.

Antes de rodar de novo

Rodar o mesmo arquivo uma segunda vez sem pensar pode duplicar dados ou gerar novos erros, porque parte dos comandos já foi aplicada.

1. Leia o log e identifique onde parou.
2. Confira no banco o que já entrou — o QueryConsole serve bem para isso.
3. Corrija o arquivo, removendo o que já foi aplicado, ou peça a quem gerou o script uma versão que possa rodar mais de uma vez com segurança.
4. Só então execute novamente.

Se o banco puder ser descartado, muitas vezes é mais simples restaurar o backup e rodar o script corrigido do zero.

Quando usar restauração em vez de script

Se o arquivo é um backup completo — e não um conjunto de ajustes —, use Restaurar um banco. A restauração trata o banco de destino de forma controlada; o Roda Script apenas aplica comandos.

Quando procurar suporte

Procure suporte quando:

• o script parou no meio e você não sabe o que já foi aplicado;
• o log mostra erros que você não consegue interpretar;
• o script era para corrigir um problema e o problema piorou;
• o mesmo arquivo falha em bancos diferentes.

Informe o código exibido, o nome do banco e a mensagem final da tela. Não envie senhas.

Artigos relacionados

• Abrir o QueryConsole
• Restaurar um banco
• Criar um banco em branco
• RDB-REST-008 — Falha ao executar o script
• RDB-REST-009 — Não foi possível ler o arquivo
• RDB-PG-001 — PostgreSQL não encontrado