O pg_dump é um utilitário para fazer cópia de segurança de um banco de dados do PostgreSQL. São feitas cópias de segurança consistentes, mesmo que o banco de dados esteja sendo utilizado ao mesmo tempo. O pg_dump não bloqueia os outros usuários que estão acessando o banco de dados (leitura ou escrita).
As cópias de segurança podem ser feitas no formato de script, personalizado ou tar. As cópias de segurança no formato de script são arquivos de texto puro, contendo os comandos SQL necessários para reconstruir o banco de dados no estado em que este se encontrava quando foi salvo. Para restaurar a partir destes scripts, deve ser utilizado o psql. Os arquivos de script podem ser utilizados para reconstruir o banco de dados até em outras máquinas com outras arquiteturas; com algumas modificações, até mesmo em outros produtos gerenciadores de banco de dados SQL.
Os formatos personalizado e tar devem ser utilizados com o pg_restore para reconstruir o banco de dados. Estes formatos permitem que o pg_restore selecione o que será restaurado, ou mesmo reordene os itens antes de restaurá-los, e também permitem salvar e restaurar os "objetos grandes", o que não é possível com a cópia de segurança em arquivo de script. Os formatos personalizado e tar foram projetados para serem portáveis entre arquiteturas diferentes.
Quando usado com o formato personalizado ou tar, e combinado com o pg_restore, o pg_dump fornece um mecanismo flexível para cópias de segurança e transferência. O pg_dump pode ser usado para fazer a cópia de segurança de todo o banco de dados e, posteriormente, o pg_restore pode ser usado para examinar a cópia de segurança e/ou selecionar as partes do banco de dados a serem restauradas. O formato de arquivo de saída mais flexível é o "personalizado" (custom, -Fc); permite a seleção e a reordenação de todos os itens da cópia de segurança, e é comprimido por padrão. O formato tar (-Ft) não é comprimido e não permite reordenar os dados ao restaurar, mas por outro lado é bastante flexível; além disso, pode ser manipulado pelas ferramentas padrão do Unix, como o tar.
Ao executar o pg_dump a saída deve ser examinada à procura de advertências (escritas na saída de erro padrão), com atenção especial às limitações mostradas abaixo.
As seguintes opções de linha de comando controlam o conteúdo e o formato da saída:
Especifica o nome do banco de dados a ser salvo. Se não for especificado, será utilizada a variável de ambiente PGDATABASE. Caso esta variável não esteja definida, será utilizado o nome do usuário especificado para a conexão.
Salva somente os dados, não salva o esquema (definições dos dados).
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao chamar o pg_restore.
Inclui os objetos grandes na cópia de segurança. Deve ser selecionado um formato de saída não-texto.
Inclui comandos para remover (DROP) os objetos do banco de dados antes dos comandos para criá-los.
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao chamar o pg_restore.
Inicia a saída por comandos para criar o banco de dados e conectar ao banco de dados criado (Com um script assim não importa em qual banco de dados se está conectado antes de executar o script).
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao chamar o pg_restore.
Salva os dados como comandos INSERT, em vez de COPY. Torna a restauração muito lenta; sua utilização principal é para fazer cópias de segurança que podem ser carregadas em outros bancos de dados que não o PostgreSQL. Deve ser observado que a restauração pode falhar inteiramente se a ordem das colunas tiver sido modificada. A opção -D é mais segura com relação à modificação da ordem das colunas, mas é ainda mais lenta.
Salva os dados como comandos INSERT explicitando os nomes das colunas (INSERT INTO tabela (coluna, ...) VALUES ...). Torna a restauração muito lenta; sua utilização principal é para fazer cópias de segurança que podem ser carregadas em outros bancos de dados que não o PostgreSQL.
Envia a saída para o arquivo especificado. Se for omitido será utilizada a saída padrão.
Seleciona o formato da saída. O formato pode ser um dos seguintes:
Gera um arquivo de script SQL no formato texto-puro (o padrão)
Gera um arquivo tar adequado para servir de entrada para o pg_restore. A utilização deste formato de arquivo permite reordenar e/ou excluir objetos do banco de dados ao fazer a restauração. Também é possível limitar os dados a serem recarregados ao fazer a restauração.
Gera um arquivo personalizado adequado para servir de entrada para o pg_restore. Este é o formato mais flexível, porque permite a reordenação da restauração dos dados, assim como das definições dos objetos. Além disso, este formato é comprimido por padrão.
Ignora a diferença de versão entre o pg_dump e o servidor de banco de dados.
O pg_dump tratar bancos de dados do PostgreSQL com versões anteriores, mas as versões muito antigas não são mais suportadas (atualmente as anteriores a 7.0). Esta opção deve ser utilizada se for necessário desconsiderar a verificação de versão (mas se o pg_dump não for bem-sucedido, não diga que não foi avisado).
Salva apenas o conteúdo do esquema. Se esta opção não for especificada, todos os esquemas no banco de dados especificado (fora os do sistema) serão salvos.
Nota: Neste modo, o pg_dump não tenta salvar os demais objetos de banco de dados que os objetos no esquema selecionado possam depender. Portanto, não existe nenhuma garantia que o resultado de salvar um único esquema possa, por si próprio, ser bem-sucedido quando restaurado em um banco de dados vazio.
Salva os identificadores de objeto (OIDs) de todas as tabelas como parte dos dados. Esta opção deverá ser utilizada se a coluna OID for referenciada por um aplicativo de alguma maneira (por exemplo, em uma restrição de chave estrangeira). Caso contrário, esta opção não deverá ser utilizada.
Não gera comandos para definir o dono dos objetos correspondendo ao banco de dados original. Por padrão, o pg_dump emite os comandos ALTER OWNER ou SET SESSION AUTHORIZATION para definir o dono dos objetos criados no bancos de dados. Estes comandos não serão bem-sucedidos quando o script for executado, a menos que o script seja iniciado por um superusuário (ou o mesmo usuário que possui todos os objetos presentes no script). Para gerar um script que pode ser restaurado por qualquer usuário, mas que tornará este usuário o dono de todos os objetos, deve ser especificada a opção -O.
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao chamar o pg_restore.
Esta opção está obsoleta, mas ainda é aceita para manter compatibilidade com as versões anteriores.
Salva somente as definições dos objetos (esquema), não os dados.
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 (Geralmente é melhor não utilizar esta opção e, em vez disso, executar o script produzido como um superusuário).
Salva somente os dados da tabela. É possível existirem várias tabelas com o mesmo nome em esquemas diferentes; se este for o caso, todas as tabelas correspondentes serão salvas. Deve ser especificado tanto --schema quanto --table para selecionar apenas uma tabela.
Nota: Neste modo, o pg_dump não tenta salvar os demais objetos de banco de dados que a tabela selecionada possa depender. Portanto, não existe nenhuma garantia que o resultado de salvar uma única tabela possa, por si próprio, ser bem-sucedido quando restaurado em um banco de dados vazio.
Especifica o modo verboso, fazendo o pg_dump colocar comentários detalhados sobre os objetos e os tempos de início/fim no arquivo de cópia de segurança, e mensagens de progresso na saída de erro padrão.
Impede salvar os privilégios de acessos (comandos GRANT/REVOKE).
Esta opção desativa a utilização do caractere cifrão ($) para delimitar o corpo da função, obrigando delimitar o corpo da função utilizando a sintaxe para cadeia de caracteres do padrão SQL.
Esta opção somente é relevante ao criar um arquivo de cópia de segurança somente de dados. Esta opção faz o pg_dump incluir 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.
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao chamar o pg_restore.
Gera comandos SET SESSION AUTHORIZATION do padrão SQL em vez dos comandos OWNER TO 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.
Especifica o nível de compressão a ser usado nas cópias de segurança com formatos que suportam compressão (atualmente somente o formato personalizado suporta compressão).
As seguintes opções de linha de comando controlam os parâmetros de conexão com o servidor de banco de dados:
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.
O pg_dump executa internamente comandos SELECT. Se acontecerem problemas ao executar o pg_dump, deve-se ter certeza que é possível selecionar as 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_dump em um banco de dados totalmente vazio; senão, poderão acontecer erros devido a definições duplicadas dos objetos adicionados. Para criar um banco de dados vazio, sem nenhuma adição local, deve-se fazê-lo a partir de template0, e não de template1 como, por exemplo:
CREATE DATABASE foo WITH TEMPLATE template0;
O pg_dump possui algumas poucas limitações:
Ao salvar uma única tabela, ou no formato texto-puro, o pg_dump não trata os objetos grandes. Os objetos grandes devem ser salvos juntamente com todo o banco de dados usando um dos formatos de cópia de segurança não-texto.
Quando é escolhida uma cópia de segurança apenas dos dados e é utilizada a opção --disable-triggers, o pg_dump emite comandos para desativar os gatilhos nas 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.
Os membros de arquivos tar estão limitados a um tamanho inferior a 8 GB (esta limitação é inerente ao formato dos arquivos tar). Portanto, este formato não pode ser utilizado se a representação textual de uma tabela exceder este tamanho. O tamanho total do arquivo tar, e dos outros formatos de saída, não possui limitação exceto, talvez, pelo sistema operacional.
Os arquivos de cópia de segurança produzidos pelo pg_dump não contêm as estatísticas utilizadas pelo otimizador para fazer as decisões de planejamento dos comandos. Portanto, é aconselhável executar o ANALYZE após restaurar de uma cópia de segurança para garantir um bom desempenho.
Para salvar um banco de dados:
$ pg_dump meu_bd > db.out
Para recarregar este banco de dados:
$ psql -d banco_de_dados -f db.out
Para salvar o banco de dados chamado meu_bd contendo objetos grandes em um arquivo tar:
$ pg_dump -Ft -b meu_bd > db.tar
Para recarregar este banco de dados (com os objetos grandes) em um banco de dados existente chamado novo_bd:
$ pg_restore -d novo_bd db.tar
O utilitário pg_dump apareceu pela primeira vez no Postgres95 versão 0.02. Os formatos de saída não-texto-puro foram introduzidos no PostgreSQL versão 7.1.
