Bài 08: Database Migrations

Migrations Là Gì?

Migrations là cách Django propagate các thay đổi trong models (thêm field, xóa model, etc.) vào database schema.

# Without migrations (old way)# 1. Change model# 2. Manually write SQL# 3. Execute SQL in database# 4. Repeat for each environment # With Django migrations (modern way)# 1. Change model# 2. python manage.py makemigrations# 3. python manage.py migrate# 4. Commit migration files to git# 5. Other developers run migrate

Migrations Benefits

# ✅ Version control for database schema# ✅ Automatic SQL generation# ✅ Database-agnostic (works with SQLite, PostgreSQL, MySQL)# ✅ Easy rollback# ✅ Team collaboration (share via git)# ✅ Deployment automation# ✅ Data migrations support

Migration Files

# blog/migrations/# ├── __init__.py# ├── 0001_initial.py          # First migration# ├── 0002_post_published.py   # Add published field# ├── 0003_post_views.py       # Add views field# └── 0004_auto_20231028_1234.py  # Auto-generated name # Each migration file:# - Is a Python file# - Contains operations# - Has dependencies# - Can be executed forward or backward

Basic Migration Commands

makemigrations - Create Migrations

# Create migrations for all appspython manage.py makemigrations # Create migrations for specific apppython manage.py makemigrations blog # Create empty migrationpython manage.py makemigrations --empty blog # Give custom namepython manage.py makemigrations blog --name add_published_field # Dry run (don't create files)python manage.py makemigrations --dry-run # Verbose outputpython manage.py makemigrations --verbosity 2

Example:

# 1. Define model# blog/models.pyclass Post(models.Model):    title = models.CharField(max_length=200)    content = models.TextField()    created = models.DateTimeField(auto_now_add=True) # 2. Create migration$ python manage.py makemigrations blog # Output:# Migrations for 'blog':#   blog/migrations/0001_initial.py#     - Create model Post # 3. Migration file created# blog/migrations/0001_initial.pyfrom django.db import migrations, models class Migration(migrations.Migration):    initial = True        dependencies = []        operations = [        migrations.CreateModel(            name='Post',            fields=[                ('id', models.BigAutoField(auto_created=True, primary_key=True)),                ('title', models.CharField(max_length=200)),                ('content', models.TextField()),                ('created', models.DateTimeField(auto_now_add=True)),            ],        ),    ]

migrate - Apply Migrations

# Apply all migrationspython manage.py migrate # Apply migrations for specific apppython manage.py migrate blog # Apply up to specific migrationpython manage.py migrate blog 0002 # Rollback to previous migrationpython manage.py migrate blog 0001 # Undo all migrations for apppython manage.py migrate blog zero # Show SQL without executingpython manage.py migrate --planpython manage.py sqlmigrate blog 0001 # Fake migration (mark as applied without running)python manage.py migrate blog --fake # Fake initial migrationpython manage.py migrate blog --fake-initial

Example:

# Apply migrations$ python manage.py migrate # Output:# Operations to perform:#   Apply all migrations: admin, auth, blog, contenttypes, sessions# Running migrations:#   Applying blog.0001_initial... OK#   Applying blog.0002_post_published... OK

showmigrations - View Migration Status

# Show all migrationspython manage.py showmigrations # Show for specific apppython manage.py showmigrations blog # Show as listpython manage.py showmigrations --list # Show as planpython manage.py showmigrations --plan

Output:

$ python manage.py showmigrations admin [X] 0001_initial [X] 0002_logentry_remove_auto_addauth [X] 0001_initial [X] 0002_alter_permission_name_max_lengthblog [X] 0001_initial [X] 0002_post_published [ ] 0003_post_views  # Not applied yet

sqlmigrate - View SQL

# Show SQL for migrationpython manage.py sqlmigrate blog 0001 # Show backward SQLpython manage.py sqlmigrate blog 0001 --backwards

Output:

BEGIN;---- Create model Post--CREATE TABLE "blog_post" (    "id" integer NOT NULL PRIMARY KEY AUTOINCREMENT,    "title" varchar(200) NOT NULL,    "content" text NOT NULL,    "created" datetime NOT NULL);COMMIT;

Migration Operations

CreateModel

