<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.123 2009/03/05 19:50:03 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.124 2009/04/07 00:31:25 tgl Exp $ -->

<chapter id="backup">

<title>Backup and Restore</title>

</para>

<para>

<function>pg_start_backup</> can take a long time to finish.

By default,<function>pg_start_backup</> can take a long time to finish.

This is because it performs a checkpoint, and the I/O

required fora checkpoint will be spread out over a significant

required forthe checkpoint will be spread out over a significant

period of time, by default half your inter-checkpoint interval

(see the configuration parameter

<xref linkend="guc-checkpoint-completion-target">). Usually

this is what you want because it minimizes the impact on query

this is what you want, because it minimizes the impact on query

processing. If you just want to start the backup as soon as

possible,execute a <command>CHECKPOINT</> command

immediately execute <function>pg_start_backup</>. Then there

todo, and it won't take long.

possible,use:

SELECTpg_start_backup('label', true);

This forces the checkpointtobe done as quickly as possible.

</para>

</listitem>

<listitem>

<para>

Once the WAL segment files used during the backup are archived, you are

done. The file identified by <function>pg_stop_backup</>'s result is

the last segment that is required to form a complete set of backup files.

the last segment that is required to form a complete set of backup files.

<function>pg_stop_backup</> does not return until the last segment has

been archived.

been archived.

Archiving of these files happens automatically since you have

already configured <varname>archive_command</>. In most cases this

happens quickly, but you are advised to monitor your archive

<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.474 2009/04/01 03:32:29 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.475 2009/04/07 00:31:25 tgl Exp $ -->

<chapter id="functions">

<title>Functions and Operators</title>

<tbody>

<row>

<entry>

<literal><function>pg_start_backup</function>(<parameter>label</> <type>text</>)</literal>

<literal><function>pg_start_backup</function>(<parameter>label</> <type>text</> <optional>, <parameter>fast</> <type>boolean</> </optional>)</literal>

</entry>

<entry><type>text</type></entry>

<entry>Set up for performing on-line backup</entry>

<entry>Prepare for performing on-line backup</entry>

</row>

<row>

<entry>

</table>

<para>

<function>pg_start_backup</> accepts asingle parameter which is an

<function>pg_start_backup</> accepts atext parameter which is an

arbitrary user-defined label for the backup. (Typically this would be

the name under which the backup dump file will be stored.) The function

writes a backup label file into the database cluster's data directory,

and then returns the backup's starting transaction log location as text. The user

need not pay any attention to this result value, but it is provided in

case it is of use.

performs a checkpoint,

and then returns the backup's starting transaction log location as text.

The user need not pay any attention to this result value, but it is

provided in case it is of use.

<programlisting>

postgres=# select pg_start_backup('label_goes_here');

pg_start_backup

-----------------

0/D4445B8

(1 row)

</programlisting>

There is an optional boolean second parameter. If <literal>true</>,

it specifies executing <function>pg_start_backup</> as quickly as

possible. This forces an immediate checkpoint which will cause a

spike in I/O operations, slowing any concurrently executing queries.

</para>

<para>

</para>

<para>

<function>pg_switch_xlog</> moves to the next transaction log file, allowing the

<function>pg_switch_xlog</> moves to the next transaction log file, allowing the

current file to be archived (assuming you are using continuous archiving).

The result is the ending transaction log location + 1 within the just-completed transaction log file.

If there has been no transaction log activity since the last transaction log switch,

pg_start_backup(PG_FUNCTION_ARGS)

{

text*backupid=PG_GETARG_TEXT_P(0);

boolfast=PG_GETARG_BOOL(1);

char*backupidstr;

XLogRecPtrcheckpointloc;

XLogRecPtrstartpoint;

RequestCheckpoint(CHECKPOINT_FORCE |CHECKPOINT_WAIT);

RequestCheckpoint(CHECKPOINT_FORCE |CHECKPOINT_WAIT |

(fast ?CHECKPOINT_IMMEDIATE :0));

REVOKE ALLon pg_user_mappingFROM public;

'debug function for current text search configuration';

CREATEOR REPLACE FUNCTION

pg_start_backup(labeltext, fastboolean DEFAULT false)

RETURNStext STRICT VOLATILE LANGUAGE internalAS'pg_start_backup';

DESCR("cancel a server process' current query");

DATA(insertOID=2096 (pg_terminate_backendPGNSPPGUID12100ffftfv1016"23"_null__null__null__null_pg_terminate_backend_null__null__null_ ));

DESCR("terminate a server process");

DATA(insertOID=2172 (pg_start_backupPGNSPPGUID12100ffftfv1025"25"_null__null__null__null_pg_start_backup_null__null__null_ ));

DATA(insertOID=2172 (pg_start_backupPGNSPPGUID12100ffftfv2025"25 16"_null__null__null__null_pg_start_backup_null__null__null_ ));

DESCR("prepare for taking an online backup");

DATA(insertOID=2173 (pg_stop_backupPGNSPPGUID12100ffftfv0025""_null__null__null__null_pg_stop_backup_null__null__null_ ));

DESCR("finish taking an online backup");