Database Migrations and Backups

This page describes how dinary-server manages its DuckDB files and how to back them up safely.

Database files

The server stores data in the data/ directory:

config.duckdb - reference data such as categories, groups, tags, stores, and mappings
budget_YYYY.duckdb - yearly transactional data such as expenses and sync jobs

Schema changes are managed with yoyo migrations.

On application startup, config.duckdb is migrated to the latest version automatically
When a yearly budget database is opened for the first time, budget_YYYY.duckdb is created and migrated automatically
During inv deploy, the deploy script applies config migrations before restarting the service

For a fresh installation, no manual migration step is usually required.

If you want to apply migrations explicitly on the server:

inv migrate-config
inv migrate-budget --year=2026

Use migrate-budget for any year whose budget_YYYY.duckdb file already exists or is about to be created.

DuckDB stores everything in local files, so backup is file-based.

Back up the whole data/ directory, including:

Create a backup:

To download server data locally:

inv backup

By default this copies the remote data/ directory into ./backups/.

You can also choose another destination:

inv backup --dest=./my-backups

To restore from a backup:

Stop the running service
Replace the contents of data/ with the backed up files
Start the service again
Run inv migrate-config and inv migrate-budget --year=YYYY if you want to force migration checks after restore

Because the database is file-based, restore is usually just a file copy operation.