# Add new model# models.pyclass Category(models.Model):    name = models.CharField(max_length=100)    slug = models.SlugField(unique=True) # Generated migrationoperations = [    migrations.CreateModel(        name='Category',        fields=[            ('id', models.BigAutoField(auto_created=True, primary_key=True)),            ('name', models.CharField(max_length=100)),            ('slug', models.SlugField(unique=True)),        ],    ),]

DeleteModel

# Delete model# Remove from models.py # Generated migrationoperations = [    migrations.DeleteModel(        name='OldModel',    ),]

AddField

# Add new field to existing model# models.pyclass Post(models.Model):    title = models.CharField(max_length=200)    content = models.TextField()    published = models.BooleanField(default=False)  # New field # Generated migrationoperations = [    migrations.AddField(        model_name='post',        name='published',        field=models.BooleanField(default=False),    ),]

RemoveField

# Remove field from model# Remove from models.py # Generated migrationoperations = [    migrations.RemoveField(        model_name='post',        name='old_field',    ),]

AlterField

# Change field definition# models.py - Change max_lengthclass Post(models.Model):    title = models.CharField(max_length=300)  # Was 200 # Generated migrationoperations = [    migrations.AlterField(        model_name='post',        name='title',        field=models.CharField(max_length=300),    ),]

RenameField

# Rename field# models.pyclass Post(models.Model):    post_title = models.CharField(max_length=200)  # Was 'title' # Generated migrationoperations = [    migrations.RenameField(        model_name='post',        old_name='title',        new_name='post_title',    ),]

RenameModel

# Rename model# Generated migrationoperations = [    migrations.RenameModel(        old_name='Post',        new_name='Article',    ),]

AlterModelTable

# Change database table name# models.pyclass Post(models.Model):    title = models.CharField(max_length=200)        class Meta:        db_table = 'articles'  # Custom table name # Generated migrationoperations = [    migrations.AlterModelTable(        name='post',        table='articles',    ),]

Working with Fields

Adding Required Fields

# Problem: Adding required field to existing table with dataclass Post(models.Model):    title = models.CharField(max_length=200)    author = models.ForeignKey(User, on_delete=models.CASCADE)  # New required field # Error: Cannot add non-nullable field without default # Solution 1: Add with defaultauthor = models.ForeignKey(User, on_delete=models.CASCADE, default=1) # Solution 2: Add as nullable, then populate, then make required# Step 1: Add as nullableauthor = models.ForeignKey(User, on_delete=models.CASCADE, null=True)# makemigrations & migrate # Step 2: Create data migration to populate field (see Data Migrations section) # Step 3: Make requiredauthor = models.ForeignKey(User, on_delete=models.CASCADE)# makemigrations & migrate

Adding Fields with Choices

# Add field with choicesclass Post(models.Model):    STATUS_CHOICES = [        ('draft', 'Draft'),        ('published', 'Published'),    ]        status = models.CharField(        max_length=20,        choices=STATUS_CHOICES,        default='draft'  # Important: provide default    ) # Generated migrationoperations = [    migrations.AddField(        model_name='post',        name='status',        field=models.CharField(            choices=[('draft', 'Draft'), ('published', 'Published')],            default='draft',            max_length=20        ),    ),]

Changing Field Type

# Change field type (e.g., CharField to TextField)# Oldclass Post(models.Model):    excerpt = models.CharField(max_length=500) # Newclass Post(models.Model):    excerpt = models.TextField() # Generated migrationoperations = [    migrations.AlterField(        model_name='post',        name='excerpt',        field=models.TextField(),    ),] # Note: Django will handle conversion, but be careful with data loss# CharField(max_length=10) -> IntegerField may fail if data not numeric

ForeignKey and Relationships

Adding ForeignKey

# Add ForeignKey to existing modelclass Post(models.Model):    title = models.CharField(max_length=200)    category = models.ForeignKey(        'Category',  # String reference if Category defined later        on_delete=models.CASCADE,        null=True,  # Make nullable initially        blank=True    ) # Generated migrationoperations = [    migrations.AddField(        model_name='post',        name='category',        field=models.ForeignKey(            blank=True,            null=True,            on_delete=django.db.models.deletion.CASCADE,            to='blog.category'        ),    ),]

Adding ManyToManyField

# Add ManyToMany relationshipclass Post(models.Model):    title = models.CharField(max_length=200)    tags = models.ManyToManyField('Tag') # Generated migrationoperations = [    migrations.AddField(        model_name='post',        name='tags',        field=models.ManyToManyField(to='blog.tag'),    ),] # Creates intermediate table: blog_post_tags

