Introduction to Django Models and Migrations

A blog has to remember its articles after the server restarts, so every article needs a row in a database table. You could write the SQL for that table by hand, but Django lets you describe the table as a Python class instead. That class is called a model, and this chapter is about models: how to define them, how Django turns them into tables, how to read and write their rows with Python, and how to connect one model to another.

This lesson covers the first two steps. You define a model for the blog's articles, and then you use migrations, which are Django's record of every change to your tables, to create the table and to change it later.

Defining a Model

A model is a Python class that inherits from models.Model, and it lives in the models.py file of an app. Each class attribute that is a field becomes one column of the table. The examples in this chapter use an app called blog, so the model goes in blog/models.py:

# blog/models.py
from django.db import models
from django.utils import timezone


class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    author = models.CharField(max_length=100)
    published_date = models.DateTimeField(default=timezone.now)

    def __str__(self):
        return self.title

The field class decides what kind of data the column holds and how Django checks it. A CharField is short text, and it requires max_length, which becomes the size of the column. A TextField is text of any length, which suits the body of an article. A DateTimeField stores a date and a time.

The default=timezone.now argument passes the function itself, without parentheses. Django calls it each time it creates an article, so a new article gets the current date and time, but you can still set a different publication date when you need to. (If you wrote timezone.now() with parentheses, every article would get the moment the server started.)

The __str__ method is not a field. It tells Django how to show an article as text, so the shell and the admin site print the title instead of Article object (1).

Other common field types are IntegerField and PositiveIntegerField for whole numbers, DecimalField for exact amounts such as prices, BooleanField for true or false values, DateField for a date without a time, and EmailField for email addresses. The ForeignKey field links one model to another, and the third lesson of this chapter covers it.

You did not declare a primary key, but the table still gets one. Django adds a field called id to every model that does not define its own primary key. Its type is BigAutoField, a 64-bit integer that the database increases by one for each new row.

The table also gets a name that you did not choose. Django names it <app label>_<model name in lowercase>, so the Article model in the blog app is stored in a table called blog_article. You can check the name in the shell with Article._meta.db_table.

From Model to Table: makemigrations and migrate

Writing the class does not create anything in the database. Django changes the database in two separate steps, and each step has its own command.

The first step writes a migration file. Run this command from the folder that contains manage.py:

python manage.py makemigrations

Migrations for 'blog':
  blog/migrations/0001_initial.py
    + Create model Article

Django compared your models with the migration files that already exist, found a new model, and wrote a new file in blog/migrations/. The file name starts with a number, so the files of an app always run in order. At this point the database has not changed at all.

The migration file is ordinary Python. It describes the change as a list of operations, not as SQL:

# blog/migrations/0001_initial.py (generated, header comment removed)
import django.utils.timezone
from django.db import migrations, models


class Migration(migrations.Migration):

    initial = True

    dependencies = [
    ]

    operations = [
        migrations.CreateModel(
            name='Article',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('title', models.CharField(max_length=200)),
                ('content', models.TextField()),
                ('author', models.CharField(max_length=100)),
                ('published_date', models.DateTimeField(default=django.utils.timezone.now)),
            ],
        ),
    ]

Because the file describes operations rather than SQL, the same migration works on SQLite, PostgreSQL, MySQL or any other database that Django supports. Django produces the SQL for your database only when it applies the migration. You can see that SQL without running it:

python manage.py sqlmigrate blog 0001

BEGIN;
--
-- Create model Article
--
CREATE TABLE "blog_article" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "title" varchar(200) NOT NULL, "content" text NOT NULL, "author" varchar(100) NOT NULL, "published_date" datetime NOT NULL);
COMMIT;

This is the SQL for SQLite, the database a new project uses. Notice that the default for published_date does not appear in the SQL. Django fills in that value in Python when it saves an article, not in the database.

The second step applies the migration to the database:

python manage.py migrate

Operations to perform:
  Apply all migrations: accounts, admin, auth, blog, contenttypes, sessions
Running migrations:
  Applying blog.0001_initial... OK

The migrate command runs every migration that has not been applied yet, in dependency order. The first line lists every app that has migrations, but only one migration ran. The project's first migrate, in Chapter 1, already applied the migrations of the apps that Django installs for you, such as auth for permissions and sessions for logged-in visitors, together with the accounts app and its user model. Only the new blog.0001_initial was left to apply.

Django also records each applied migration in a table called django_migrations. The next time you run migrate, it reads that table and skips everything already done.