# 备份恢复控制函数 #### 备份控制函数 备份控制函数可帮助进行在线备份。 - pg_create_restore_point(name text) 描述：为执行恢复创建一个命名点。需要管理员角色权限。 返回值类型：text 备注：pg_create_restore_point创建了一个可以用作恢复目的、有命名的事务日志记录，并返回相应的事务日志位置。在恢复过程中，recovery_target_name可以通过这个名称定位对应的日志恢复点，并从此处开始执行恢复操作。避免使用相同的名称创建多个恢复点，因为恢复操作将在第一个匹配（恢复目标）的名称上停止。 - pg_current_xlog_location() 描述：获取当前事务日志的写入位置。 返回值类型：text 备注：pg_current_xlog_location使用与前面那些函数相同的格式显示当前事务日志的写入位置。如果是只读操作，不需要系统管理员权限。 - pg_current_xlog_insert_location() 描述：获取当前事务日志的插入位置。 返回值类型：text 备注：pg_current_xlog_insert_location显示当前事务日志的插入位置。插入点是事务日志在某个瞬间的"逻辑终点"，而实际的写入位置则是从服务器内部缓冲区写出时的终点。写入位置是可以从服务器外部检测到的终点，如果要归档部分完成事务日志文件，则该操作即可实现。插入点主要用于服务器调试目的。如果是只读操作，不需要系统管理员权限。 - gs_current_xlog_insert_end_location() 描述：获取当前事务日志的插入位置。 返回值类型：text 备注：gs_current_xlog_insert_end_location显示当前事务日志的实际插入位置。 - pg_start_backup(label text \[, fast boolean \]) 描述：开始执行在线备份。需要管理员角色、复制的角色或运维管理员角色打开operation_mode。 返回值类型：text 备注：pg_start_backup接受一个用户定义的备份标签（通常这是备份转储文件存放地点的名称）。这个函数向数据库的数据目录写入一个备份标签文件，然后以文本方式返回备份的事务日志起始位置。 ``` gaussdb=# SELECT pg_start_backup('label_goes_here'); pg_start_backup ----------------- 0/3000020 (1 row) ``` - pg_stop_backup() 描述：完成执行在线备份。需要管理员角色、复制的角色或运维管理员角色打开operation_mode。 返回值类型：text 备注：pg_stop_backup删除pg_start_backup创建的标签文件，并且在事务日志归档区里创建一个备份历史文件。这个历史文件包含给予pg_start_backup的标签、备份的事务日志起始与终止位置、备份的起始和终止时间。返回值是备份的事务日志终止位置。计算出终止位置后，当前事务日志的插入点将自动前进到下一个事务日志文件，结束的事务日志文件可以被立即归档从而完成备份。 - pg_switch_xlog() 描述：切换到一个新的事务日志文件。需要管理员角色或运维管理员角色打开operation_mode。 返回值类型：text 备注：pg_switch_xlog移动到下一个事务日志文件，以允许将当前日志文件归档（假定使用连续归档）。返回值是刚完成的事务日志文件的事务日志结束位置+1。如果从最后一次事务日志切换以来没有活动的事务日志，则pg_switch_xlog不进行移动操作，直接返回当前事务日志文件的开始位置。 - pg_xlogfile_name(location text) 描述：将事务日志的位置字符串转换为文件名。 返回值类型：text 备注：pg_xlogfile_name仅抽取事务日志文件名称。如果给定的事务日志位置恰好位于事务日志文件的交界上，这两个函数都返回前一个事务日志文件的名称。这对于管理事务日志归档来说是非常有利的，因为前一个文件是当前最后一个需要归档的文件。 - pg_xlogfile_name_offset(location text) 描述：将事务日志的位置字符串转换为文件名并返回在文件中的字节偏移量。 返回值类型：text,integer 备注：可以使用pg_xlogfile_name_offset从前述函数的返回结果中抽取相应的事务日志文件名称和字节偏移量。例如： ``` gaussdb=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); NOTICE: pg_stop_backup cleanup done, waiting for required WAL segments to be archived NOTICE: pg_stop_backup complete, all required WAL segments have been archived file_name | file_offset --------------------------+------------- 000000010000000000000003 | 272 (1 row) ``` - pg_xlog_location_diff(location text, location text) 描述：计算两个事务日志位置之间在字节上的区别。 返回值类型：numeric - pg_cbm_start_tracked_location() 描述：用于查询cbm解析的起始lsn位置。 返回值类型：text - pg_cbm_tracked_location() 描述：用于查询cbm解析到的lsn位置。 返回值类型：text - pg_cbm_get_merged_file(startLSNArg text, endLSNArg text) 描述：用于将指定lsn范围之内的cbm文件合并成一个cbm文件，并返回合并完的cbm文件名。 返回值类型：text 备注：必须是系统管理员或运维管理员才能获取cbm合并文件。 - pg_cbm_get_changed_block(startLSNArg text, endLSNArg text) 描述：用于将指定lsn范围之内的cbm文件合并成一个表，并返回表的各行记录。 返回值类型：records 备注：pg_cbm_get_changed_block返回的表字段包含：合并起始的lsn、合并截止的lsn、表空间oid、库oid、表的relfilenode、表的fork number、表是否为系统表、表是否被删除、表是否被创建、表是否被截断、表被截断后的页面数、有多少页被修改以及被修改的页号的列表。 - pg_cbm_recycle_file(targetLSNArg text) 描述：删除不再使用的cbm文件，并返回删除后的第一条lsn。 返回值类型：text - pg_cbm_force_track(targetLSNArg text,timeOut int) 描述：强制执行一次cbm追踪到指定的xlog位置，并返回实际追踪结束点的xlog位置。 返回值类型：text - pg_enable_delay_ddl_recycle() 描述：开启延迟DDL功能，并返回开启点的xlog位置。需要管理员角色或运维管理员角色打开operation_mode。 返回值类型：text - pg_disable_delay_ddl_recycle(barrierLSNArg text, isForce bool) 描述：关闭延迟DDL功能，并返回本次延迟DDL生效的xlog范围。需要管理员角色或运维管理员角色打开operation_mode。 返回值类型：records - pg_enable_delay_xlog_recycle() 描述：开启延迟xlog回收功能，数据库主节点修复使用。需要管理员角色或运维管理员角色打开operation_mode。 返回值类型：void - pg_disable_delay_xlog_recycle() 描述：关闭延迟xlog回收功能，数据库主节点修复使用。需要管理员角色或运维管理员角色打开operation_mode。 返回值类型：void - pg_cbm_rotate_file(rotate_lsn text) 描述：等待cbm解析到rotate_lsn之后，强制切换文件，在build期间调用。 返回值类型：void。 - gs_roach_stop_backup(backupid text) 描述：停止一个内部备份工具GaussRoach开启的备份。与pg_stop_backup系统函数类似，但更轻量。 返回值类型：text，内容为当前日志的插入位置。 - gs_roach_enable_delay_ddl_recycle(backupid name) 描述：开启延迟DDL功能，并返回开启点的日志位置。与pg_enable_delay_ddl_recycle系统函数类似，但更轻量。并且，通过传入不同的backupid，可以支持并发打开延迟DDL。 返回值类型：text，内容为返回开启点的日志位置。 - gs_roach_disable_delay_ddl_recycle(backupid text) 描述：关闭延迟DDL功能，并返回本次延迟DDL生效的日志范围。与pg_enable_delay_ddl_recycle系统函数类似，但更轻量。并且，通过传入不同的backupid，可以支持并发关闭延迟DDL功能。 返回值类型：records，内容为本次延迟DDL生效的日志范围。 - gs_roach_switch_xlog(request_ckpt bool) 描述：切换当前使用的日志段文件，并且，如果request_ckpt为true，则触发一个全量检查点。 返回值类型：text，内容为切段日志的位置。 - gs_block_dw_io(timeout int, identifier text) 描述：阻塞双写页面刷盘。 参数说明： - timeout 阻塞时长。 取值范围：\[0, 3600\]（秒），0为阻塞时长为0。 - identifier 此次操作的标识。 取值范围：字符串，不支持除大小写字母、数字以及下划线(_)以外的字符。 返回值类型：bool 备注：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限，运维管理员角色须打开operation_mode。 - gs_is_dw_io_blocked() 描述：查看当前双写页面刷盘是否被阻塞，如果处于阻塞中则返回true。 返回值类型：bool 备注：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限，运维管理员角色须打开operation_mode。 - gs_pitr_advance_last_updated_barrier() 描述：在PITR模式下，强制推进上次上传到OBS/NAS介质中的全局最大已归档恢复点到当前点，无入参。 返回值类型：text 备注：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限，运维管理员角色须打开operation_mode。同时只能在集中式的主DN上使用才有效。返回值为当前推进到的最新本地最大已归档恢复点。 - gs_pitr_clean_local_barrier_files('delete_timestamp') 描述：清理本地缓存的barrier记录文件。 参数范围：delete_timestamp参数类型为text，为linux时间戳，长度为10位。 返回值类型：text 备注：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限，运维管理员角色须打开operation_mode。返回的结果是删除后本地最老barrier文件的开始时间戳。 - gs_get_barrier_lsn(barrier_name text) 描述：获取备份创建的barrier对应的lsn。 返回值类型：text 备注：目前不支持该函数。当前入参仅支持gs_roach_full和gs_roach_inc。调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限，运维管理员角色须打开operation_mode。 - gs_gbr_relation_associated_filenode(schemaName name, tableName name) 描述：返回与输入table相关的全部索引、sequence、分区、toast、toast index的relfilenode。 返回值类型：records 备注：gs_gbr_relation_associated_filenode返回的字段包含文件类型relkind、文件所在namespace、文件对应的relation name、文件所在的database oid、文件所在的tablespace oid以及文件的relfilenode。 - pg_create_physical_replication_slot_extern(slotname text, dummy_standby bool, extra_content text, need_recycle_xlog bool) ![](https://support.huaweicloud.com/centralized-devg-v3-gaussdb/public_sys-resources/notice_3.0-zh-cn.png) slotname为归档槽名称，取值范围：字符串，仅支持小写字母、数字以及"_"，"?"，"-"，"."字符，且不支持"."或".."单独作为复制槽名称。建议使用字母字符串作为归档槽名，且长度不能超过64。 描述：创建OBS/NAS归档槽。slotname为归档槽/恢复槽的slotname ，主备必须使用同一个slotname。dummy_standby是预留参数。extra_content包含了归档槽的一些信息。对于OBS归档槽，其格式为"OBS;obs_server_ip;obs_bucket_name;obs_ak;obs_sk;archive_path;is_recovery;is_vote_replicate"，OBS表示归档槽的归档的介质，obs_server_ip为obs的ip，obs_bucket_name为obs的桶名，obs_ak为obs的ak，obs_sk为obs的sk，archive_path为归档的路径i，is_recovery标志是归档槽还是恢复槽，0表示是归档槽，1表示是恢复槽。is_vote_replicate标志是否是投票副本优先，0表示同步备机归档优先，1表示投票副本归档优先，当前版本该字段为预留字段，暂未适配。对于NAS归档槽，其格式为"NAS;archive_path;is_recovery;is_vote_replicate"，相比OBS归档槽，缺少了OBS相关的配置信息，其余字段意义相同。 如果是不指定OBS或NAS介质的话，默认指定的是OBS归档槽，其extra_content格式为"obs_server_ip;obs_bucket_name;obs_ak;obs_sk;archive_path;is_recovery;is_vote_replicate"。 need_recycle_xlog标志创建归档槽时是否回收老的归档日志，true表示回收，false表示不回收。 返回值类型：records包含slotname和xlog_position。 备注：调用该函数的用户需要具有SYSADMIN权限或具有REPLICATION权限或继承了内置角色gs_role_replication的权限。目前不支持创建多归档槽。 例如： 创建OBS归档槽： ``` gaussdb=# select * from pg_create_physical_replication_slot_extern('uuid', false, 'OBS;obs_server_ip;obs_bucket_name;obs_ak;obs_sk;gaussdb_uuid/dn1;0;0', false); slotname | xlog_position ----------+--------------- uuid | (1 row) ``` 创建NAS归档槽： ``` gaussdb=# select * from pg_create_physical_replication_slot_extern('uuid', false, 'NAS;/data/nas/media/gaussdb_uuid/dn1;0;0',false); slotname | xlog_position ----------+--------------- uuid | ``` - gs_set_obs_delete_location(delete_location text) 描述：设置OBS归档日志可删除的位置。delete_location实际为Log Sequence Number ( LSN )，该位置之前的日志已经完成回放并且落盘，可以在OBS上进行删除。 返回值类型：xlog_file_name text，表明此次可删除点所在的日志文件名。无论OBS删除是否成功，该值都会正常返回。 ``` gaussdb=# select gs_set_obs_delete_location('0/54000000'); gs_set_obs_delete_location ----------------------------- 000000010000000000000054_00 (1 row) ``` - gs_set_obs_delete_location_with_slotname(cstring, cstring ) 描述：设置指定归档槽OBS归档日志可删除的位置。第一个参数实际为Log Sequence Number ( LSN )，该位置之前的日志已经完成回放并且落盘，可以在OBS上进行删除，第二个参数为归档槽的名称。 返回值类型：xlog_file_name text，表明此次可删除点所在的日志文件名。无论OBS删除是否成功，该值都会正常返回。 - gs_get_global_barrier_status() 描述：gs_get_global_barrier_status用以查询主数据库实例已在obs完成归档的最新global barrier。 返回值类型：text global_barrier_id：全局最新barrier ID。 global_achive_barrier_id：全局最新归档barrier ID。 - gs_get_global_barriers_status() 描述：gs_get_global_barriers_status用以查询主数据库实例已在OBS完成归档的最新global barrier。 返回值类型：text slot_name：槽位名。 global_barrier_id：全局最新barrier ID。 global_achive_barrier_id：全局最新归档barrier ID。 - gs_set_archive_standby_name_on_primary(text) 描述：gs_set_archive_standby_name_on_primary用来指定归档备机，设置后将由指定的备机执行归档操作。输入为备机名称，如：dn_6002。 返回值类型：bool - true：表示设置成功； - false：表示设置失败。 #### 恢复控制函数 恢复信息函数提供了当前备机状态的信息。这些函数可能在恢复期间或正常运行中执行。 - pg_is_in_recovery() 描述：如果恢复仍然在进行中则返回true。 返回值类型：Boolean - pg_last_xlog_receive_location() 描述：获取最后接收事务日志的位置并通过流复制将其同步到磁盘。当流复制正在进行时，事务日志将持续递增。如果恢复已完成，则最后一次获取的WAL记录会被静态保持并在恢复过程中同步到磁盘。如果流复制不可用，或还没有开始，这个函数返回NULL。 返回值类型：text - pg_last_xlog_replay_location() 描述：获取最后一个事务日志在恢复时重放的位置。如果恢复仍在进行，事务日志将持续递增。如果已经完成恢复，则将保持在恢复期间最后接收WAL记录的值。如果未进行恢复但服务器正常启动时，则这个函数返回NULL。 返回值类型：text - pg_last_xact_replay_timestamp() 描述：获取最后一个事务在恢复时重放的时间戳。这是为在主节点上生成事务提交或终止WAL记录的时间。如果在恢复时没有事务重放，则这个函数返回NULL。如果恢复仍在进行，则事务日志将持续递增。如果恢复已经完成，则将保持在恢复期间最后接收WAL记录的值。如果服务器无需恢复就已正常启动，则这个函数返回NULL。 返回值类型：timestamp with time zone 恢复控制函数控制恢复的进程。这些函数可能只在恢复时被执行。 - pg_is_xlog_replay_paused() 描述：如果恢复暂停则返回true。 返回值类型：Boolean - pg_xlog_replay_pause() 描述：立即暂停恢复。 返回值类型：void - pg_xlog_replay_resume() 描述：如果恢复处于暂停状态，则重新启动。 返回值类型：void - gs_get_active_archiving_standby() 描述：查询同一分片内归档备机的信息。返回备机名，备机归档位置和已归档日志个数。 返回值类型：text，int - gs_pitr_get_warning_for_xlog_force_recycle() 描述：查询开启归档后是否因归档槽不推进日志大量堆积导致日志被回收。 返回值类型：bool - gs_pitr_clean_history_global_barriers(stop_barrier_timestamp cstring) 描述：清理指定时间之前所有barrier记录。返回最老的barrier记录。入参为cstring类型，linux时间戳。需要管理员角色或运维管理员角色执行。 返回值类型：text - gs_pitr_archive_slot_force_advance(stop_barrier_timestamp cstring) 描述：强制推进归档槽，并清理不需要的barrier记录。返回新的归档槽位置。入参为cstring类型，linux时间戳。需要管理员角色或运维管理员角色执行。 返回值类型：text 当恢复暂停时，没有发生数据库更改。如果是在热备里，所有新的查询将看到一致的数据库快照，并且不会有进一步的查询冲突产生，直到恢复继续。 如果不能使用流复制，则暂停状态将无限的延续。当流复制正在进行时，将连续接收WAL记录，最终将填满可用磁盘空间，这个进度取决于暂停的持续时间，WAL生成的速度和可用的磁盘空间。 - gs_recent_barrier_buffer_info(start_time text, end_time text) 描述：根据用户输入的时间范围，进行相应的barrier信息查询，获取time_stamp、CSN、LSN和standard_time。 返回值类型：records 说明：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限。输入参数start_time和end_time采用"年-月-日 时间"格式，其中时间采用clock格式。查询最大时间跨度为1天，超出跨度约束，根据查询起始时间将结束时间自动转换为极限边界进行查询。例如： ``` gaussdb=# SELECT * FROM gs_recent_barrier_buffer_info('2024-01-15 23:27:50', '2024-01-15 23:28:00'); timestamp | lsn | csn | standard_time ------------+-------------------+----------+--------------------- 1705332470 | 00000000/15FFBBA0 | 41020421 | 2024-01-15 23:27:50 1705332471 | 00000000/15FFBDF0 | 41020422 | 2024-01-15 23:27:51 1705332472 | 00000000/15FFC058 | 41020423 | 2024-01-15 23:27:52 1705332472 | 00000000/15FFC0F8 | 41020424 | 2024-01-15 23:27:52 1705332473 | 00000000/15FFC348 | 41020425 | 2024-01-15 23:27:53 1705332474 | 00000000/15FFC598 | 41020426 | 2024-01-15 23:27:54 1705332475 | 00000000/15FFC638 | 41020427 | 2024-01-15 23:27:55 1705332476 | 00000000/15FFC888 | 41020428 | 2024-01-15 23:27:56 1705332476 | 00000000/15FFDC80 | 41020433 | 2024-01-15 23:27:56 1705332477 | 00000000/15FFDD20 | 41020434 | 2024-01-15 23:27:57 1705332478 | 00000000/15FFDF70 | 41020435 | 2024-01-15 23:27:58 1705332479 | 00000000/15FFE1D8 | 41020436 | 2024-01-15 23:27:59 1705332480 | 00000000/15FFE278 | 41020437 | 2024-01-15 23:28:00 1705332480 | 00000000/15FFE4C8 | 41020438 | 2024-01-15 23:28:00 (14 rows) ``` - gs_show_obs_media_files(slot_name cstring, src cstring, offset int32, limit int32) 描述：根据用户输入的归档槽（slot_name）和OBS目录地址（src），查询OBS文件列表。 返回值类型：records 说明：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限。Offset为查询结果偏移，limit为输出最大行数，查询src下所有文件。例如： ``` gaussdb=# SELECT gs_show_obs_archive_files('ssh','dn1/pg_xlog',0, 5); gs_show_obs_archive_files --------------------------------------------------------------------------------------------- (wstdist_ssh/archive/dn1/pg_xlog/000000010000000000000007_00_01_00000004_00000002_00000000) (wstdist_ssh/archive/dn1/pg_xlog/000000010000000000000007_00_01_00000103_00000003_00000000) (wstdist_ssh/archive/dn1/pg_xlog/000000010000000000000007_01_01_00000004_00000002_00000000) (wstdist_ssh/archive/dn1/pg_xlog/000000010000000000000007_01_01_00000103_00000003_00000000) (wstdist_ssh/archive/dn1/pg_xlog/000000010000000000000007_02_01_00000004_00000002_00000000) (5 rows) ``` - gs_upload_obs_media_file(slot_name cstring, src cstring, dest cstring, is_forced bool) 描述：根据用户输入的归档槽（slot_name）、上传文件原地址（src）、OBS地址（dest）和是否强制上传（is_forced），上传OBS文件。 返回值类型：void 说明：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限。原文件目录仅允许为$GAUSSLOG目录。例如： ``` gaussdb=# SELECT * FROM gs_upload_obs_archive_file('ssh', '/data/gauss/log/stwang/test/000000010000000000000007_02_01_00000004_00000002_00000000', 'dn1/pg_xlog/000000010000000000000019_02_01_00000000_00000000_00000003', true); gs_upload_obs_archive_file ---------------------------- (1 row) ``` - gs_download_obs_media_file(slot_name cstring, src cstring, dest cstring) 描述：根据用户输入的归档槽（slot_name）、下载原地址（src）和本地目标地址（dest），下载OBS文件。 返回值类型：void 说明：调用该函数的用户需要具有SYSADMIN权限或具有OPRADMIN权限。下载目录仅允许为$GAUSSLOG目录。例如： ``` gaussdb=# SELECT * FROM gs_download_obs_archive_file('ssh','dn1/pg_xlog/000000010000000000000019_02_01_00000000_00000000_00000003','/data/gauss/log/stwang/test'); gs_download_obs_archive_file ------------------------------ (1 row) ```