Changing on_delete Behavior

# Change ForeignKey on_delete# Oldcategory = models.ForeignKey(Category, on_delete=models.CASCADE) # Newcategory = models.ForeignKey(Category, on_delete=models.SET_NULL, null=True) # Generated migrationoperations = [    migrations.AlterField(        model_name='post',        name='category',        field=models.ForeignKey(            null=True,            on_delete=django.db.models.deletion.SET_NULL,            to='blog.category'        ),    ),]

Data Migrations

Creating Data Migration

# Create empty migrationpython manage.py makemigrations --empty blog --name populate_authors

Simple Data Migration

# blog/migrations/0005_populate_authors.pyfrom django.db import migrations def populate_authors(apps, schema_editor):    """Set default author for existing posts."""    # Get model via apps registry (not direct import)    Post = apps.get_model('blog', 'Post')    User = apps.get_model('auth', 'User')        # Get or create default user    default_user = User.objects.first()    if not default_user:        default_user = User.objects.create(            username='admin',            is_staff=True        )        # Update posts    Post.objects.filter(author__isnull=True).update(author=default_user) def reverse_populate_authors(apps, schema_editor):    """Reverse migration (set authors to null)."""    Post = apps.get_model('blog', 'Post')    Post.objects.all().update(author=None) class Migration(migrations.Migration):    dependencies = [        ('blog', '0004_post_author'),    ]        operations = [        migrations.RunPython(            populate_authors,            reverse_populate_authors  # For rollback        ),    ]

Data Migration Examples

# Example 1: Convert data formatdef convert_status(apps, schema_editor):    Post = apps.get_model('blog', 'Post')        # Convert boolean to status choice    Post.objects.filter(published=True).update(status='published')    Post.objects.filter(published=False).update(status='draft') # Example 2: Calculate and store valuedef calculate_word_counts(apps, schema_editor):    Post = apps.get_model('blog', 'Post')        for post in Post.objects.all():        post.word_count = len(post.content.split())        post.save() # Example 3: Migrate to new modeldef migrate_to_new_model(apps, schema_editor):    OldModel = apps.get_model('blog', 'OldModel')    NewModel = apps.get_model('blog', 'NewModel')        for old in OldModel.objects.all():        NewModel.objects.create(            name=old.title,            description=old.content,            created=old.date        ) # Example 4: Bulk operationsdef bulk_update_categories(apps, schema_editor):    Post = apps.get_model('blog', 'Post')    Category = apps.get_model('blog', 'Category')        tech_category = Category.objects.get(slug='tech')        # Bulk update    Post.objects.filter(        content__icontains='django'    ).update(category=tech_category) # Migration classclass Migration(migrations.Migration):    dependencies = [        ('blog', '0006_previous_migration'),    ]        operations = [        migrations.RunPython(            bulk_update_categories,            reverse_code=migrations.RunPython.noop  # No reverse        ),    ]

RunSQL - Custom SQL

# Run custom SQLfrom django.db import migrations class Migration(migrations.Migration):    dependencies = [        ('blog', '0007_previous'),    ]        operations = [        migrations.RunSQL(            # Forward SQL            """            UPDATE blog_post            SET views = 0            WHERE views IS NULL;            """,            # Reverse SQL            """            UPDATE blog_post            SET views = NULL            WHERE views = 0;            """        ),    ]

Migration Dependencies

Dependency Types

# 1. App-level dependencyclass Migration(migrations.Migration):    dependencies = [        ('blog', '0001_initial'),  # Depends on blog's 0001    ] # 2. Cross-app dependencyclass Migration(migrations.Migration):    dependencies = [        ('blog', '0001_initial'),        ('shop', '0001_initial'),  # Depends on another app    ] # 3. Auth/User dependencyclass Migration(migrations.Migration):    dependencies = [        ('blog', '0001_initial'),        migrations.swappable_dependency(settings.AUTH_USER_MODEL),    ]

Resolving Conflicts

# Scenario: Two developers create migrations simultaneously# Developer A creates: 0002_add_field_a.py# Developer B creates: 0002_add_field_b.py # Solution: Merge migrations# 1. Rename one: 0002_add_field_b.py -> 0003_add_field_b.py# 2. Update dependencies in 0003: class Migration(migrations.Migration):    dependencies = [        ('blog', '0002_add_field_a'),  # Depends on other migration    ]        operations = [        migrations.AddField(            model_name='post',            name='field_b',            field=models.CharField(max_length=100),        ),    ] # 3. Run makemigrations to detect conflictspython manage.py makemigrations --merge

