# 在PostgreSQL中 pg_start_backup 做了什么?
HM 2019-07-30
## pg_start_backup
做一个备份开始标记，还做了一些其他的操作，下面进行探寻。
* 函数定义：
```
postgres=# df pg_start_backup
List of functions
Schema | Name | Result data type | Argument data types | Type
------------+-----------------+------------------+------------------------------------------------------------------------+------
pg_catalog | pg_start_backup | pg_lsn | label text, fast
boolean DEFAULT false, exclusive boolean DEFAULT true | func
(1 row)
```
* 参数介绍：
```
第一个参数：开始记录备份的标签；
第二个参数：设置是否为快速执行，默认为false，将会做一个schedule checkpoint，把脏数据刷到磁盘。这里会等待其他checkpoint结束，有时候会等一下；如果设置为true，会尽快执行checkpoint，可能会产生大量的IO，拖慢正在执行的SQL；
第三个参数：是否是exclusive模式，既是否为独占模式；默认为true，如果设置为false，则在调用pg_stop_back时，需要指定独占模式为false，且将返回备份标签文件里面的内容。
那么exclusive模式和no-exclusive模式的内在区别在哪里？
```
* 那么pg_start_backup将会执行下面几件事情：
```
1.如果设置为独占模式（默认是），将会把开始备份的LSN和checkpoint信息记录到标签
文件。同时，如果有表空间链接，也会记录一个tablespace_map。如果是no-exclusive
模式，则不会记录，这些信息会在执行pg_stop_back时返回。
那么他会不会switch一个新的wal文件呢？会不会把归档日志做完归档呢？有没有必要，
没有必要。
在此时拷贝数据库data文件进行恢复可能会失败，因为备份的数据可能不是在一致性下，
数据文件的刷盘不可能同时完成。单纯恢复到checkpoint点应该可以，但是，只有一个备
份文件是无法这样回退恢复的。
因此，还需要获取到从startbackup到stopbackup之间的wal日志，以拷贝的data目录
+这段wal日志进行恢复，即可恢复成功。
这也是pg_basebackup的逻辑。
2.将wal日志设置为forcepagewrites，即使没有把full_page_writes设为on，保证在
startbackup期间，对数据库的写是可以完全回放的。
如果不这样做，在从checkpoint点恢复时，从新的环境的对应block进行数据回放，块的
初始数据不一样，恢复后的结果就可能是错的。这点可以参考full_page_writes的功能。
3.根据第二个fast参数的值，选择执行哪种checkpoint。
```
## pg_stop_backup:
pg_stop_backup则是将日志模式恢复正常，删除data目录下的备份日志文件，返回结束的
LSN或者备份标记信息。
* 函数定义：
```
postgres=# df pg_stop_backup
List of functions
Schema | Name | Result data type | Argument data types | Type
------------+----------------+------------------+-------------------------------------------------------------------------------------------------------------------+------
pg_catalog | pg_stop_backup | pg_lsn | | func
pg_catalog | pg_stop_backup | SETOF record | exclusive boolean,
wait_for_archive boolean DEFAULT true, OUT lsn pg_lsn, OUT labelfile text,
OUT spcmapfile text | func
(2 rows)
```
## 实验
```
postgres=# select pg_start_backup('test', true, true);
pg_start_backup
-----------------
0/2000060
(1 row)
postgres=# select pg_start_backup('test', true, true);
ERROR: a backup is already in progress
HINT: Run pg_stop_backup() and try again.
postgres=# ^Z
[1]+ Stopped psql
[postgres@localhost ~]$ cd $PGDATA
[postgres@localhost data]$ ls
backup_label global pg_dynshmem pg_logical pg_replslot
pg_stat pg_tblspc pg_wal postgresql.conf
base log pg_hba.conf pg_multixact pg_serial
pg_stat_tmp pg_twophase pg_xact postmaster.opts
current_logfiles pg_commit_ts pg_ident.conf pg_notify pg_snapshots
pg_subtrans PG_VERSION postgresql.auto.conf postmaster.pid
[postgres@localhost data]$ cat backup_label
START WAL LOCATION: 0/2000060 (file 000000010000000000000002)
CHECKPOINT LOCATION: 0/2000098
BACKUP METHOD: pg_start_backup
BACKUP FROM: master
START TIME: 2019-07-30 03:05:20 PDT
LABEL: test
START TIMELINE: 1
[postgres@localhost data]$ fg
psql (wd: ~)
postgres=# select pg_stop_backup();
NOTICE: WAL archiving is not enabled; you must ensure that all required
WAL segments are copied through other means to complete the backup
pg_stop_backup
----------------
0/2000168
(1 row)
postgres=# ^Z
[1]+ Stopped psql (wd: ~)
(wd now: /dbdata/pg11/data)
[postgres@localhost data]$ cat backup_label
cat: backup_label: No such file or directory
[postgres@localhost data]$ ls
base log pg_hba.conf pg_multixact pg_serial
pg_stat_tmp pg_twophase pg_xact postmaster.opts
current_logfiles pg_commit_ts pg_ident.conf pg_notify
pg_snapshots pg_subtrans PG_VERSION postgresql.auto.conf postmaster.pid
global pg_dynshmem pg_logical pg_replslot pg_stat pg_tblspc pg_wal postgresql.conf
[postgres@localhost data]$
postgres=# select pg_start_backup('test', true, false);
pg_start_backup
-----------------
0/4000028
(1 row)
postgres=# select pg_stop_backup();
ERROR: non-exclusive backup in progress
HINT: Did you mean to use pg_stop_backup('f')?
postgres=# select pg_stop_backup('f');
NOTICE: WAL archiving is not enabled; you must ensure that all
required WAL segments are copied through other means to complete
the backup
pg_stop_backup
---------------------------------------------------------------------------
(0/4000130,"START WAL LOCATION: 0/4000028 (file 000000010000000000000004)
+ CHECKPOINT LOCATION: 0/4000060
+ BACKUP METHOD: streamed
+ BACKUP FROM: master
+ START TIME: 2019-07-30 03:12:35 PDT
+ LABEL: test
+ START TIMELINE: 1
+ ","")
(1 row)
postgres=# ^Z
[1]+ Stopped psql (wd: ~)
(wd now: /dbdata/pg11/data)
[postgres@localhost data]$ ls
base log pg_hba.conf pg_multixact pg_serial pg_stat_tmp pg_twophase pg_xact postmaster.opts
current_logfiles pg_commit_ts pg_ident.conf pg_notify pg_snapshots pg_subtrans PG_VERSION postgresql.auto.conf postmaster.pid
global pg_dynshmem pg_logical pg_replslot pg_stat pg_tblspc pg_wal postgresql.conf
[postgres@localhost data]$ ls pg_wal/
000000010000000000000004 000000010000000000000005 archive_status
```
## 官方文档
```
`pg_start_backup` accepts an arbitrary user-defined label for the backup.
(Typically this would be the name under which the backup dump file will be
stored.) When used in exclusive mode, the function writes a backup label
file (`backup_label`) and, if there are any links in the `pg_tblspc/`
directory, a tablespace map file (`tablespace_map`) into the database
cluster's data directory, performs a checkpoint, and then returns the
backup's starting write-ahead log location as text. The user can ignore
this result value, but it is provided in case it is useful. When used
in non-exclusive mode, the contents of these files are instead returned
by the `pg_stop_backup` function, and should be written to the backup
by the caller.
postgres=# select pg_start_backup('label_goes_here');
pg_start_backup
-----------------
0/D4445B8
(1 row)
There is an optional second parameter of type `boolean`. If `true`, it
specifies executing `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.
In an exclusive backup, `pg_stop_backup` removes the label file and, if it exists, the `tablespace_map` file created by `pg_start_backup`. In
a non-exclusive backup, the contents of the `backup_label` and
`tablespace_map` are returned in the result of the function, and should
be written to files in the backup (and not in the data directory).
There is an optional second parameter of type `boolean`. If false, the
`pg_stop_backup` will return immediately after the backup is completed
without waiting for WAL to be archived. This behavior is only useful
for backup software which independently monitors WAL archiving.
Otherwise, WAL required to make the backup consistent might be missing
and make the backup useless. When this parameter is set to true,
`pg_stop_backup`will wait for WAL to be archived when archiving is
enabled; on the standby, this means that it will wait only when
`archive_mode = always`. If write activity on the primary is low, it
may be useful to run `pg_switch_wal` on the primary in order to trigger
an immediate segment switch.
When executed on a primary, the function also creates a backup history
file in the write-ahead log archive area. The history file includes the
label given to `pg_start_backup`, the starting and ending write-ahead
log locations for the backup, and the starting and ending times of the
backup. The return value is the backup's ending write-ahead log
location (which again can be ignored). After recording the ending
location, the current write-ahead log insertion point is automatically
advanced to the next write-ahead log file, so that the ending write-
ahead log file can be archived immediately to complete the backup.
```