Automated Backups & Restoration

Relevant source files

The following files were used as context for generating this wiki page:

• internal/app/backup.go
• internal/app/backup_test.go
• internal/app/app.go
• README.md
• internal/app/calendar.go
• internal/app/app_test.go

GoCasa protects the primary SQLite database (app.db) through an automated backup system that handles daily rotations and safety snapshots during schema migrations. The system ensures data persistence by copying the database to a dedicated directory within the configured data volume.

Sources: README.md:38-40, internal/app/backup.go:1-10

Backup Mechanisms

GoCasa implements three distinct backup triggers to ensure data safety: nightly schedules, startup checks, and pre-migration safety points.

Nightly Backups

The system performs a backup every day at 03:00 in the household's configured time zone (TZ). It uses the SQLite VACUUM INTO command to create a clean, defragmented copy of the database. The system retains only the newest 14 daily backups.

Sources: README.md:38-40, internal/app/backup.go:58-81

Startup Backups

When the GoCasa binary starts, it checks the age of the newest existing daily backup. If the newest backup is more than 24 hours old, or if no backups exist, the system takes a backup immediately before proceeding.

Sources: README.md:38-41, internal/app/backup.go:68-76, internal/app/backup_test.go:48-73

Pre-Migration Backups

Before applying database migrations, GoCasa writes a safety backup named app-YYYYMMDD-pre-vN.db, where N is the schema version before the upgrade. If this backup fails, the application refuses to start to prevent unprotected data modification. Unlike daily backups, pre-migration backups are never automatically pruned.

Sources: README.md:46-51, internal/app/app.go:65-71, internal/app/backup.go:43-46

Architecture and Data Flow

The backup logic is integrated into the application initialization and scheduling lifecycle.

The diagram shows the logic flow from application startup through migration checks to scheduled maintenance.
Sources: internal/app/app.go:65-80, internal/app/backup.go:15-81

Data Storage Structure

Backups are stored in the backups/ subdirectory of the DATA_DIR.

File Pattern	Purpose	Pruning Policy
app-YYYYMMDD.db	Standard daily backup.	Kept for 14 days.
app-YYYYMMDD-pre-vN.db	Rollback point created before migration.	Never pruned.
*.tmp	Temporary file used during the VACUUM INTO process.	Deleted after success or on retry.

Sources: README.md:46-51, internal/app/backup.go:15-46

Restoration Procedure

Restoration is a manual process that requires stopping the GoCasa service to ensure file integrity.

1. Stop the container: Run docker compose stop.
2. Clear active state: Delete app.db-wal and app.db-shm files if they exist, as they correspond to the current session of the primary database.
3. Replace database: Move the existing app.db aside and copy the chosen backup file to app.db.
4. Restart service: Run docker compose start.

Sources: README.md:42-45

Technical Implementation Details

The system uses specific Go functions to manage file operations and scheduling.

Key Functions

Function	Description	Source
backup()	Executes VACUUM INTO to a temporary file, updates timestamps, renames it to the final destination, and triggers pruning.	backup.go:15-39
dailyBackups()	Returns a sorted list of daily backup files using a glob pattern.	backup.go:43-46
next0300()	Calculates the next occurrence of 03:00 relative to the current time and time zone.	backup.go:84-91
startBackups()	Coordinates the startup stale-check and registers the nightly task with the Scheduler.	backup.go:58-81

Code Example: Backup Logic

func backup(ctx context.Context, d *sql.DB, dir, name string, now time.Time) error {
	// ... directory creation ...
	dst := filepath.Join(dir, name)
	tmp := dst + ".tmp"
	// VACUUM INTO refuses an existing file
	if _, err := d.ExecContext(ctx, "VACUUM INTO ?", tmp); err != nil {
		return fmt.Errorf("backup %s: %w", name, err)
	}
	os.Chtimes(tmp, now, now)
	return os.Rename(tmp, dst)
}

Sources: internal/app/backup.go:15-30

Summary

The Automated Backup & Restoration system provides a hands-off safety net for household data. By combining scheduled snapshots with mandatory pre-migration checkpoints, GoCasa ensures that the SQLite database remains recoverable even after hardware failures or unsuccessful software upgrades. Restoration requires simple file-system operations while the service is offline.