Child pages
  • UAPI Functions - Backup::restore_databases
Skip to end of metadata
Go to start of metadata

Description

This function restores a database's backup files.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Backup/restore_databases?backup=/home/cpuser/cpuser_db1.sql.gz&verbose=1&timeout-3600


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Restore the database's backup files.
$Backup_restore_database = $cpanel->uapi(
    'Backup', 'restore_databases'
    array(
        'backup'                 => '/home/cpuser/cpuser_db1.sql.gz',
        'verbose'                => '1',
        'timeout'                => '3600',
    )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Restore the database's backup files.
my $Backup_restore_databases = $cpliveapi->uapi(
    'Backup', 'restore_databases',
    {
        'backup'                 => '/home/cpuser/cpuser_db1.sql.gz',
        'verbose'                => '1',
        'timeout'                => '3600',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username Backup restore_databases backup=/home/cpuser/cpuser_db1.sql.gz verbose=1 timeout=3600


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
   {
          "errors" : null,
          "metadata" : {},
          "data" : {
			 "log_id" : "2019-08-13T15:10:07Z.1"
             "log_path" : "/home/cptest/logs/restoredb/2019-08-13T15:10:07Z.1.log",
          },
          "messages" : [
             "No virus detected in upload "cpuser_db1.sql.gz".",
			 "The system is extracting the archive "/home/cpsuer/tmp/cpuser_db1.slq.gz	
             "The system will attempt to restore from the file cpuser_db1.sql.gz to the database: cpuser_db1.sql.gz",
             "The system is starting to restore "cpuser_db1.sql.gz".",
             "The system successfully restored the database "cpuser_db1" from the backup file "cpuser_db1.sql.gz"."
          ],
          "status" : 1,
          "warnings" : null
       },


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

Note:

You must pass either the file or backup parameter.


ParameterTypeDescriptionPossible valuesExample
file string

The database backup file to upload and restore. 

Pass this file in a multipart/form-data structure. For more information about this structure, read Mozilla's POST Method documentation.

Important:

  • Only pass this parameter to upload files that don't already exist on the server.
  • You can't pass this parameter on the command line.

Note:

To upload multiple database backup files, increment the parameter name. For example: file-1file-2file-3.

A valid filename, that uses the .sql or .sql.gz extensions.

 Click to view...
------WebKitFormBoundaryvb6rQ3QyCo6yC2w5
Content-Disposition: form-data; name="file-1"; file="example.sql.gz"
Content-Type: application/x-gzip

------WebKitFormBoundaryvb6rQ3QyCo6yC2w5--
backupstring

The database backup file to restore. 

Important:

Only pass this parameter to restore files already on the server.

Note:

To restore multiple database backup files, increment the parameter name. For example: backup-1backup-2backup-3.

A valid filepath that uses the .sql or .sql.gz extensions. 


/home/user/user_db1.sql.gz
verbose Boolean

Whether to return additional information from the /usr/local/cpanel/logs/cpbackup log file.

This parameter defaults to 0.

  • 1 — Return.
  • 0  – Don't return.
1 
timeout integer

The maximum number of seconds to try to restore the file.

This parameter defaults to 7200

An integer value.3600 

Returns

ReturnTypeDescriptionPossible valuesExample
log_idstring

The log file's restoration identification (ID). 

The system uses the backup restoration's date to create this ID.

The backup restoration date in YYYY-MM-DDTHH:mm:SS.rev human-readable format, where:

  • YYYY represents the year.
  • MM represents the month.
  • DD represents the date.
  • HH represents the hour.
  • mm represents the minute.
  • SS represents the second.
  • rev represents the log's revision during the current backup restoration.

2019-08-13T15:10:07Z.1

log_pathstringThe log file where the system recorded the backup restoration.A valid filepath./home/cptest/logs/restoredb/2019-08-13T15:10:07Z.1.log
messagesarray of stringsAn array of statements about the database's restoration.An array of strings that describe the restoration's status. 


 Click to view...
The system successfully restored the database 'user_db1' from the backup file 'user_db1.sql.gz'