Backup & Restore

Updated for nself v0.4.8

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

v0.4.8: Environment-Aware Backups

* Per-environment backups: Separate backup directories for dev, staging, prod
* Deployment rollback: nself deploy rollback to revert deployments
* Environment export: nself env export to backup environment configurations

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
Deployments - Before nself deploy operations

Backups are stored in bin/dbsyncs/ with timestamps:

bin/dbsyncs/
├── 2026-01-24_14-30-00/
│   ├── backup.sql
│   └── metadata.json
└── 2026-01-24_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

Environment Export/Import

Backup and restore environment configurations:

# Export environment configuration
nself env export staging --output staging-env.tar.gz

# Import environment configuration
nself env import staging-env.tar.gz

# This includes:
# - .env file
# - .env.secrets file (if exists)
# - server.json (if exists)

Deployment Rollback

Roll back to previous deployment:

# Rollback if deployment fails
nself deploy rollback

# View deployment history
nself deploy logs

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 {} +

# Before major deployments, create named backup
nself db backup --name "pre-deploy-v1.2.0"

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 start postgres

# Wait for PostgreSQL to be ready
sleep 5

# Retry restore
nself db revert