Common Workflows

Adding a New Model

# 1. Define model# blog/models.pyclass Category(models.Model):    name = models.CharField(max_length=100)    slug = models.SlugField(unique=True)        def __str__(self):        return self.name # 2. Create migrationpython manage.py makemigrations blog # 3. Review migrationcat blog/migrations/0002_category.py # 4. Apply migrationpython manage.py migrate blog # 5. Verify in databasepython manage.py dbshell.tables  # SQLite\dt  # PostgreSQL

Adding Field to Existing Model

# Workflow: Add non-nullable field with existing data # Step 1: Add field as nullableclass Post(models.Model):    title = models.CharField(max_length=200)    category = models.ForeignKey(        Category,        on_delete=models.CASCADE,        null=True,        blank=True    ) python manage.py makemigrationspython manage.py migrate # Step 2: Create data migration to populatepython manage.py makemigrations --empty blog --name populate_categories # Edit migrationdef populate_categories(apps, schema_editor):    Post = apps.get_model('blog', 'Post')    Category = apps.get_model('blog', 'Category')        default_category = Category.objects.get_or_create(        slug='uncategorized',        defaults={'name': 'Uncategorized'}    )[0]        Post.objects.filter(category__isnull=True).update(        category=default_category    ) python manage.py migrate # Step 3: Make field non-nullableclass Post(models.Model):    category = models.ForeignKey(        Category,        on_delete=models.CASCADE  # Remove null=True    ) python manage.py makemigrationspython manage.py migrate

Renaming Model or Field

# Workflow: Rename without losing data # Option 1: Using RenameModel/RenameField (safe)# 1. Let Django detect rename# Rename in models.pyclass Article(models.Model):  # Was Post    post_title = models.CharField(max_length=200)  # Was title # 2. Create migrationpython manage.py makemigrations # Django will ask:# Did you rename post.title to post.post_title (a CharField)? [y/N]# Answer: y # Option 2: Manual (for complex cases)# 1. Create migrationpython manage.py makemigrations --empty blog --name rename_model # 2. Edit migrationoperations = [    migrations.RenameModel(        old_name='Post',        new_name='Article',    ),    migrations.RenameField(        model_name='article',        old_name='title',        new_name='post_title',    ),] python manage.py migrate

Bài Tập

Bài 1: Basic Migrations

Task: Create blog app with migrations:

# 1. Create apppython manage.py startapp blog # 2. Define initial modelsclass Post(models.Model):    title = models.CharField(max_length=200)    content = models.TextField()    created = models.DateTimeField(auto_now_add=True) # 3. Create and apply migration# 4. Verify table created in database # 5. Add published fieldpublished = models.BooleanField(default=False) # 6. Create and apply migration# 7. Check migration status

Bài 2: Add Relationships

Task: Add Category model and relationship:

# 1. Create Category modelclass Category(models.Model):    name = models.CharField(max_length=100)    slug = models.SlugField(unique=True) # 2. Add ForeignKey to Post (nullable)class Post(models.Model):    # ... existing fields    category = models.ForeignKey(        Category,        on_delete=models.CASCADE,        null=True,        blank=True    ) # 3. Create migrations# 4. Create default category in admin# 5. Create data migration to assign default category# 6. Make category required (remove null=True)

Bài 3: Data Migration

Task: Migrate status from boolean to choices:

# Current modelclass Post(models.Model):    title = models.CharField(max_length=200)    published = models.BooleanField(default=False) # New modelclass Post(models.Model):    title = models.CharField(max_length=200)    status = models.CharField(        max_length=20,        choices=[            ('draft', 'Draft'),            ('published', 'Published'),            ('archived', 'Archived'),        ],        default='draft'    ) # Steps:# 1. Add status field (keep published temporarily)# 2. Create data migration to convert published -> status# 3. Remove published field

Bài 4: Rollback Practice

Task: Practice rollback:

# 1. Create 3 migrations# 2. Apply all migrations# 3. Rollback to migration 0001# 4. Re-apply to latest# 5. Show migration status# 6. View SQL for specific migration

Tài Liệu Tham Khảo

Previous: Bài 07 Part 2: QuerySets | Next: Bài 09: Django Admin

#schema

Django Database Migrations