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. 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. Este é o comportamento padrão, exceto quando se especifica --schema, --table ou --schema-only, portanto a chave -b somente é útil para adicionar objetos grandes a cópias de segurança seletivas.
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. Além disso, como esta opção gera um comando separado para cada linha, um erro ao recarregar uma linha faz com que somente esta linha seja perdida, em vez de todo o conteúdo da tabela. 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. Além disso, como esta opção gera um comando separado para cada linha, um erro ao recarregar uma linha faz com que somente esta linha seja perdida, em vez de todo o conteúdo da tabela.
Cria uma cópia de segurança com a codificação do conjunto de caracteres especificado. Por padrão, a cópia de segurança é gerada com a codificação do banco de dados (Outra maneira de obter o mesmo resultado é definindo a variável de ambiente PGCLIENTENCODING com a codificação desejada para a cópia de segurança).
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 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.
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.
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). Fazer a cópia de segurança de um banco de dados mais novo que o pg_dump provavelmente não vai funcionar. 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 os esquemas correspondendo a esquema; seleciona tanto o próprio esquema quanto todos os objetos que este contém. Se esta opção não for especificada, todos os esquemas no banco de dados de destino, fora os do sistema, serão salvos. Podem ser selecionados vários esquemas escrevendo várias chaves -n. Além disso, o parâmetro esquema é interpretado como sendo um padrão de acordo com as mesmas regras utilizadas pelos comandos \d do psql (consulte Padrões), portanto também podem ser selecionados vários esquemas escrevendo caracteres curinga no padrão. Quando são utilizados caracteres curinga deve-se tomar o cuidado de colocar o padrão entre delimitadores, se for necessário, para impedir que o interpretador de comandos expanda os caracteres curinga.
Nota: Quando é especificado -n, o pg_dump não tenta salvar qualquer objeto do banco de dados dos quais os esquemas selecionados possam depender. Portanto, não há garantia que os resultados de uma cópia de segurança específica de esquema será bem-sucedida ao ser restaurada por si própria em um banco de dados vazio.
Nota: Os objetos que não são do esquema, como os objetos binários grandes (blobs) não são salvos quando -n é especificado. Os blobs podem ser reintroduzidos na cópia de segurança utilizando a chave --blobs.
Não salva os esquemas que correspondem ao padrão esquema. O padrão é interpretado de acordo com as mesmas regras para a chave -n. A chave -N pode ser escrita mais de uma vez para excluir esquemas que correspondem a vários padrões.
Quando se especifica tanto -n quanto -N, o comportamento é salvar apenas os esquemas que correspondem a pelo menos uma chave -n e a nenhuma chave -N. Se -N aparecer sem -n, então os esquemas correspondendo a -N serão excluídos da cópia de segurança normal.
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 as tabelas (ou visões ou seqüências) correspondendo a tabela. Podem ser selecionadas várias tabelas escrevendo várias chaves -t. Além disso, o parâmetro tabela é interpretado como sendo um padrão de acordo com as mesmas regras utilizadas pelos comandos \d do psql (consulte Padrões), portanto também podem ser selecionadas várias tabelas escrevendo caracteres curinga no padrão. Quando são utilizados caracteres curinga deve-se tomar o cuidado de colocar o padrão entre delimitadores, se for necessário, para impedir que o interpretador de comandos expanda os caracteres curinga.
As chaves -n e -N não têm nenhum efeito quando é utilizada a chave -t, porque as tabelas selecionadas por -t são salvas sem considerar estas chaves, e os objetos que não são tabelas não são salvos.
Nota: Quando é especificado -t, o pg_dump não tenta salvar qualquer objeto do banco de dados dos quais as tabelas selecionadas possam depender. Portanto, não há garantia que os resultados de uma cópia de segurança específica de tabela será bem-sucedida ao ser restaurada por si própria em um banco de dados vazio.
Nota: O comportamento da chave -t não é possui total compatibilidade ascendente [1] com as verões do PostgreSQL anteriores a 8.2. Antes, escrever -t tab salvava todas as tabelas de nome tab, mas agora só salva as tabelas visíveis no caminho de procura padrão utilizado. Para obter o comportamento antigo, pode ser escrito -t '*.tab'. Além disso, deve ser escrito algo como -t esq.tab para selecionar uma tabela de um determinado esquema, em vez da maneira antiga -n esq -t tab.
Não salva as tabelas que correspondem ao padrão tabela. O padrão é interpretado de acordo com as mesmas regras para a chave -t. A chave -T pode ser escrita mais de uma vez para excluir tabelas que correspondem a vários padrões.
Quando se especifica tanto -t quanto -T, o comportamento é salvar apenas as tabelas que correspondem a pelo menos uma chave -t e a nenhuma chave -T. Se -T aparecer sem -t, então as tabelas correspondendo a -T serão excluídas da cópia de segurança normal.
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 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. Além disso, salvar utilizando SET SESSION AUTHORIZATION certamente vai requerer privilégios de superusuário para restaurar de maneira correta, enquanto ALTER OWNER requer menos privilégios.
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:
Quando é escolhida uma cópia de segurança apenas dos dados e é utilizada a opção --disable-triggers, o pg_dump submete 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 no meio, 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.
Como o pg_dump é utilizado para transferir dados para uma versão mais nova do PostgreSQL, a saída do pg_dump pode ser carregada em bancos de dados PostgreSQL mais novos. O pg_dump também pode ler bancos de dados PostgreSQL mais antigos, entretanto geralmente não consegue ler bancos de dados PostgreSQL mais novos, ou produzir uma saída que possa ser carregada em bancos de dados mais antigos. Para fazer isto pode ser requerida a edição manual dos arquivos de cópia de segurança.
Para salvar o banco de dados chamado meu_bd em um arquivo de script SQL:
$ pg_dump meu_bd > bd.sql
Para recarregar este script no banco de dados (recém criado) chamado novo_bd:
$ psql -d novo_bd -f bd.sql
Para salvar o banco de dados no arquivo de cópia de segurança com formato personalizado:
$ pg_dump -Fc meu_bd > bd.dump
Para recarregar esta cópia de segurança no banco de dados (recém criado) chamado novo_bd:
$ pg_restore -d novo_bd bd.dump
Para salvar uma única tabela chamada minha_tabela:
$ pg_dump -t minha_tabela meu_bd > bd.sql
Para salvar todas as tabelas cujos nomes começam por emp no esquema detroit, exceto a tabela chamada empregado_log:
$ pg_dump -t 'detroit.emp*' -T detroit.empregado_log meu_bd > bd.sql
Para salvar todos os esquemas cujos nomes começam por leste ou oeste e terminam por gsm, excluindo todos os esquemas cujos nomes contenham a palavra teste:
$ pg_dump -n 'leste*gsm' -n 'oeste*gsm' -N '*teste*' meu_bd > bd.sql
A mesma coisa utilizando a notação de expressão regular para unificar as chaves:
$ pg_dump -n '(leste|oeste)*gsm' -N '*teste*' meu_bd > bd.sql
Para salvar todos os objetos do banco de dados, exceto as tabelas cujos nomes começam por ts_:
$ pg_dump -T 'ts_*' meu_bd > bd.sql
Para especificar um nome com letras maiúsculas, ou maiúsculas e minúsculas, na chave -t e nas chaves relacionadas, é necessário colocar o nome entre aspas; senão será convertido para letras minúsculas (consulte Padrões). Porém, aspa é um caractere especial para o interpretador de comandos e, por isso, também precisa ser delimitada. Assim sendo, para salvar uma única tabela com um nome com letras minúsculas e maiúsculas é necessário algo como:
$ pg_dump -t '"NomeMaiúsculasMinúsculas"' meu_bd > minha_tabela.sql
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.
| [1] |
compatibilidade ascendente (upward compatibility) — característica de um software que funciona sem modificações em versões mais recentes ou mais avançadas de determinado sistema de computador. Webster's New World Dicionário de Informática, Bryan Pfaffenberger, Editora Campus, 1999, pág. 200. (N. do T.) |
