pg_start_backup()

System function to put PostgreSQL in a state suitable for performing a backup

pg_start_backup() is a system function which puts PostgreSQL in a state suitable for performing a backup at file system level.

Return value

pg_start_backup() returns the LSN of the minimum WAL location which must be available for PostgreSQL to be able to start from a backup made from this point.

NOTE: the user or client application is responsible for ensuring required WAL files are available to the backup; in general it's advisable to use an application such as pg_basebackup to manage the backup process.

Source code

The backend code which handles pg_start_backup() is located in src/backend/access/transam/xlog.c, function do_pg_start_backup().

Change history

Examples

With an exclusive backup

postgres=# SELECT pg_start_backup('test backup');
 pg_start_backup 
-----------------
 0/2000028
(1 row)

postgres=# SELECT pg_is_in_backup();
 pg_is_in_backup                                                                                                                                                                    
-----------------                                                                                                                                                                   
 t                                                                                                                                                                                  
(1 row)                                                                                                                                                                             
                                                                                                                                                                                    
postgres=# SELECT pg_backup_start_time();                                                                                                                                           
  pg_backup_start_time                                                                                                                                                              
------------------------                                                                                                                                                            
 2018-12-14 19:22:50+09                                                                                                                                                             
(1 row)

At this point, the data directory will now contain a backup_label file, and it is safe to make a backup of the data directory at file-system level.

With a non-exclusive backup

postgres=# SELECT pg_start_backup(label := 'test backup', exclusive := false);
 pg_start_backup 
-----------------
 0/8000028
(1 row)

In a non-exclusive backup, a backup_label file will not be created (instead, the contents of the backup label will be returned as a record by pg_stop_backup()). It is now safe to make a backup of the data directory at file-system level.

Categories

Backup, Replication

See also

Backup history file, backup_label, pg_stop_backup(), tablespace_map