Manual Migration Fix

This guide explains how to reset the migration history for a specific Django app. This is useful when your migrations get out of sync but you want to keep the app and its data tables intact.

Clear Migration History

The django_migrations table contains records that track which migration files have been applied to your database. Sometimes these records prevent new updates from running correctly. You can manually clear these entries to reset the tracking for a specific app.

First, access your database command line using the following command:

uv run manage.py dbshell

Run this query to view the current migration records for your specific app:

-- Replace 'app_name' with your actual app name
SELECT * FROM django_migrations WHERE app = 'app_name';

If you need to reset the history, run the delete command:

-- Replace 'app_name' with your actual app name
DELETE FROM django_migrations WHERE app = 'app_name';

This operation only removes the tracking metadata. It does not delete your actual data or the physical tables in your database.

(Optional) Drop Physical Tables

If you intend to recreate the app structure from scratch, you can manually drop the existing tables in your database shell. This step is only necessary if you want the next migration to create brand-new tables rather than using the existing ones.

Fake Migrations

After clearing the records, you must bring Django back in sync with the database. If your physical tables still exist, use the following command to "fake" the migrations:

uv run manage.py migrate --fake app_name

This marks the migrations as completed in the tracking table without attempting to recreate the tables. You should only use the --fake flag if you did not drop the tables and want to prevent Django from trying to create them again.

However, if you chose to drop the physical tables in the previous step, run a standard migration instead to recreate the tables and update the tracking metadata automatically:

uv run manage.py migrate app_name