Developer's Guide to Utilizing the Bench Restore Feature in Empress

Developers
1

Introduction

Welcome to the comprehensive developer guide on how to use the Bench Restore feature in Empress. This guide will delve into the technical aspects of one of the most critical features of Empress, the restore command, which allows developers to restore an existing site to a previous state.

The Bench Restore Functionality

At its core, Bench Restore is a command-line utility that utilizes the bench restore command to restore a Empress site to a specific database and file restore point. It is an invaluable tool for developers, enabling them to revert changes and troubleshoot issues effectively.

Its primary functionality revolves around restoring the site’s database from a specified local file. It’s essential to note that the file must be either an sql.gz or sql extension for the database and tar or tgz extension for public and private file backups.

The Implementation of Bench Restore

The Bench Restore command is executed via the terminal. Here’s the basic usage:

bench restore [OPTIONS] SQL_FILE_PATH

Arguments

  • SQL_FILE_PATH: This is the path to the database source file. This path may be relative from the bench directory root, or the sites folder, or it may be an absolute path.

Options

The restore command has multiple options to customize the restore process:

  • --db-root-username: Root username for MariaDB or Postgres
  • --db-root-password: Root password for MariaDB or Postgres
  • --db-name: Database name for site in case it is a new one
  • --admin-password: Administrator password for new site
  • --install-app: Install app after installation
  • --with-public-files: Restores the public files of the site, given path to its archive file
  • --with-private-files: Restores the private files of the site, given path to its archive file

Flags

  • --force: This flag is used to ignore the site downgrade warning, if applicable. It’s crucial to note that this is not recommended unless you’re fully aware of the consequences.

Using the Bench Restore Feature

Here are some examples of how to use the restore command effectively:

  1. To restore a site with files:
 bench --site {site} restore {path/to/database/file} 
      --with-public-files {path/to/public/archive} 
      --with-private-files {path/to/private/archive}
  1. To bypass DBMS root interactive prompt by passing values in options:
bench --site {site} restore {path/to/database/file} 
   --db-root-username {db-user} 
   --db-root-password {db-pass}
  1. To specify a new app to install after site restore:
bench --site {site} restore {path/to/database/file} 
   --install-app {app}
  1. To specify a custom database name for the restored site:
bench --site {site} restore {path/to/database/file} 
   --db-name {custom-db-name}
  1. To reset the admin password for the restored site:
bench --site {site} restore {path/to/database/file} 
   --admin-password {admin-pass}

Conclusion

In conclusion, the Bench Restore feature is a crucial tool for developers working with Empress. It allows for effective site restoration, debugging, and customization. By understanding and effectively using this tool, developers can significantly enhance their productivity and the robustness of their applications.