wheels db restore
Restore a database from a dump file.
Synopsis
wheels db restore <file> [--datasource=<name>] [--environment=<env>]
[--clean] [--force] [--compressed]
Description
The wheels db restore
command imports a database dump file created by wheels db dump
or other database export tools. It can handle both plain SQL files and compressed dumps.
Arguments
file
Required. Path to the dump file to restore.
wheels db restore backup.sql
Options
--datasource=
Specify which datasource to restore to. If not provided, uses the default datasource.
wheels db restore backup.sql --datasource=myapp_dev
--environment=
Specify the environment to use. Defaults to the current environment.
wheels db restore backup.sql --environment=staging
--clean
Drop existing database objects before restore.
wheels db restore backup.sql --clean
--force
Skip confirmation prompts.
wheels db restore backup.sql --force
--compressed
Indicate the file is compressed. Auto-detected for .gz files.
wheels db restore backup.sql.gz --compressed
Examples
Basic Restore
wheels db restore backup.sql
Restore Compressed Backup
# Auto-detects compression from .gz extension
wheels db restore backup.sql.gz
# Or explicitly specify
wheels db restore backup.sql --compressed
Clean Restore
Drop existing objects first:
wheels db restore backup.sql --clean
Force Restore
Skip confirmation in scripts:
wheels db restore backup.sql --force
Restore to Different Environment
wheels db restore prod-backup.sql --environment=staging --force
Safety Features
Confirmation Required: Prompts before overwriting data
Production Warning: Extra warning for production environments
File Validation: Checks file exists before starting
Database-Specific Behavior
MySQL/MariaDB
Uses
mysql
clientHandles large files efficiently
Preserves character sets
PostgreSQL
Uses
psql
clientSupports custom formats from pg_dump
Handles permissions and ownership
SQL Server
Uses
sqlcmd
clientLimited support for complex backups
Best with SSMS for full restores
H2
Uses RUNSCRIPT command
Native support for compressed files
Fast for embedded databases
Common Workflows
Development Reset
# Get fresh production data
wheels db dump --environment=production --output=prod-latest.sql
wheels db restore prod-latest.sql --environment=development --clean
Disaster Recovery
# Restore from latest backup
wheels db restore backups/daily-20231204.sql.gz --force
Environment Cloning
# Clone staging to test
wheels db dump --environment=staging --output=staging-snapshot.sql
wheels db restore staging-snapshot.sql --environment=test --clean
Important Warnings
Data Loss
Restoring overwrites existing data
Always backup current database first
Use
--clean
carefully
Version Compatibility
Ensure dump is from compatible database version
Check character set compatibility
Verify schema matches application version
Large Files
Monitor disk space during restore
Consider using
--compressed
dumpsMay need to adjust timeout settings
Pre-Restore Checklist
Backup current database
wheels db dump --output=pre-restore-backup.sql
Verify dump file
ls -lh backup.sql head -n 20 backup.sql # Check format
Check disk space
df -h # Ensure enough space
Stop application (if needed)
server stop
Troubleshooting
"Access denied"
Check database user has CREATE/DROP permissions
Verify credentials in datasource
"File not found"
Check file path is correct
Use absolute paths for clarity
"Syntax error"
Verify dump file isn't corrupted
Check database version compatibility
Ensure correct database type
Restore Hangs
Large databases take time
Check database server resources
Monitor with
wheels db shell
in another terminal
Character Set Issues
Ensure database charset matches dump
Check connection encoding settings
Best Practices
Test restores regularly - Verify backups work
Document source - Note where dumps came from
Version control - Track schema version with dumps
Automate testing - Script restore verification
Secure dumps - Protect sensitive data in dumps
Recovery Scenarios
Partial Restore
If full restore fails:
# Extract specific tables from dump
grep -E "(CREATE TABLE|INSERT INTO) users" backup.sql > users-only.sql
wheels db restore users-only.sql
Manual Recovery
Use database shell for control:
wheels db shell
# Then manually run SQL from dump file
Related Commands
wheels db dump
- Create database dumpswheels db reset
- Alternative fresh startwheels db shell
- Manual restore controlwheels db status
- Verify after restore
Last updated
Was this helpful?