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. 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).
Restaura apenas os objetos que estão no esquema especificado. Pode ser combinado com a opção -t para restaurar apenas uma determinada tabela.
Não gera comandos para definir o dono dos objetos correspondendo ao banco de dados original. Por padrão, o pg_restore emite os comandos ALTER OWNER ou SET SESSION AUTHORIZATION para definir o dono dos elementos criados no esquema. Estes comandos não serã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). Com 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 os objetos criados.
Restaura apenas a função especificada. Deve ser tomado o cuidado de escrever o nome da função e os argumentos exatamente como aparecem na tabela de conteúdo do arquivo de 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 correntes da seqüência também não são restaurados (Não confunda com a opção --schema, que utiliza a palavra "esquema" com um significado diferente).
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).
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 o pg_restore como um superusuário do PostgreSQL.
Gera comandos SET SESSION AUTHORIZATION do padrão SQL em vez dos comandos ALTER OWNER para determinar o dono do objeto. 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.
Por padrão, os dados da tabela são restaurados mesmo que o comando de criação da tabela não tenha sido bem-sucedido (por exemplo, porque a tabela já existe). Com esta opção, os dados da tabela são saltados. Este comportamento é útil quando o banco de dados de destino pode já conter os dados desejados para a tabela. Por exemplo, as tabelas auxiliares para as extensões do PostgreSQL, como o PostGIS, podem já estar carregadas no banco de dados de destino; especificar esta opção impede que sejam carregados na tabela dados duplicados ou obsoletos.
Esta opção somente é efetiva ao restaurar diretamente no banco de dados, e não quando é produzida uma saída de script SQL.
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.
Executar a restauração como uma única transação (ou seja, envolver os comandos emitidos por BEGIN/COMMIT). Isto garante que todos os comandos irão terminar bem-sucedidos, ou não será aplicada nenhuma alteração. Esta opção implica em --exit-on-error.
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.
Assumindo que tenha sido salvo um banco de dados chamado meu_bd em um arquivo de cópia de segurança no formato personalizado:
$ pg_dump -Fc meu_bd > db.dump
Para remover o banco de dados e recriá-lo a partir da cópia de segurança:
$ dropdb meu_bd $ pg_restore -C -d postgres db.dump
O banco de dados especificado na chave -d pode ser qualquer banco de dados existente no agrupamento; o pg_restore somente utiliza este banco de dados para emitir o comando CREATE DATABASE para meu_bd. Com a chave -C, os dados são sempre restaurados no banco de dados cujo nome aparece no arquivo de cópia de segurança.
Para recarregar a cópia de segurança em um banco de dados novo chamado bd_novo:
$ createdb -T template0 bd_novo $ pg_restore -d bd_novo db.dump
Deve ser observado que não foi utilizada a chave -C, e sim conectado diretamente ao banco de dados a ser restaurado. Também deve ser observado que o novo banco de dados foi clonado a partir de template0 e não de template1, para garantir que esteja inicialmente vazio.
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 db.dump > db.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: meu_bd ; 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 db.list db.dump
