diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index c4215be..711b61e 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -38,7 +38,7 @@ pg_dump dbname > outfile As you see, pg_dump writes its result to the - standard output. We will see below how this can be useful. + standard output. @@ -47,8 +47,11 @@ pg_dump dbname > pg_dump does not operate with special permissions. In particular, it must - have read access to all tables that you want to back up, so in - practice you almost always have to run it as a database superuser. + have read access to all tables that you want to back up. Whether + it is going to have proper access permissions is determined by + privileges granted to a role used to connect to a database. + As long as the role has read access to tables, sequences, etc. + it need not to be a superuser role. @@ -95,13 +98,49 @@ pg_dump dbname > - If your database schema relies on OIDs (for instance, as foreign - keys) you must instruct pg_dump to dump the OIDs - as well. To do this, use the command-line - option. + The use of OIDs on user objects is deprecated. If your database schema + relies on OIDs (for instance, as foreign keys) you must instruct + pg_dump to dump the OIDs as well. To do this, use + the command-line option. + + This type of dump can be used to restore a database in full. However, + there is a more sophisticated form of PostgreSQL backup + that allows for far greater control when working with backups. A syntax looks like this: + +pg_dump -U username --format=c --file=mydatabase.sqlc dbname + + The options in detail are: + + -U, --username=NAME connect as specified database user + -F, --format=c|t|p output file format (custom, tar, plain text) + -f, --file=FILENAME output file name + + The most important of which is --format. + By default pg_dump uses the plaintext format. In + some cases you may be better off using a custom format backup, though. + The custom format allows for a wealth of customizability. + + + + Using the custom format you are able to restore single objects from a + backup. For example to restore only a specified index from a backup + file: + +pg_restore -U username --dbname=dbname --index=indexname + + If you wanted to restore only a single function: + +pg_restore -U username --dbname=dbname --function=functionname(args) + + If you wanted to restore only a single table: + +pg_restore -U username --dbname=dbname --table=tablename + + + Restoring the Dump @@ -176,6 +215,34 @@ pg_dump -h host1 dbname | psql -h h + When it comes to restoring a dump with a custom format the command + used to restore a backup file is pg_restore. It has + similar options to pg_dump. A simple restore: + +pg_restore -U username --dbname=databasename filename + + Where filename is the name of the backup file. + + + + + Do not confuse + + + + If what you have is a plaintext backup pg_restore can + not be used as a restoration mechanism. You can use psql to restore it: + +psql dbname < backupfile + + + + After restoring a backup, it is wise to run on each database so the query optimizer has useful statistics; @@ -222,14 +289,30 @@ psql -f infile postgres each database will be internally consistent, the snapshots of different databases might not be exactly in-sync. + + + Unfortunately, pg_dumpall can only create plaintext + backups. However, it is currently the only way to backup the globals in your + cluster. So, a reasonable backup strategy to backup your globals and + produce a flexible backup of every database in the cluster would + look like this: + +pg_dumpall -g -Uusername --file=globals.sql; +psql -AtU postgres -c "SELECT datname FROM pg_database \ + WHERE NOT datistemplate"| \ +while read f; + do pg_dump -Upostgres --format=c --file=$f.sqlc $f; +done; + + Handling Large Databases - Some operating systems have maximum file size limits that cause - problems when creating large pg_dump output files. + Although rare in modern operating systems, sometimes maximum file size limits may + cause problems when creating large pg_dump output files. Fortunately, pg_dump can write to the standard output, so you can use standard Unix tools to work around this potential problem. There are several possible methods: @@ -239,12 +322,20 @@ psql -f infile postgres Use compressed dumps. You can use your favorite compression program, for example - gzip: + gzip or pigz which + is a parallel implementation of gzip for modern + multi-processor, multi-core machines: pg_dump dbname | gzip > filename.gz + or: + + +pg_dump dbname | pigz > filename.gz + + Reload with: @@ -254,7 +345,7 @@ gunzip -c filename.gz | psql -cat filename.gz | gunzip | psql dbname +pigz -dc filename.gz | psql dbname