Backup Control Functions
Backup control functions help with online backup.
pg_create_restore_point(name text)
Description: Creates a named point for performing a restore (requires an administrator role).
Return type: text
Note: pg_create_restore_point creates a named transaction log record that can be used as a restoration target, and returns the corresponding transaction log location. The given name can then be used with recovery_target_name to specify the point up to which restoration will proceed. Avoid creating multiple restoration points with the same name, since restoration will stop at the first one whose name matches the restoration target.
pg_current_xlog_location()
Description: Obtains the write position of the current transaction log.
Return type: text
Note: pg_current_xlog_location displays the write position of the current transaction log in the same format as those of the previous functions. Read-only operations do not require SYSADMIN permissions.
pg_current_xlog_insert_location()
Description: Obtains the insert position of the current transaction log.
Return type: text
Note: pg_current_xlog_insert_location displays the insert position of the current transaction log. The insertion point is the logical end of the transaction log at any instant, while the write location is the end of what has been written out from the server's internal buffers. The write position is the end that can be detected externally from the server. This operation can be performed to archive only some of completed transaction log files. The insert position is mainly used for commissioning the server. Read-only operations do not require SYSADMIN permissions.
gs_current_xlog_insert_end_location()
Description: Obtains the insert position of the current transaction log.
Return type: text
Note: gs_current_xlog_insert_end_location displays the insert position of the current transaction log.
pg_start_backup(label text [, fast boolean ])
Description: Starts to perform online backup. (An administrator, replication role, or O&M administrator must enable operation_mode.) Label strings starting with gs_roach are reserved and can be used only by the internal backup tool GaussRoach.
Return type: text
Note: pg_start_backup receives a user-defined backup label (usually the name of the position where the backup dump file is stored). This function writes a backup label file to the data directory of the database cluster and then returns the starting position of backed up transaction logs in text mode. This function must be used together with pg_stop_backup(). If this function is called independently, backup_label remains. During WAL replay, the checkpoint is read based on backup_label. If the WAL file corresponding to the checkpoint has been reclaimed, the database cannot be started.
1 2 3 4 5 |
gaussdb=# SELECT pg_start_backup('label_goes_here',true); pg_start_backup ----------------- 0/3000020 (1 row) |
pg_stop_backup()
Description: Completes online backup An administrator, replication role, or O&M administrator must enable operation_mode.
Return type: text
Note: pg_stop_backup deletes the label file created by pg_start_backup and creates a backup history file in the transaction log archive area. The history file includes the label given to pg_start_backup, the start and end transaction log locations for the backup, and the start and end time of the backup. The return value is the backup's ending transaction log location. After the end position is calculated, the insert position of the current transaction log automatically goes ahead to the next transaction log file. The ended transaction log file can be immediately archived so that backup is complete.
pg_switch_xlog()
Description: Switches to a new transaction log file An administrator or O&M administrator must enable operation_mode.
Return type: text
Note: pg_switch_xlog moves to the next transaction log file so that the current log file can be archived (if continuous archive is used). The return value 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 switchover, pg_switch_xlog does not move but returns the start location of the transaction log file currently in use.
pg_xlogfile_name(location text)
Description: Converts the position string in a transaction log to a file name.
Return type: text
Note: pg_xlogfile_name extracts only the transaction log file name. If the given transaction log position is the transaction log file border, a transaction log file name will be returned for both the two functions. This is usually the desired behavior for managing transaction log archiving, since the preceding file is the last one that currently needs to be archived.
pg_xlogfile_name_offset(location text)
Description: Converts the position string in a transaction log to a file name and returns the byte offset in the file.
Return type: text, integer
Note: pg_xlogfile_name_offset can extract transaction log file names and byte offsets from the returned results of the preceding functions. Example:
1 2 3 4 5 6 7 |
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)
Description: Calculates the difference in bytes between two transaction log locations.
Return type: numeric
pg_cbm_start_tracked_location()
Description: Queries the start LSN parsed by CBM.
Return type: text
pg_cbm_tracked_location()
Description: Queries the LSN location parsed by CBM.
Return type: text
pg_cbm_get_merged_file(startLSNArg text, endLSNArg text)
Description: Combines CBM files within the specified LSN range into one and returns the name of the combined file.
Return type: text
Note: Only SYSADMIN or OPRADMIN can obtain the CBM combination file.
pg_cbm_get_changed_block(startLSNArg text, endLSNArg text)
Description: Combines CBM files within the specified LSN range into a table and return records of this table.
Return type: records
Note: The table columns returned by pg_cbm_get_changed_block include the start LSN, end LSN, tablespace OID, database OID, table relfilenode, table fork number, whether the table is a system catalog, whether the table is deleted, whether the table is created, whether the table is truncated, number of pages in the truncated table, number of modified pages, and list of modified page numbers.
pg_cbm_recycle_file(targetLSNArg text)
Description: Deletes the CBM files that are no longer used and returns the first LSN after the deletion.
Return type: text
pg_cbm_force_track(targetLSNArg text,timeOut int)
Description: Forcibly executes the CBM trace to the specified Xlog position and returns the Xlog position of the actual trace end point.
Return type: text
pg_enable_delay_ddl_recycle()
Description: Enables DDL delay and returns the Xlog position of the enabling point. An administrator or O&M administrator must enable operation_mode.
Return type: text
pg_disable_delay_ddl_recycle(barrierLSNArg text, isForce bool)
Description: Disables DDL delay and returns the Xlog range where DDL delay takes effect. An administrator or O&M administrator must enable operation_mode.
Return type: records
pg_enable_delay_xlog_recycle()
Description: Enables the Xlog recycling delay function for CN recovery. An administrator or O&M administrator must enable operation_mode.
Return type: void
pg_disable_delay_xlog_recycle()
Description: Disables the Xlog recycling delay function for CN recovery. An administrator or O&M administrator must enable operation_mode.
Return type: void
pg_cbm_rotate_file(rotate_lsn text)
Description: Forcibly switches the file after the CBM parses rotate_lsn. This function is called during the build process.
Return type: void
gs_roach_stop_backup(backupid text)
Description: Stops a backup started by the internal backup tool GaussRoach. It is similar to the pg_stop_backup system function but is more lightweight.
Return type: text. The content is the insertion position of the current log.
gs_roach_enable_delay_ddl_recycle(backupid name)
Description: Enables DDL delay and returns the log position of the enabling point. It is similar to the pg_enable_delay_ddl_recycle system function but is more lightweight. In addition, different backupid values can be used to concurrently open DDL statements with delay.
Return type: text. The content is the log location of the start point.
gs_roach_disable_delay_ddl_recycle(backupid text)
Description: Disables DDL delay and returns the log range where DDL delay takes effect. It is similar to the pg_enable_delay_ddl_recycle system function but is more lightweight. In addition, different backupid values can be used to concurrently disable DDL statements with delay.
Return type: records. The content is the range of logs for which DDL is delayed to take effect.
gs_roach_switch_xlog(request_ckpt bool)
Description: Switches the currently used log segment file and triggers a full checkpoint if request_ckpt is set to true.
Return type: text. The content is the location of the segment log.
gs_block_dw_io(timeout int, identifier text)
Description: Blocks doublewrite page flushing.
Parameters:
- timeout
Value range: [0,3600], in seconds. The value 0 indicates that the block duration is 0s.
- identifier
Value range: a string, supporting only uppercase letters, lowercase letters, digits, and underscores (_).
Return type: Boolean
Note: To call this function, the user must have the SYSADMIN or OPRADMIN permission. An O&M administrator must enable operation_mode.
gs_is_dw_io_blocked()
Description: Checks whether disk flushing on the current doublewrite page is blocked. If disk flushing is blocked, true is returned.
Return type: Boolean
Note: To call this function, the user must have the SYSADMIN or OPRADMIN permission. An O&M administrator must enable operation_mode.
gs_pitr_advance_last_updated_barrier()
Description: In PITR mode, forcibly updates the global maximum archived recovery point uploaded to OBS/NAS last time to the current point. No input parameter is required.
Return type: text
Note: To call this function, the user must have the SYSADMIN or OPRADMIN permission. An O&M administrator must enable operation_mode. This parameter is valid only on the first normal CN in a distributed system. The return value is the latest local maximum archived recovery point.
gs_pitr_clean_local_barrier_files('delete_timestamp')
Description: Clears locally cached barrier record files.
Value range: The delete_timestamp parameter is of the text type. It is a Linux timestamp and contains 10 characters.
Return type: text
Note: To call this function, the user must have the SYSADMIN or OPRADMIN permission. An O&M administrator must enable operation_mode. The returned result is the start timestamp of the earliest barrier file on the localhost after the deletion.
gs_get_barrier_lsn(barrier_name text)
Description: Obtains the LSN corresponding to the barrier created using a backup.
Return type: text
Note: Currently, only gs_roach_full and gs_roach_inc are supported. To call this function, the user must have the SYSADMIN or OPRADMIN permission. An O&M administrator must enable operation_mode.
gs_gbr_relation_associated_filenode(schemaName name, tableName name)
Description: Returns the relfilenode of all indexes, sequences, partitions, TOASTs, and TOAST indexes related to the input table.
Return type: records
Note: The table columns returned by gs_gbr_relation_associated_filenode include the file type relkind, namespace where the file is located, relation name corresponding to the file, OID of the database where the file is located, OID of the tablespace where the file is located, and relfilenode of the file.
pg_create_physical_replication_slot_extern(slotname text, dummy_standby bool, extra_content text, need_recycle_xlog bool)
Description: Creates an OBS or a NAS archive slot. slotname indicates the name of the archive slot or recovery slot. The primary and standby slots must use the same slot name. dummy_standby is a reserved parameter. extra_content contains some information about the archive slot. For an OBS archive slot, the format is OBS;obs_server_ip;obs_bucket_name;obs_ak;obs_sk;archive_path;is_recovery;is_vote_replicate, in which OBS indicates the archive media of the archive slot, obs_server_ip indicates the IP address of OBS, obs_bucket_name indicates the bucket name, obs_ak indicates the AK of OBS, obs_sk indicates the SK of OBS, archive_path indicates the archive path, and is_recovery specifies whether the slot is an archive slot or a recovery slot (0: archive slot; 1: recovery slot). is_vote_replicate specifies whether the voting copy is archived first. The value 0 indicates that the synchronous standby node is archived first, and the value 1 indicates that the voting copy is archived first. This column is reserved in the current version and is not adapted yet. For a NAS archive slot, the format is NAS;archive_path;is_recovery;is_vote_replicate. Compared with the OBS archive slot, the NAS archive slot does not have the OBS configuration information, while the meanings of other fields are the same.
If the media is not OBS or NAS, the OBS archive slot is used by default. The extra_content format is obs_server_ip;obs_bucket_name;obs_ak;obs_sk;archive_path;is_recovery;is_vote_replicate.
need_recycle_xlog specifies whether to recycle old archived logs when creating an archive slot. The value true indicates that old archived logs are recycled, and the value false indicates that old archived logs are not recycled.
Return type: records, including slotname and xlog_position.
Note: Users who call this function must have the SYSADMIN permission or the REPLICATION permission, or inherit permissions of the built-in role gs_role_replication. Currently, multiple archive slots cannot be created.
Examples:
Create an OBS archive slot.
In the following command, obs_server_ip, obs_bucket_name, obs_ak and obs_sk indicate the OBS IP address, bucket name, AK, and SK, respectively. gaussdb_uuid/dn1 indicates the log archive path in the OBS bucket. Replace it with the actual path as required.
1 2 3 4 5 |
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) |
Create a NAS archive slot.
In the following command, /data/nas/media/gaussdb_uuid/dn1 indicates the log archive path on the NAS. Replace it with the actual path as required.
1 2 3 4 |
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)
Description: Sets the location where OBS archived logs can be deleted. The value of delete_location is an LSN. The logs before this location have been replayed and flushed to disks and can be deleted on OBS.
Return type: xlog_file_name text, indicating the file name of the logs that can be deleted. The value of this parameter is returned regardless of whether OBS is deleted successfully.
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 )
Description: Sets the location where OBS archived logs in a specified archived slot can be deleted. The first parameter indicates the LSN. The logs before this location have been replayed and flushed to disks and can be deleted on OBS. The second parameter indicates the name of the archive slot.
Return type: xlog_file_name text, indicating the file name of the logs that can be deleted. The value of this parameter is returned regardless of whether OBS is deleted successfully.
gs_get_global_barrier_status()
Description: gs_get_global_barrier_status is used to query the latest global barrier archived in OBS.
Return type: text
global_barrier_id: globally latest barrier ID.
global_achive_barrier_id: globally latest archived barrier ID.
gs_get_global_barriers_status()
Description: gs_get_global_barriers_status is used to query the latest global barrier archived in OBS.
Return type: text
slot_name: slot name.
global_barrier_id: globally latest barrier ID.
global_achive_barrier_id: globally latest archived barrier ID.
gs_set_archive_standby_name_on_primary(text)
Description: gs_set_archive_standby_name_on_primary is used to specify the standby node for archiving. After the setting, the specified standby node performs the archive operation. In DCF mode, the standby node cannot be specified. The input is the name of a standby node, for example, dn_6002.
Return type: Boolean
The value true indicates that the setting is successful, while the value false indicates that the setting fails.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot
