Backup & Restore

Learn how to backup and restore your nself database with automatic versioning, point-in-time recovery, and safe rollback procedures.

Overview

nself provides comprehensive backup and restore capabilities to protect your data and enable safe database operations. Every migration automatically creates a backup, and you can create manual backups at any time.

Automatic Backups

Backups are automatically created during:

Migration operations - Before applying any migration
Database updates - When running nself db update
Schema changes - When running nself db run

Backups are stored in bin/dbsyncs/ with timestamps:

bin/dbsyncs/
├── 2025-08-06_14-30-00/
│   ├── backup.sql
│   └── metadata.json
└── 2025-08-06_15-45-30/
    ├── backup.sql
    └── metadata.json

Manual Backup

Create a manual backup at any time:

# Create a timestamped backup
nself db backup

# Backup with custom name
nself db backup --name before-major-change

Restore Operations

Restore to Previous State

Quickly revert to the most recent backup:

# Restore to last backup
nself db revert

# This is useful after a failed migration or incorrect data change

Restore from Specific Backup

Restore from a specific backup file:

# List available backups
ls bin/dbsyncs/

# Restore from specific backup
nself db restore bin/dbsyncs/2025-08-06_14-30-00/backup.sql

Database Status

Check your database and backup status:

# View database status
nself db status

# Example output:
# Database Status
# Schema file: schema.dbml
#   Hash: b4dc5d616f59...
# Migrations:        1
# Latest migrations:
#   - 1_init
# Backups:        3
# PostgreSQL: Running

Best Practices

Test restore procedures - Regularly verify backups are restorable
Automate backup verification - Check backup integrity automatically
Store backups securely - Encrypt sensitive backups
Monitor backup success - Alert on backup failures
Version control backup scripts - Track backup procedure changes

Production Backup Strategy

For production environments:

# Set up automated daily backups via cron
0 2 * * * cd /path/to/project && nself db backup --name "daily-$(date +%Y%m%d)"

# Keep only last 30 backups
0 3 * * * find bin/dbsyncs -type d -mtime +30 -exec rm -rf {} +

Troubleshooting

Backup Fails with Permission Error

# Fix permissions
chmod 755 bin/dbsyncs
chown -R $(whoami) bin/dbsyncs

Restore Fails with Connection Error

# Ensure PostgreSQL is running
nself up postgres

# Wait for PostgreSQL to be ready
sleep 5

# Retry restore
nself db revert