Repository files navigation

A package to restore a database backup created by thespatie/laravel-backup package.

The package requires Laravel v10.17 or higher and PHP 8.2 or higher.

You can install the package via composer:

composer require wnx/laravel-backup-restore

Optionally, you can publish the config file with:

php artisan vendor:publish --tag="backup-restore-config"

This is the contents of the published config file:

return [/**     * Health checks are run after a given backup has been restored.     * With health checks, you can make sure that the restored database contains the data you expect.     * By default, we check if the restored database contains any tables.     *     * You can add your own health checks by adding a class that extends the HealthCheck class.     * The restore command will fail, if any health checks fail.     */'health-checks' => [        \Wnx\LaravelBackupRestore\HealthChecks\Checks\DatabaseHasTables::class,    ],];

To restore a backup, run the following command.

php artisan backup:restore

You will be prompted to select the backup you want to restore and whether the encryption password from the configuration should be used, to decrypt the backup.

The package relies on an existingconfig/backup.php-file to find your backups, encryption/decryption key and database connections.

Note
By default, the name of a backup equals the value of the APP_NAME-env variable. The restore-commands looks for backups in a folder with that backup name. Make sure that the APP_NAME-value is correct in the environment you're running the command.

You can pass disk, backup, database connection and decryption password to the Artisan command directly, to speed things up.

php artisan backup:restore    --disk=s3    --backup=latest     --connection=mysql     --password=my-secret-password     --reset

Note that we usedlatest as the value for--backup. The command will automatically download the latest available backup and restore its database.

The filesystem disk to look for backups. Defaults to the first destination disk configured inconfig/backup.php.

Relative path to the backup file that should be restored.Uselatest to automatically select latest backup.

Database connection to restore backup. Defaults to the first source database connection configured inconfig/backup.php.

Password used to decrypt a possible encrypted backup. Defaults to encryption password set inconfig/backup.php.

Reset the database before restoring the backup. Defaults tofalse.

The command asks for confirmation before starting the restore process. If you run thebackup:restore-command in an environment where you can't confirm the process (for example through a cronjob), you can use the--no-interaction-option to bypass the question.

php artisan backup:restore    --disk=s3    --backup=latest     --connection=mysql     --password=my-secret-password     --reset    --no-interaction

After the backup has been restored, the package will run a series of health checks to ensure that the database has been imported correctly.By default, the package will check if the database has tables after the restore.

You can add your own health checks by creating classes that extendWnx\LaravelBackupRestore\HealthChecks\HealthCheck-class.

namespaceApp\HealthChecks;useWnx\LaravelBackupRestore\PendingRestore;useWnx\LaravelBackupRestore\HealthChecks\HealthCheck;class MyCustomHealthCheckextends HealthCheck{publicfunctionrun(PendingRestore$pendingRestore):Result    {$result = Result::make($this);// We assume that your app generates sales every day.// This check ensures that the database contains sales from yesterday.$newSales = \App\Models\Sale::query()            ->whereBetween('created_at', [now()->subDay()->startOfDay(),now()->subDay()->endOfDay()            ])            ->exists();// If no sales were created yesterday, we consider the restore as failed.if ($newSales ===false) {return$result->failed('Database contains no sales from yesterday.');        }return$result->ok();    }}

Add your health check to thehealth-checks-array in theconfig/laravel-backup-restore.php-file.

'health-checks' => [        \Wnx\LaravelBackupRestore\HealthChecks\Checks\DatabaseHasTables::class,        \App\HealthChecks\MyCustomHealthCheck::class,    ],

In addition to running thebackup:restore command manually, you can also use this package to regularly test the integrity of your backups using GitHub Actions.

The GitHub Actions workflow below can either be triggered manually through the Github UI (workflow_dispatch-trigger) or runs automatically on a schedule (schedule-trigger).The workflow starts an empty MySQL database, clones your Laravel application, sets up PHP, installs composer dependencies and sets up the Laravel app. It then downloads, decrypts and restores the latest available backup to the MySQL database available in the GitHub Actions workflow run. The database is wiped, before the workflow completes.

Note that we pass a couple of env variables to thebackup:restore command. Most of those values have been declared asGitHub Action secrets. By using secrets our AWS keys are not being leaked in the workflow logs.

If the restore command fails, the entire workflow will fail, you and will receive a notification from GitHub.This is obviously just a starting point. You can add more steps to the workflow, to – for example – notify you through Slack, if a restore succeeded or failed.

name:Validate Backup Integrityon:# Allow triggering this workflow manually through the GitHub UI.workflow_dispatch:schedule:# Run workflow automatically on the first day of each month at 14:00 UTC# https://crontab.guru/#0_14_1_*_*    -cron:"0 14 1 * *"jobs:restore-backup:name:Restore backupruns-on:ubuntu-latestservices:# Start MySQL and create an empty "laravel"-databasemysql:image:mysql:latestenv:MYSQL_ROOT_PASSWORD:passwordMYSQL_DATABASE:laravelports:          -3306:3306options:--health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3steps:      -name:Checkout codeuses:actions/checkout@v3      -name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:8.2      -uses:ramsey/composer-install@v2      -run:cp .env.example .env      -run:php artisan key:generate# Download latest backup and restore it to the "laravel"-database.# By default the command checks, if the database contains any tables after the restore.# You can write your own Health Checks to extend this feature.      -name:Restore Backuprun:php artisan backup:restore --backup=latest --no-interactionenv:APP_NAME:'Laravel'DB_PASSWORD:'password'AWS_ACCESS_KEY_ID:${{ secrets.AWS_ACCESS_KEY_ID }}AWS_SECRET_ACCESS_KEY:${{ secrets.AWS_SECRET_ACCESS_KEY }}AWS_DEFAULT_REGION:${{ secrets.AWS_DEFAULT_REGION }}AWS_BACKUP_BUCKET:${{ secrets.AWS_BACKUP_BUCKET }}BACKUP_ARCHIVE_PASSWORD:${{ secrets.BACKUP_ARCHIVE_PASSWORD }}# Wipe database after the backup has been restored.      -name:Wipe Databaserun:php artisan db:wipe --no-interactionenv:DB_PASSWORD:'password'

The package comes with an extensive test suite.To run it, you need MySQL, PostgreSQL and sqlite installed on your system.

composertest

For MySQL and PostgreSQL the package expects that alaravel_backup_restore database exists and is accessible to aroot-user without using a password.

You can change user, password and database by passing ENV-variables to the shell command tp run the tests … or change the settings locally to your needs. SeeTestCase for details.

You can invoke thebackup:restore command usingtestbench to test the command like you would in a Laravel application.

vendor/bin/testbench backup:restore --disk=remote

Please seeCHANGELOG for more information on what has changed recently.

Please seeCONTRIBUTING for details.

Please reviewour security policy on how to report security vulnerabilities.

• Stefan Zweifel
• All Contributors

The MIT License (MIT). Please seeLicense File for more information.