pg_dump
Nome
pg_dump -- salva um banco de dados do
PostgreSQL em um arquivo de script ou de outro tipo
Sinopse
pg_dump [opção...] [nome_do_banco_de_dados]
Descrição
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 concorrentemente. 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 ou em outros formatos. As cópias de segurança no formato de script são arquivos no formato 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 de arquivo de cópia de segurança alternativos 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. As formatos de cópia de segurança alternativos também são projetados para serem portáveis entre arquiteturas diferentes.
Quando usado com um dos formatos de cópia de segurança alternativos, 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 a 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.
Opções
As seguintes opções de linha de comando controlam o conteúdo e o formato da saída:
- nome_do_banco_de_dados
-
Especifica o nome do banco de dados a ser salvo. Se não for especificado, é utilizada a variável de ambiente PGDATABASE. Caso esta variável não esteja definida, é utilizado o nome do usuário especificado para a conexão.
- -a
--data-only
-
Salva somente os dados, não salva o esquema (definições de dado).
Esta opção só faz sentido para o formato texto-puro. Para os formatos alternativos esta opção pode ser especificada ao chamar o pg_restore.
- -b
--blobs
-
Inclui os objetos grandes na cópia de segurança. Deve ser selecionado um formato de saída não-texto.
- -c
--clean
-
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 formatos alternativos esta opção pode ser especificada ao chamar o pg_restore.
- -C
--create
-
Inicia a saída por um comando para criar o banco de dados e conectar ao banco de dados criado (Com um script assim não importa 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 formatos alternativos a opção pode ser especificada ao chamar o pg_restore.
- -d
--inserts
-
Salva os dados como comandos INSERT, em vez de COPY. Torna a restauração muito lenta, mas os arquivos produzidos são mais portáveis para outros sistemas gerenciadores de banco de dados SQL.
- -D
--column-inserts
--attribute-inserts
-
Salva os dados como comandos INSERT explicitando os nomes das colunas (INSERT INTO tabela (coluna, ...) VALUES ...). Torna a restauraçã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 é usada a saída padrão.
- -F formato
--format=formato
-
Seleciona o formato da saída. O formato pode ser um dos seguintes:
- p
-
Gera um arquivo de script SQL no formato texto-puro (padrão)
- t
-
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.
- c
-
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. Também, este formato é 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.
O pg_dump pode tratar bancos de dados de versões anteriores do PostgreSQL, 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).
- -n esquema
--schema=esquema
-
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) sã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.
- -o
--oids
-
Salva os identificadores de objeto (OIDs) de todas as tabelas como parte dos dados. Esta opção deve ser usada 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 a propriedade dos objetos correspondendo a do banco de dados original. Por padrão, o pg_dump emite comandos SET SESSION AUTHORIZATION para definir o dono dos objetos de bancos de dados criados. Estes comandos não são bem-sucedidos quando o script é executado, a menos que o script seja executado por um superusuário (ou o mesmo usuário que possui todos os objetos presentes no script). Para gerar um script que possa ser restaurado por qualquer usuário, mas que torna 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 formatos alternativos a opção pode ser especificada ao chamar o pg_restore.
- -R
--no-reconnect
-
Esta opção está obsoleta, mas ainda é aceita para manter compatibilidade com as versões anteriores.
- -s
--schema-only
-
Salva somente o esquema (definições dos dados), não os dados.
- -S nome_do_usuário
--superuser=nome_do_usuário
-
Especifica o nome de usuário do superusuário a ser usado para desabilitar 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).
- -t tabela
--table=tabela
-
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.
- -v
--verbose
-
Especifica o modo verboso, fazendo o pg_dump enviar as mensagens de progresso para a saída de erro padrão.
- -x
--no-privileges
--no-acl
-
Impede salvar os privilégios de acessos (comandos GRANT/REVOKE).
- -X use-set-session-authorization
--use-set-session-authorization
-
Esta opção está obsoleta, sendo aceita apenas para manter compatibilidade com as versões anteriores. Atualmente a aplicação pg_dump sempre se comporta da forma anteriormente selecionada por esta opção.
- -X disable-triggers
--disable-triggers
-
Esta opção somente é relevante ao criar um arquivo de cópia de segurança de dados apenas. Faz o pg_dump incluir comandos para desabilitar, temporariamente, os gatilhos das tabelas de destino enquanto os dados são recarregados. Deve ser utilizado 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 formatos alternativos esta opção pode ser especificada ao chamar o pg_restore.
- -Z 0..9
--compress=0..9
-
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:
- -h hospedeiro
--host=hospedeiro
-
Especifica o nome de hospedeiro da máquina onde o servidor está executando. Se o nome iniciar por uma barra (/) é usado 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.
- -p porta
--port=porta
-
Especifica a porta TCP, ou a extensão de arquivo do soquete do domínio Unix local, onde o servidor está escutando as conexões. O padrão é obter a partir da variável de ambiente PGPORT, se esta estiver definida, senão o padrão compilado.
- -U nome_do_usuário
-
Conectar como o usuário especificado.
- -W
-
Força a solicitação da senha, o que deve acontecer automaticamente quando o servidor requer autenticação por senha.
Ambiente
- PGDATABASE
PGHOST
PGPORT
PGUSER
-
Parâmetros de conexão padrão.
Diagnósticos
O pg_dump executa internamente comandos SELECT. Se acontecerem problemas ao executar o pg_dump, deve-se ter certeza que é possível selecionar informações no banco de dados utilizando, por exemplo, o utilitário
psql
.
Observações
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, 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;
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 é escolhido salvar apenas os dados, e se utiliza a opção --disable-triggers, o pg_dump emite comandos para desabilitar os gatilhos das tabelas do usuário antes de inserir os dados, e comandos para reabilitá-los após os dados terem sido inseridos. Se a restauração for interrompida antes do fim, os catálogos do sistema podem 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.
Uma vez restaurado, é aconselhável executar o comando ANALYZE em todas as tabelas restauradas para que o otimizador possua estatísticas úteis.
Exemplos
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
Histórico
O 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.