Code 4 Code

Name
pg_dump -- extrai um banco de dados do PostgreSQL para um arquivo script ou de exportação

Synopsis
pg_dump [-a | -s] [-b] [-c] [-C] [-d | -D] [-f arquivo] [-F formato] [-i] [-n | -N] [-o] [-O] [-R] [-S] [-t tabela] [-v] [-x] [-X palavra_chave] [-Z 0...9] [-h hospedeiro] [-p porta] [-U nome_do_usuário] [-W] nome_bd

Descrição
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).


Opções
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).

nome_bd - Especifica o nome do banco de dados a ser exportado.

-a
--data-only

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.

-b
--blobs

Exporta os objetos binários grandes (blobs).

-c
--clean

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.

-C
--create

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.

-d
--inserts

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.

-D
--column-inserts
--attribute-inserts

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.

-f arquivo
--file=arquivo

Envia a saída para o arquivo especificado. Se for omitido, a saída padrão é usada.

-F formato
--format=formato

Seleciona o formato da saída. O formato pode ser um dos seguintes:

p

Exporta um script SQL para um arquivo texto-puro (padrão)

t

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.

c

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.

-i
--ignore-version

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).

-n
--no-quotes

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.

-N
--quotes

Inclui aspas em torno dos identificadores. Este é o padrão.

-o
--oids

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.

-O
--no-owner

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.

-R
--no-reconnect

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.

-s
--schema-only

Exporta somente o esquema (definições dos dados), sem os dados.

-S nome_do_usuário
--superuser=nome_do_usuário

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.

-t tabela
--table=tabela

Exporta os dados da tabela apenas.

-v
--verbose

Especifica o modo verboso.

-x
--no-privileges
--no-acl

Impede gerar os privilégios de acessos (comandos GRANT/REVOKE).

-X use-set-session-authorization
--use-set-session-authorization

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.

-Z 0..9
--compress=0..9

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:

-h hospedeiro
--host=hospedeiro

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.

-p porta
--port=porta

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).

-U nome_do_usuário

Nome do usuário para se conectar.

-W

Força a solicitação da senha. Deve acontecer automaticamente se o servidor requerer autenticação por senha.


Exemplos
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

Para exportar um banco de dados chamado nome que contém criação do banco junto com insert dos dados existente:

pg_dump -d -U db_user -h ip_banco -f nome.sql nome_banco