- How do I restore a database backup made with spatie/laravel-backup?
- Install wnx/laravel-backup-restore and run php artisan backup:restore. The command lists the backups it finds on your configured disk, asks which one to restore and whether the encryption password from config/backup.php should be used, then downloads, decrypts and imports the dump into your database. Afterwards, health checks run against the restored database so you know the import actually produced the data you expect.
- How do I install and configure wnx/laravel-backup-restore?
- Run composer require wnx/laravel-backup-restore, then optionally publish the config file with php artisan vendor:publish --tag=backup-restore-config. The package does not define its own connections, disks or keys; it reads your existing config/backup.php from spatie/laravel-backup. Make sure APP_NAME matches the backup folder name on disk, because that mismatch is the most common setup failure.
- Which Laravel and PHP versions does wnx/laravel-backup-restore support?
- It requires Laravel 12 or higher and PHP 8.4 or higher. Version 1.8.0 dropped PHP 8.2/8.3 and Laravel 10/11, and v2.0.0 is a major release, so re-check composer.json and UPGRADING.md before installing on an older codebase. If your application is still on Laravel 11, treat this as part of the framework upgrade rather than an independent task.
- How are encrypted backups decrypted during a restore?
- The command prompts you to confirm whether the archive password configured in config/backup.php should be used, and decrypts the downloaded zip before importing it. The same configuration that spatie/laravel-backup uses to encrypt is reused, so no extra key management is needed. If decryption fails, the restore aborts before the database is touched.
- Can I restore a backup stored on S3 or another remote disk?
- Yes. Restores resolve the disks defined in your spatie/laravel-backup config, so backups on S3 or any other Flysystem disk work as long as credentials are available at runtime. The archive is downloaded locally first and then imported into the configured database connection. Multiple database connections are supported, so you can target a staging or local database instead of production.
- What are post-restore health checks and how do I add a custom one?
- Health checks run after the import and make the command fail if the restored database does not look right. By default DatabaseHasTables verifies that at least one table exists. You can add your own checks by extending the HealthCheck class and listing the classes under health-checks in the published backup-restore config.
- Is php artisan backup:restore safe to run in production, and what does --reset do?
- The --reset option drops existing tables before importing the dump, which is destructive and should not be routine in production. Version 2.0.0 added a pre-flight check before the reset, but that is a safety net rather than a policy, so keep restores limited to non-production environments or require break-glass approval. Always confirm the target database connection before running the command.
- Why does the restore fail because the mysql, psql or sqlite3 client is missing?
- The package delegates the import to the native database client, so the binary must exist in the environment running the command. In v2 the client is checked before the backup is downloaded, turning an expensive late failure into an early, cheap one. Docker images that only ship the PHP runtime need the client installed at build time. Note that v2 also stopped building a shell command string, so any wrapper or custom option that assumed shell semantics needs review.
- What breaking changes are in v2.0.0 and should I upgrade from 1.x?
- v2.0.0 is a major release with changes documented in UPGRADING.md, most notably that the import is no longer assembled into a command string and piped through /bin/sh -c but passed as an argument array to the database client. That removes the command injection risk present in 1.x, so new work should require at least 2.0.0 and never deploy 1.x. Read UPGRADING.md in full and diff published overrides, wrapper scripts and dump.add_extra_option values before bumping an existing install.
- Is wnx/laravel-backup-restore maintained, and what are the alternatives?
- It is a small package by Stefan Zweifel with a single maintainer and no vendor backing, so pin the exact version, control upgrades through Renovate and keep a documented fork or shell-script contingency. The nearest alternatives are importing a dump manually with mysql or psql, or writing your own Artisan command around spatie/laravel-backup. Because the package is an Artisan-layer tool with no production runtime footprint, removing it is a one-line Composer change.