O pg_restore é um utilitário para restaurar um banco de dados do PostgreSQL, a partir de uma cópia de segurança criada pelo pg_dump em um dos formatos não-texto-puro. São submetidos os comandos necessários para reconstruir o banco de dados no estado em que este se encontrava no momento em que foi salvo. Os arquivos de cópia de segurança também permitem ao pg_restore selecionar o que será restaurado, ou mesmo reordenar os itens antes de serem restaurados. Os arquivos de cópia de segurança são projetados para serem portáveis entre arquiteturas diferentes.
O pg_restore pode operar de dois modos: Se o nome do banco de dados for especificado, a cópia de segurança será restaurada diretamente no banco de dados (Os objetos grandes só podem ser restaurados utilizando uma conexão direta com o banco de dados como esta). Senão, será criado um script (escrito em um arquivo ou na saída padrão), contendo os comandos SQL necessários para reconstruir o banco de dados. A saída em script é equivalente ao formato de saída texto-puro do pg_dump. Algumas das opções que controlam a saída são, portanto, análogas às opções do pg_dump.
Obviamente, o pg_restore não pode restaurar informações que não estão presentes no arquivo de cópia de segurança. Por exemplo, se a cópia de segurança for gerada usando a opção "salvar os dados como comandos INSERT", o pg_restore não poderá carregar os dados usando comandos COPY.
O pg_restore aceita os seguintes argumentos de linha de comando.
Especifica o local do arquivo de cópia de segurança a ser restaurado. Se não for especificado, será utilizada a entrada padrão.
Restaura somente os dados, não restaura o esquema (definições dos dados).
Remove (DROP) os objetos do banco de dados antes de criá-los.
Cria o banco de dados antes de restaurá-lo (Quando esta opção é utilizada, o banco de dados especificado na opção -d é usado apenas para submeter o comando CREATE DATABASE inicial. Todos os dados são restaurados no banco de dados cujo nome aparece na cópia de segurança).
Conecta ao banco de dados nome_do_banco_de_dados e restaura diretamente neste banco de dados.
Termina se for encontrado um erro ao enviar os comandos SQL para o banco de dados. O padrão é continuar e mostrar um contador de erros ao término da restauração.
Especifica o arquivo de saída para o script gerado, ou para conter a listagem quando for utilizada com a opção -l. Por padrão a saída padrão.
Especifica o formato do arquivo da cópia de segurança. Não é necessário especificar o formato, porque o pg_restore determina o formato automaticamente. Se for especificado, poderá ser um dos seguintes:
A cópia de segurança é um arquivo tar. Este formato de cópia de segurança permite reordenar e/ou excluir elementos do esquema ao restaurar o banco de dados. Também permite limitar quais dados serão recarregados na restauração.
A cópia de segurança está no formato personalizado do pg_dump. Este é o formato mais flexível, porque permite reordenar a carga dos dados e dos elementos do esquema. Além disso, este formato é comprimido por padrão.
Ignora a verificação da versão do banco de dados.
Restaura apenas a definição do índice especificado.
Lista o conteúdo da cópia de segurança. A saída desta operação pode ser usada com a opção -L para restringir e reordenar os itens a serem restaurados.
Restaura apenas os elementos presentes no arquivo_da_listagem, e na ordem em que aparecem neste arquivo. As linhas podem ser movidas e, também, podem virar comentário colocando ";" no seu início (Veja os exemplos abaixo).
Não gera comandos para definir os donos dos objetos correspondendo aos donos destes objetos no banco de dados de origem. Por padrão, o pg_restore executa o comando ALTER OWNER ou SET SESSION AUTHORIZATION para definir os donos dos elementos criados no esquema. Estes comando não são bem-sucedidos a menos que a conexão inicial com o banco de dados seja feita por um superusuário (ou o mesmo usuário que possui todos os objetos presentes no script). Usando a opção -O, pode ser utilizado qualquer nome de usuário na conexão inicial, e este usuário será o dono de todos objetos criados.
Restaura apenas a função especificada. Tome cuidado para escrever o nome da função e os argumentos exatamente como estes aparecem na tabela de conteúdo da cópia de segurança.
Esta opção está obsoleta, mas ainda é aceita para manter a compatibilidade com as versões anteriores.
Restaura somente o esquema (definições dos dados), não os dados (conteúdo das tabelas). Os valores das seqüências são reiniciados.
Especifica o nome de usuário do superusuário a ser usado para desativar os gatilhos. Somente é relevante quando é usada a opção --disable-triggers.
Restaura apenas a definição e/ou dados da tabela especificada.
Restaura apenas o gatilho especificado.
Especifica o modo verboso.
Impede restaurar os privilégios de acessos (comandos GRANT/REVOKE).
Gera comandos SET SESSION AUTHORIZATION do padrão SQL, em vez dos comandos OWNER TO. Isto torna a cópia de segurança mais compatível com o padrão, mas dependendo da disposição dos objetos na cópia de segurança pode não restaurar de forma apropriada.
Esta opção é relevante apenas quando se restaura somente os dados. Faz com que o pg_restore execute comandos para desativar, temporariamente, os gatilhos das tabelas de destino enquanto os dados são recarregados. Deve ser utilizada quando existem verificações de integridade referencial, ou outros gatilhos nas tabelas, que não se deseja que sejam chamados durante a recarga dos dados.
Atualmente, os comandos emitidos para a opção --disable-triggers devem ser executados por superusuários. Portanto, também deve ser especificado o nome de um superusuário com a opção -S ou, de preferência, executar, com cuidado, o script produzido como um superusuário.
O pg_restore também aceita os seguintes argumentos de linha de comando para os parâmetros de conexão:
Especifica o nome de hospedeiro da máquina onde o servidor de banco de dados está executando. Se o nome iniciar por barra (/), será utilizado como o diretório do soquete do domínio Unix. O padrão é obter o nome a partir da variável de ambiente PGHOST, se esta estiver definida, senão tentar uma conexão pelo soquete do domínio Unix.
Especifica a porta TCP, ou a extensão do arquivo de soquete do domínio Unix local, onde o servidor está atendendo as conexões. O padrão é obter o valor a partir da variável de ambiente PGPORT, se esta estiver definida, senão usar o valor padrão compilado.
Conectar como o usuário especificado.
Força a solicitação da senha, o que deve acontecer automaticamente quando o servidor requer autenticação por senha.
Quando é especificada a conexão direta com o banco de dados usando a opção -d, o pg_restore executa internamente comandos SQL. Se acontecerem problemas ao executar o pg_restore, deve-se ter certeza que é possível selecionar informações no banco de dados utilizando, por exemplo, o utilitário psql.
Se o agrupamento de bancos de dados tiver alguma adição local ao banco de dados template1, deve-se ter o cuidado de restaurar a saída do pg_restore em um banco de dados totalmente vazio; senão, podem acontecer erros devido à duplicidade de definição dos objetos adicionados. Para criar um banco de dados vazio, sem nenhuma adição local, deve-se fazê-lo partir de template0, e não de template1 como, por exemplo:
CREATE DATABASE foo WITH TEMPLATE template0;
As limitações do pg_restore estão descritas abaixo.
Ao restaurar os dados em uma tabela pré-existente utilizando a opção --disable-triggers, o pg_restore emite comandos para desativar os gatilhos das tabelas do usuário antes de inserir os dados, e comandos para reativar os gatilhos após os dados serem inseridos. Se a restauração for interrompida antes do fim, os catálogos do sistema poderão ser deixados em um estado errado.
O pg_restore não restaura objetos grandes para uma única tabela. Se a cópia de segurança contiver objetos grandes, então todos os objetos grandes serão restaurados.
Consulte também a documentação do pg_dump para obter os detalhes de suas limitações.
Uma vez restaurado, é aconselhável executar o comando ANALYZE em todas as tabelas restauradas para que o otimizador possua estatísticas úteis.
Para gerar uma cópia de segurança do banco de dados meu_bd, que contém objetos grandes, em um arquivo tar:
$ pg_dump -Ft -b meu_bd > db.tar
Para restaurar este banco de dados (com os objetos grandes) no banco de dados chamado novo_bd:
$ pg_restore -d novo_bd db.tar
Para reordenar os itens do banco de dados, primeiro é necessário criar um arquivo contendo a tabela de conteúdo (índice) da cópia de segurança:
$ pg_restore -l copia_de_seguranca.arquivo > copia_de_seguranca.list
O arquivo de listagem consiste de um cabeçalho e uma linha para cada item como, por exemplo,
; ; Archive created at Fri Jul 28 22:28:36 2000 ; dbname: birds ; TOC Entries: 74 ; Compression: 0 ; Dump Version: 1.4-0 ; Format: CUSTOM ; ; ; Selected TOC Entries: ; 2; 145344 TABLE species postgres 3; 145344 ACL species 4; 145359 TABLE nt_header postgres 5; 145359 ACL nt_header 6; 145402 TABLE species_records postgres 7; 145402 ACL species_records 8; 145416 TABLE ss_old postgres 9; 145416 ACL ss_old 10; 145433 TABLE map_resolutions postgres 11; 145433 ACL map_resolutions 12; 145443 TABLE hs_old postgres 13; 145443 ACL hs_old
No início da linha ponto-e-vírgula inicia um comentário, e o número refere-se ao identificador interno de arquivamento atribuído a cada item.
As linhas do arquivo podem ser transformadas em comentário, excluídas e reordenadas. Por exemplo, poderia ser usado
10; 145433 TABLE map_resolutions postgres ;2; 145344 TABLE species postgres ;4; 145359 TABLE nt_header postgres 6; 145402 TABLE species_records postgres ;8; 145416 TABLE ss_old postgres
como entrada do pg_restore, e somente restauraria os itens 10 e 6, nesta ordem.
$ pg_restore -L copia_de_seguranca.list copia_de_seguranca.arquivo
