O pg_dump é um utilitário para salvar um banco de dados do PostgreSQL em um arquivo script ou de exportação. Os arquivos script são no formato texto-puro e contêm os comandos SQL necessários para reconstruir o banco de dados no estado em que este se encontrava no momento que foi salvo. Estes scripts podem ser usados até para reconstruir o banco de dados em outras máquinas com outras arquiteturas e, com algumas modificações, até em outros SGBDR. Além do script, existem outros formatos de exportação feitos para serem usados em conjunto com o pg_restore para reconstruir o banco de dados, que permitem ao pg_restore selecionar o que deve ser restaurado, ou mesmo reordenar a restauração dos itens. Estes formatos de exportação também são projetados para serem portáveis entre arquiteturas.
O pg_dump salva as informações necessárias para regerar todos os tipos, funções, tabelas, índices, agregações e operadores definidos pelo usuário. Adicionalmente, todos os dados são salvos no formato texto para que possam ser prontamente importados, bem como tratados por ferramentas de edição.
O pg_dump é útil para exportar o conteúdo de um banco de dados a ser movido de um PostgreSQL para outro.
Quando usado com um dos formatos de exportação e combinado com o pg_restore , o pg_dump fornece um mecanismo de exportação e importação flexível. O pg_dump pode ser usado para exportar todo o banco de dados e, posteriormente, o pg_restore pode ser usado para examinar o arquivo e/ou selecionar que partes do banco de dados devem ser importadas. O formato mais flexível produzido é o "personalizado" (custom, -Fc), que permite a seleção e a reordenação de todos os itens exportados, sendo comprimido por padrão. O formato tar (-Ft) não é comprimido e não permite reordenar os dados durante a importação mas, por outro lado, é bastante flexível; além disso, pode ser tratado por outras ferramentas como o tar.
Ao executar o pg_dump deve-se examinar a saída procurando por advertências (escritas na saída de erro padrão), atento especialmente às limitações listadas abaixo.
O pg_dump cria cópias de segurança consistentes, mesmo se o banco de dados estiver sendo usado concorrentemente. O pg_dump não bloqueia os outros usuários que porventura estejam acessando o banco de dados (leitura ou gravação).
O pg_dump aceita os seguintes argumentos de linha de comando (As formas longas das opções estão disponíveis apenas em algumas plataformas).
Especifica o nome do banco de dados a ser exportado.
Exporta somente os dados, não 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 se chamar o pg_restore.
Exporta os objetos binários grandes (blobs).
Gera comandos para excluir (drop) os objetos do banco de dados antes de criá-los.
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao se chamar o pg_restore.
Inicia a saída por um comando para criar o próprio banco de dados e se conectar ao banco de dados criado (Com um script assim, não importa em qual o 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 se chamar o pg_restore.
Exporta os dados como comandos INSERT (em vez de COPY), tornando a importação muito lenta, porém os arquivos exportados tornam-se mais portáveis para outros SGBDR.
Exporta os dados como comandos INSERT com nomes explícitos das colunas (INSERT INTO tabela (coluna, ...) VALUES ...), tornando a importação muito lenta, mas é necessário se for desejado mudar a ordem das colunas.
Envia a saída para o arquivo especificado. Se for omitido, a saída padrão é usada.
Seleciona o formato da saída. O formato pode ser um dos seguintes:
Exporta um script SQL para um arquivo texto-puro (padrão)
Exporta um arquivo tar adequado para servir de entrada para o pg_restore. Usando este formato de exportação pode-se reordenar e/ou excluir elementos do esquema durante a restauração do banco de dados. Também é possível limitar quais dados são importados durante a restauração.
Exporta um arquivo personalizado apropriado para servir de entrada para o pg_restore. Este é o formato mais flexível porque permite a reordenação da importação dos dados, assim como dos elementos do esquema. Este formato também é comprimido por padrão.
Ignora a diferença de versão entre o pg_dump e o servidor de banco de dados. Como o pg_dump trabalha muito ligado aos catálogos do sistema, toda versão do pg_dump é feita para ser usada somente com a versão correspondente do servidor de banco de dados. Use esta opção se for necessário desconsiderar a verificação de versão (mas, se o pg_dump falhar, não diga que não foi avisado).
Suprime as aspas (") em torno dos identificadores a menos que seja absolutamente necessário. Pode causar problemas na importação dos dados exportados se existirem palavras reservadas usadas pelos identificadores. Este era o comportamento padrão para o pg_dump antes da versão 6.4.
Inclui aspas em torno dos identificadores. Este é o padrão.
Exporta os identificadores de objeto (OIDs) para todas as tabelas. Deve-se usar esta opção quando a coluna OID é referenciada de alguma maneira (por exemplo, em uma restrição de chave estrangeira). Caso contrário esta opção não deve ser usada.
Não gera comandos para definir o mesmo dono do objeto do banco de dados original. Tipicamente, o pg_dump gera comandos \connect (específico do psql) para definir o dono dos elementos do esquema. Consulte também as opções -R e -X use-set-session-authorization. Observe que a opção -O não impede todas as reconexões ao banco de dados, mas somente àquelas que são usadas exclusivamente para acertar o dono.
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao se chamar o pg_restore.
Proíbe o pg_dump gerar um script que requeira reconexões com o banco de dados quando for realizada a importação. Usualmente, um script de importação necessita reconectar várias vezes como usuários diferentes para especificar o dono original dos objetos. Esta opção é um instrumento bastante rudimentar, porque faz o pg_dump perder a informação sobre o dono, a menos que seja usada a opção -X use-set-session-authorization.
Uma das razões possíveis para não se desejar a reconexão durante a importação é o acesso ao banco de dados requerer intervenção manual (por exemplo, senhas).
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao se chamar o pg_restore.
Exporta somente o esquema (definições dos dados), sem os dados.
Os scripts e os arquivos de exportação gerados pelo pg_dump necessitam do privilégio de superusuário em certos casos, como desativar gatilhos ou definir o dono dos elementos do esquema. Esta opção especifica o nome do usuário a ser usado nestes casos.
Exporta os dados da tabela apenas.
Especifica o modo verboso.
Impede gerar os privilégios de acessos (comandos GRANT/REVOKE).
Normalmente, se o script (modo texto-puro) gerado pelo pg_dump necessita trocar o usuário corrente do banco de dados (por exemplo, para definir o dono correto do objeto) é usado o comando \connect do psql. Este comando na verdade abre uma nova conexão, o que pode requerer a intervenção manual (por exemplo, senhas). Se for usada a opção -X use-set-session-authorization, então o pg_dump vai usar o comando SET SESSION AUTHORIZATION. Embora produza o mesmo efeito, requer que o usuário que for fazer a importação do banco de dados a partir do script gerado seja um superusuário. Esta opção substitui a opção -R.
Como o SET SESSION AUTHORIZATION é um comando SQL padrão, enquanto o \connect somente funciona no psql, esta opção também aumenta a portabilidade teórica do script gerado.
Esta opção só faz sentido para o formato texto-puro. Para os outros formatos esta opção pode ser especificada ao se chamar o pg_restore.
Especifica o nível de compressão a ser usado nos arquivos com formatos que suportam compressão (atualmente somente o formato personalizado suporta compressão).
O pg_dump também aceita os seguintes argumentos de linha de comando para os parâmetros de conexão:
Especifica o nome da máquina onde o servidor está executando. Se o nome iniciar por uma barra (/), é considerado como sendo o diretório do soquete do domínio Unix.
Especifica a porta Internet TCP/IP, ou o soquete do domínio local Unix, onde o servidor está aguardando as conexões. O padrão para o número da porta é 5432, ou o valor da variável de ambiente PGPORT (se estiver definida).
Nome do usuário para se conectar.
Força a solicitação da senha. Deve acontecer automaticamente se o servidor requerer autenticação por senha.
Connection to database 'template1' failed.
connectDBStart() -- connect() failed: No such file or directory
Is the postmaster running locally
and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?O pg_dump não pôde se conectar ao processo postmaster usando o computador e a porta especificada. Se esta mensagem for recebida, deve-se garantir que o postmaster está processando na máquina especificada e usando a porta especificada.
Note: O pg_dump executa internamente comandos SELECT. Se houver problema ao executar o pg_dump, deve-se ter certeza de poder consultar as informações no banco de dados usando, por exemplo, o psql.
Se na instalação houver 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 realmente vazio; de outra forma podem acontecer erros devido à duplicidade de definições dos objetos adicionados. Para criar um banco de dados vazio, sem nenhuma adição local, deve-se fazê-lo partir do template0, e não do template1. Por exemplo:
CREATE DATABASE foo WITH TEMPLATE = template0;
O pg_dump possui algumas poucas limitações:
Ao exportar uma única tabela, ou no formato texto-puro, o pg_dump não trata objetos grandes. Os objetos grandes devem ser exportados em sua inteireza usando um dos formatos binários de exportação.
Ao exportar somente os dados, o pg_dump gera comandos para desativar os gatilhos das tabelas do usuário antes de inserir os dados, e comandos para reativá-los após os dados terem sido inseridos. Se a restauração for interrompida no meio, os catálogos do sistema podem ficar em um estado errado.
Para exportar um banco de dados:
$ pg_dump meu_bd > db.out
Para importar este banco de dados:
$ psql -d database -f db.out
Para exportar um banco de dados chamado meu_bd que contém objetos grandes para um arquivo tar:
$ pg_dump -Ft -b meu_bd > bd.tar
Para importar este banco de dados (com os objetos grandes) para um banco de dados existente chamado novo_bd:
$ pg_restore -d novo_bd bd.tar