Первая модель в Django: описываем и делаем миграцию

К концу этой инструкции у вас будет таблица в базе данных, созданная не руками через SQL, а из класса Python. Вы опишете модель Article, сгенерируете файл миграции, примените его к базе и увидите новую таблицу в админке Django. Займёт всё около 20 минут, если проект уже создан. Инструкция для Django 5.x (проверялась на 5.0 и 5.1), для базы по умолчанию — SQLite, отдельно устанавливать её не нужно.

Что нужно иметь до начала

Прежде чем писать первую строку модели, убедитесь, что у вас на месте всё из списка. Если чего-то не хватает — доберите сейчас, а не на пятом шаге.

• Python 3.10 или новее (Django 5.x не запустится на более старых).
• Установленный Django. Проверьте командой python -m django --version — должна вывестись версия вида 5.1.
• Созданный проект (папка с manage.py) и хотя бы одно приложение внутри. Если приложения нет — создайте: python manage.py startapp blog.
• Активированное виртуальное окружение, чтобы команды python и manage.py работали с нужной версией Django.

Дальше все команды выполняются из папки, где лежит manage.py.

Что такое миграция — если вы слышите это впервые

Миграция — это файл на Python, который описывает изменение схемы базы: «создать такую-то таблицу», «добавить столбец». Django сам сравнивает ваши модели с тем, что уже применено, и генерирует эти файлы. Вы не пишете SQL руками — Django переводит модель в команды CREATE TABLE под вашу базу.

Шаг 1. Подключите приложение к проекту

Django видит модели только у тех приложений, которые перечислены в настройках. Откройте файл настроек проекта (обычно <имя_проекта>/settings.py) и добавьте своё приложение в список INSTALLED_APPS.

# settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",  # ваше приложение
]

Проверка: если строки "blog" нет, миграция на шаге 3 не найдёт вашу модель и напишет No changes detected. Это самая частая ошибка новичка.

Шаг 2. Опишите модель

Откройте файл blog/models.py. По умолчанию там уже есть импорт from django.db import models. Добавьте класс Article.

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


class Article(models.Model):
    # Заголовок: строка до 200 символов
    title = models.CharField(max_length=200)
    # Текст статьи: длинный, без ограничения длины
    body = models.TextField()
    # Дата создания: проставится автоматически при сохранении
    created_at = models.DateTimeField(auto_now_add=True)
    # Опубликована ли статья
    is_published = models.BooleanField(default=False)

    def __str__(self):
        # Так запись будет выглядеть в админке и в консоли
        return self.title

Каждый атрибут класса станет столбцом таблицы. Столбец id Django добавит сам — первичный ключ создавать вручную не нужно.

Проверка: сохраните файл. Ошибок при импорте быть не должно. Если запустите python manage.py check — вывод должен закончиться строкой System check identified no issues.

Про max_length и типы полей

CharField требует обязательный max_length — забудете его, и Django на следующем шаге откажется работать с ошибкой валидации. TextField длину не требует. Полный список типов полей — в документации Django, здесь показаны только четыре самых ходовых.

Модель — это единственный источник правды о структуре данных. Не правьте таблицу в базе руками: следующая миграция об этом не узнает, и схема разъедется.

Шаг 3. Создайте файл миграции

Команда makemigrations смотрит на ваши модели, сравнивает с уже применёнными миграциями и генерирует файл с описанием изменений.

python manage.py makemigrations blog

Проверка: в терминале появится примерно такое:

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

В папке blog/migrations/ появится файл 0001_initial.py. Открывать и править его вручную не нужно — это генерируемый код. Если вместо этого вы видите No changes detected — вернитесь к шагу 1: приложение не подключено или файл модели не сохранён.

Шаг 4. Примените миграцию к базе

До этого момента таблицы в базе ещё нет — есть только план её создания. Команда migrate выполняет этот план.

python manage.py migrate

Проверка: среди строк вывода будет ваша миграция:

Applying blog.0001_initial... OK

Заодно применятся встроенные миграции Django (auth, sessions и другие) — при первом запуске это нормально. В папке проекта появится файл db.sqlite3 — это и есть ваша база.

Шаг 5. Убедитесь, что таблица работает

Самый наглядный способ — админка. Зарегистрируйте модель в blog/admin.py:

# blog/admin.py
from django.contrib import admin
from .models import Article

admin.site.register(Article)

Создайте суперпользователя и запустите сервер:

python manage.py createsuperuser
python manage.py runserver

Откройте http://127.0.0.1:8000/admin/, войдите под созданным логином. Проверка: в списке разделов будет «Articles». Добавьте одну запись — она сохранится в таблицу, а её заголовок отобразится в списке благодаря методу __str__.

Если не получилось

Четыре ошибки, на которые новичок натыкается чаще всего, и что с ними делать.

• No changes detected после makemigrations. Приложения нет в INSTALLED_APPS, либо вы не сохранили models.py. Проверьте шаг 1.
• CharFields must define a 'max_length' attribute. У CharField не указан max_length. Добавьте, например, max_length=200.
• no such table: blog_article при обращении к данным. Вы создали файл миграции, но не применили его. Запустите python manage.py migrate.
• ModuleNotFoundError или пустая админка. В admin.py не тот импорт модели или приложение импортируется неверно. Проверьте, что в from .models import Article имя класса совпадает с описанным в models.py.

Разница между двумя командами

Новички путают makemigrations и migrate и запускают одну вместо другой. Запомните разницу:

Порядок всегда такой: сначала makemigrations, потом migrate. Каждый раз, когда меняете модель, повторяете обе.

Что делать дальше

Первая таблица создана. Логичные следующие шаги:

• Добавьте в модель ещё одно поле (например, author = models.CharField(max_length=100)) и снова прогоните makemigrations + migrate — увидите, как Django генерирует миграцию на изменение, а не на создание.
• Разберитесь со связями между таблицами — ForeignKey, ManyToManyField. Это отдельная тема, здесь мы её не трогали.
• Посмотрите, какой SQL генерирует миграция: python manage.py sqlmigrate blog 0001 — команда покажет реальный CREATE TABLE, ничего не меняя в базе.

Переход с SQLite на PostgreSQL меняет настройки подключения, но сами модели и миграции остаются теми же — это плюс подхода Django.