Skip to main content

Backup & Upgrade

Maintain your BillManager instance with regular backups and updates.

Backing Up​

Database Backup​

Create a SQL backup of your PostgreSQL database:

docker exec -t billmanager-db-1 pg_dump -U billsuser billmanager > backup_$(date +%Y%m%d).sql

Automated Backups​

Set up a cron job for daily backups:

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * docker exec -t billmanager-db-1 pg_dump -U billsuser billmanager > /path/to/backups/billmanager_$(date +\%Y\%m\%d).sql

Backup Retention​

Keep multiple backups and clean old ones:

# Keep last 30 days of backups
find /path/to/backups -name "billmanager_*.sql" -mtime +30 -delete

Restoring from Backup​

Full Restore​

# Stop the application
docker-compose stop billmanager

# Restore the database
cat backup_20240101.sql | docker exec -i billmanager-db-1 psql -U billsuser billmanager

# Start the application
docker-compose start billmanager

Partial Restore​

For specific tables or data, edit the SQL backup to include only what you need.

Upgrading BillManager​

Standard Upgrade​

# Pull the latest image
docker-compose pull

# Restart with the new image
docker-compose up -d

# Check logs for any migration messages
docker-compose logs -f billmanager

Upgrade to Specific Version​

services:
  billmanager:
    image: ghcr.io/brdweb/billmanager:v4.11.0

Then:

docker-compose up -d

Before Upgrading​

  1. Read the release notes on GitHub Releases
  2. Create a backup of your database
  3. Test in staging if you have a staging environment

PostgreSQL 17 Default​

Current examples use PostgreSQL 17. Do not point an existing PostgreSQL 16 data volume directly at a PostgreSQL 17 container. Back up and restore into a fresh PostgreSQL 17 volume, or use PostgreSQL's supported pg_upgrade process.

v4.4 Migration Notice​

The first startup on v4.4 or newer runs migration 20260716_01, which replaces and validates three foreign-key constraints used by bill shares, category budgets, and registered devices. It requires no manual SQL or data conversion, but validation may briefly block writes. Use a normal maintenance window and start one application replica first.

After Upgrading​

  1. Check the application logs for errors
  2. Verify key functionality works
  3. Database migrations run automatically on startup

Rollback​

If an upgrade causes issues:

# Stop the application
docker-compose down

# Restore database from backup
cat backup_before_upgrade.sql | docker exec -i billmanager-db-1 psql -U billsuser billmanager

# Edit docker-compose.yml to use previous version
# image: ghcr.io/brdweb/billmanager:v4.10.0

# Start the previous version
docker-compose up -d

Data Migration​

Exporting Data​

Users can export their bills and payments from the web interface:

  1. Go to the Bills page
  2. Click Export → CSV or PDF

Importing from v2.x​

If upgrading from SQLite-based v2.x:

  1. Contact the maintainer for migration assistance
  2. The migration script can import data from SQLite databases
  3. See GitHub Issues for help