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:4.13.6

Then:

docker-compose up -d

Before Upgrading​

  1. Read the release notes for every version between your current and target versions
  2. Create a backup of your database
  3. Test in staging if you have a staging environment

v4.13.4 to v4.13.6 Upgrade Notes​

These releases add no database migrations or new settings.

  • v4.13.4: If you run SaaS mode with Stripe billing, review failed invoice.* and checkout.session.completed deliveries in the Stripe Dashboard after you upgrade. A restricted Stripe key still needs read access to subscriptions. API clients that call /billing/create-checkout can receive 400 while the stored subscription still needs attention.
  • v4.13.6: That 400 response now carries code: "subscription_needs_attention".

v4.13.1 to v4.13.3 Upgrade Notes​

These releases add no database migrations or new settings.

  • v4.13.1: If you run SaaS mode with Stripe billing, open the Stripe Dashboard, go to Developers → Webhooks, and review failed deliveries from the time you ran v4.13.0. Stripe retries failed events for up to 3 days. Resend older events manually or reconcile the affected subscriptions.
  • v4.13.2: Yearly, monthly-comparison, and by-account totals can change for shared bills. A share recipient's payment on the owner's bill now counts as income for the owner and as an expense for the recipient.
  • v4.13.3: API clients that call /billing/change-plan now receive effective: immediately. The plan change behavior itself is unchanged.

v4.13.0 Upgrade Notes​

The first startup on v4.13.0 runs migration 20260907_01. It adds a table for processed Stripe webhook events and one column to the subscriptions table. No manual SQL is required.

Self-hosted deployments need no new settings. Stripe billing stays disabled in self-hosted mode, and the public image contains no product-analytics tracker. To turn on optional crash reporting, see Crash Reporting.

For SaaS-mode deployments with billing, set STRIPE_PRICE_PRO_MONTHLY and STRIPE_PRICE_PRO_ANNUAL before you upgrade. Checkout stays unavailable until both are set. Keep the existing STRIPE_PRICE_BASIC_* and STRIPE_PRICE_PLUS_* values so current subscriptions keep Pro access. See Stripe Billing.

v4.12.2 Client Compatibility​

Complete these steps when you upgrade to v4.12.2:

  1. Update API clients to use POST /api/v2/auth/2fa/recovery-codes for recovery-code replacement.
  2. Update mobile clients before you use native OAuth with a private custom callback scheme.
  3. Restart each linking or enrollment flow that started before the server upgrade.

The updated mobile client keeps a verifier and sends its SHA-256 challenge during OAuth. The server creates the new identity-confirmation table at startup.

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:4.13.2

# 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