backupchecks/docs/migrations.md

Database migrations policy

This document describes how database schema changes are handled for Backupchecks .

Overview

• The baseline schema is defined in backend/app/models.py.
• On application startup, the following is executed inside create_app():
  1. db.create_all() – creates any missing tables and columns defined in the models.
  2. run_migrations() – executes in-image SQL migrations from backend/app/migrations.py.

This approach allows:

• Clean databases to be created automatically.
• Existing databases to be upgraded in-place without manual SQL.
• Safe repeated restarts: migrations are idempotent and can be run multiple times.

Adding migrations

When you change the schema in a way that is not automatically covered by db.create_all() (for example, altering column nullability, adding constraints, backfilling data), follow these steps:

1. Add or adjust the corresponding model(s) in models.py.

2. In migrations.py:

   • Add a new function, for example:

     • def migrate_xyz():
     • Perform the required SQL using db.get_engine() and sqlalchemy.text.
     • Always check the current state first (e.g. whether a column or constraint already exists).

   • Call this function from run_migrations() in the correct order.

3. Do NOT remove older migration functions. They must remain so that:

   • Existing databases can still be upgraded from older versions.
   • New installations run all migrations but older ones become no-ops because their checks see that the changes are already applied.

4. Each migration must be idempotent:

   • It should detect whether its change is already in place and then exit without error.
   • This allows run_migrations() to be executed on every startup.

Current migrations (initial set)

Implemented in backend/app/migrations.py:

• migrate_add_username_to_users()

  • Adds a username column to the users table if it does not exist.
  • Backfills username from email where possible.
  • Sets username to NOT NULL.
  • Adds a UNIQUE constraint on users.username.

• migrate_make_email_nullable()

  • Ensures the email column on users is nullable.
  • If the column is currently NOT NULL, the migration executes:
    ALTER TABLE "users" ALTER COLUMN email DROP NOT NULL.

• run_migrations()

  • Calls the above migrations in order.
  • Logs progress to stdout so changes are visible in container / Portainer logs.

• migrate_reporting_report_config()

  • Adds report_definitions.report_config (TEXT) if it does not exist.
  • Stores the JSON report definition for the reporting UI (selected columns, chart types, filters) so the same definition can later be reused for PDF export.

Future changes

• Every time you introduce a non-trivial schema change, update:

  • backend/app/models.py
  • backend/app/migrations.py
  • This document (docs/migrations.md) – add a short description of the new migration.

• When sharing the repository state (for example in a ZIP), always include the current migrations.py and this document so the migration history and policy are clear.