gs_basebackup

Background

After openGauss is deployed, problems and exceptions may occur during database running. gs_basebackup, provided by openGauss, is used to perform basic physical backup. gs_basebackup copies the binary files of the database on the server using a replication protocol. To remotely execute gs_basebackup, you need to use the system administrator account. gs_basebackup supports hot backup and does not support compressed backup.

NOTE:

• gs_basebackup supports only full backup.

• gs_basebackup supports hot backup and does not support compressed backup.

• gs_basebackup cannot back up tablespaces containing absolute paths on the same server. This is because the absolute path is unique on the same machine, and brings about conflicts. However, it can back up tablespaces containing absolute paths on different machines.

• If the functions of incremental checkpoint and dual-write are enabled, gs_basebackup also backs up dual-write files.

• If the pg_xlog directory is a soft link, no soft link is created during backup. Data is directly backed up to the pg_xlog directory in the destination path.

• If the backup permission is revoked during the backup, the backup may fail or the backup data may be unavailable.

• Currently, openGauss does not support version upgrade.

Prerequisites

• The openGauss database can be connected.

• User permissions are not revoked during the backup.

• In the pg_hba.conf file, the replication connection is allowed and the connection is established by a system administrator.

• If the Xlog transmission mode is stream, the number of max_wal_senders must be configured to at least one.

• If the Xlog transmission mode is fetch, the wal_keep_segments parameter must be set to a large value so that logs are not removed before the backup ends.

• During the restoration, backup files exist in the backup directory on all the nodes. If backup files are lost on any node, copy them to it from another node.

Syntax

• Display help information.

  gs_basebackup -? | --help
  

• Display version information.

  gs_basebackup -V | --version
  

Parameter Description

The gs_basebackup tool can use the following types of parameters:

• -D directory

  Directory for storing backup files. This parameter is mandatory.

• Common parameters

  • -c, --checkpoint=fast|spread

    Sets the checkpoint mode to fast or spread (default).

  • -l, --label=LABEL

    Adds tags for the backup.

  • -P, --progress

    Enables the progress report.

  • -v, --verbose

    Enables the verbose mode.

  • -V, --version

    Prints the version and exits.

  • -?, --help

    Displays gs_basebackup command parameters.

• Connection parameters

  • -h, --host=HOSTNAME

    Specifies the host name of the machine on which the server is running or the directory for the Unix-domain socket.

  • -p, --port=PORT

    Specifies the port number of the database server.

    You can modify the default port number using this parameter.

  • -U, --username=USERNAME

    Specifies the user that connects to the database.

  • -s, --status-interval=INTERVAL

    Specifies the time for sending status packets to the server, in seconds.

  • -w,--no-password

    Never issues a password prompt.

  • -W, --password

    Issues a password prompt when the -U parameter is used to connect to a local or remote database.

Example

gs_basebackup -D /home/test/trunk/install/data/backup -h 127.0.0.1 -p 21233
INFO:  The starting position of the xlog copy of the full build is: 0/1B800000. The slot minimum LSN is: 0/1B800000.

Restoring Data from Backup Files

If a database is faulty, restore it from backup files. gs_basebackup backs up the database in binary mode. Therefore, you can directly copy and replace the original files or start the database on the backup database.

NOTE:

• If the current database instance is running, a port conflict may occur when you start the database from the backup file. In this case, you need to modify the port parameter in the configuration file or specify a port when starting the database.

• If the current backup file is a primary/standby database, you may need to modify the replication connections between the primary and standby databases. That is, replconninfo1 and replconninfo2 in the postgre.conf file.

To restore the original database, perform the following steps:

1. Stop the database server. For details, see Administrator Guide.
2. Copy the original database and all tablespaces to another location for future use.
3. Delete all or part of the files from the original database.
4. Use the database system user rights to restore the required database files from the backup.
5. If a link file exists in the database, modify the link file so that it can be linked to the correct file.
6. Restart the database server and check the database content to ensure that the database is restored to the required status.

NOTE:

• Incremental restoration from backup files is not supported.

• After the restoration, check that the link file in the database is linked to the correct file.