Skip to content

Database Migrations

Overview

The Onconova platform uses Django’s ORM (Object-Relational Mapping) system to manage its database schema. Any changes to the database structure:

  • Adding or removing tables
  • Altering fields
  • Updating relationships
  • Altering constraints or triggers
  • etc.

must be performed through Django migrations rather than by manually modifying the database.

Why Migrations Matter

Django’s migrations framework provides a structured, version-controlled way to evolve the database schema alongside your application code.
Migrations ensure that:

  • The database schema always matches the structure defined by the Django models.
  • Changes are applied consistently across all environments (development, staging, production).
  • Dependencies between schema changes are tracked.
  • The API (which is autogenerated from the database schema) remains consistent and predictable.

Do Not Edit the Database Manually

Never alter the Onconova database schema directly via SQL commands or external tools.

Manual changes can:

  • Break the link between the Django models and the actual database tables.
  • Cause runtime errors when the ORM attempts to access non-existent or misconfigured columns.
  • Corrupt automatic database migrations or make them impossible to apply safely.
  • Lead to desynchronization between the API endpoints (which rely on schema introspection) and the actual database.

Applying Migrations

When updating Onconova to a newer version or after developing new features, the Onconova database might be out-of-date with the migrations. To apply pending migrations and synchronize the database schema with the latest migration files: 

docker compose run server python manage.py migrate

This will:

  • Execute all unapplied migrations in order.
  • Update the database schema accordingly.
  • Track applied migrations in the django_migrations table.

Controlled Migrations

Always apply migrations in a controlled environment and back up production databases before applying schema changes.

To see which migrations have been applied and which are pending: 

docker compose run server python manage.py showmigrations

For developers

Creating New Migrations

Whenever you change a model in the server application (e.g., add a new field, remove a column, or create a new model), you must generate a new migration file.

docker compose run server python manage.py makemigrations
This will:

  • Detect changes in the Django models.
  • Create a new migration file.
  • Describe the changes required to bring the database schema in line with the updated models.
runner