Переезд Django с SQLite на PostgreSQL: пошаговая инструкция

По умолчанию Django кладёт данные в файл db.sqlite3 в корне проекта — это удобно на старте, но не годится для продакшена: SQLite блокирует базу на запись целиком, плохо переносит параллельные запросы и не даёт нормально настроить бэкапы и репликацию. В этой инструкции вы переведёте проект на PostgreSQL 16: поставите драйвер, создадите базу и пользователя, поправите settings.py, прогоните миграции и перенесёте существующие данные. Проверено на Django 5.x и PostgreSQL 16, на Django 4.2 всё работает так же.

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

• Работающий проект на Django 4.2 или 5.x с базой на SQLite.
• Python 3.10+ и активированное виртуальное окружение проекта.
• Установленный PostgreSQL 16 — локально или на сервере, к которому у вас есть доступ. Проверьте командой psql --version.
• Права суперпользователя в PostgreSQL (обычно роль postgres), чтобы создать базу и пользователя.
• Компилятор C и заголовки libpq — нужны, если ставите psycopg2 из исходников. На Debian/Ubuntu это пакеты libpq-dev и build-essential. Если ставите psycopg2-binary, они не понадобятся.

Сделайте копию файла db.sqlite3 перед началом. Пока данные не перенесены, старая база — ваш единственный источник.

Шаг 1. Установите драйвер

Django общается с PostgreSQL через библиотеку psycopg. Для быстрого старта поставьте бинарную сборку — она не требует компиляции:

pip install "psycopg[binary]"

Это psycopg версии 3, которую Django 4.2+ поддерживает штатно. Если проект старый и завязан на psycopg2, подойдёт и он: pip install psycopg2-binary. Не смешивайте — достаточно одного драйвера.

Проверка: выполните python -c "import psycopg; print(psycopg.__version__)". Должна вывестись версия без ошибок импорта.

Зафиксируйте зависимость: pip freeze | grep psycopg и добавьте строку в requirements.txt.

Шаг 2. Создайте базу и пользователя в PostgreSQL

Зайдите в консоль psql под суперпользователем:

sudo -u postgres psql

Внутри выполните три команды. Замените имена и пароль на свои — пароль здесь заглушка:

CREATE DATABASE myshop_db;
CREATE USER myshop_user WITH PASSWORD 'YOUR_DB_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE myshop_db TO myshop_user;

В PostgreSQL 15 и новее прав на саму базу мало: чтобы Django мог создавать таблицы, пользователю нужны права и на схему public. Подключитесь к базе и выдайте их:

\c myshop_db
GRANT ALL ON SCHEMA public TO myshop_user;

Выйдите из psql командой \q.

Проверка: подключитесь под новым пользователем — psql -U myshop_user -d myshop_db -h localhost. Если запросит пароль и пустит внутрь, доступ настроен.

Шаг 3. Пропишите базу в settings.py

Найдите в settings.py блок DATABASES — там сейчас SQLite. Замените его на конфигурацию PostgreSQL. Значения тяните из переменных окружения, а не хардкодьте:

import os

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("DB_NAME", "myshop_db"),
        "USER": os.environ.get("DB_USER", "myshop_user"),
        "PASSWORD": os.environ.get("DB_PASSWORD", ""),
        "HOST": os.environ.get("DB_HOST", "localhost"),
        "PORT": os.environ.get("DB_PORT", "5432"),
    }
}

Значение ENGINE одинаково и для psycopg 3, и для psycopg2 — Django сам определяет, какой драйвер установлен. Пароль в репозиторий не попадает: положите его в переменную окружения или в .env, который добавлен в .gitignore.

Не оставляйте старый блок DATABASES закомментированным рядом. Через месяц вы забудете, какой из них рабочий, и потратите полчаса на отладку опечатки в закомментированном коде.

Проверка: запустите python manage.py check. Если конфигурация корректна, увидите System check identified no issues.

Шаг 4. Создайте структуру таблиц

Новая база пустая. Прогоните миграции, чтобы Django создал таблицы:

python manage.py migrate

Команда пройдёт по всем миграциям приложений и системных модулей и создаст схему. Проверка: подключитесь к базе через psql и выполните \dt — должен вывестись список таблиц вроде auth_user, django_migrations и ваших моделей.

Шаг 5. Перенесите данные из SQLite

Если данными в SQLite можно пожертвовать (например, это учебный проект), пропустите шаг — migrate уже дал пустую рабочую базу. Если данные нужны, перенесите их через дамп в JSON.

Сначала выгрузите данные из старой базы. Временно верните SQLite в settings.py или используйте отдельный конфиг, затем:

python manage.py dumpdata --natural-foreign --natural-primary \
  --exclude contenttypes --exclude auth.permission \
  --indent 2 -o dump.json

Исключения важны: таблицы contenttypes и auth.permission Django заполняет сам при миграциях, и повторная загрузка вызовет конфликт уникальных ключей.

Теперь верните в settings.py конфигурацию PostgreSQL и загрузите дамп:

python manage.py loaddata dump.json

Проверка: откройте админку или выполните запрос в shell — python manage.py shell -c "from django.contrib.auth.models import User; print(User.objects.count())". Число пользователей должно совпасть с тем, что было в SQLite.

Шаг 6. Запустите приложение

python manage.py runserver

Откройте http://127.0.0.1:8000/ и пройдитесь по основным страницам. Если раньше был суперпользователь и он не перенёсся с данными, создайте нового: python manage.py createsuperuser.

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

• psql: FATAL: password authentication failed for user — неверный пароль или PostgreSQL настроен на другой метод аутентификации. Проверьте пароль и файл pg_hba.conf: для локальных подключений по паролю нужна строка с методом md5 или scram-sha-256, а не peer.
• django.db.utils.OperationalError: connection refused — PostgreSQL не запущен или слушает не тот адрес. Проверьте службу: sudo systemctl status postgresql. Убедитесь, что HOST и PORT в настройках совпадают с реальными.
• permission denied for schema public — вы на PostgreSQL 15+ и не выдали права на схему. Вернитесь к шагу 2 и выполните GRANT ALL ON SCHEMA public.
• IntegrityError при loaddata на contenttype — вы не исключили contenttypes при dumpdata. Пересоздайте дамп с флагами --exclude из шага 5.
• ModuleNotFoundError: No module named 'psycopg' — драйвер поставлен не в то окружение. Убедитесь, что виртуальное окружение активно, и повторите установку из шага 1.

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

После переезда закройте несколько вопросов, до которых на SQLite не доходили руки:

• Настройте регулярный бэкап через pg_dump — например, ежедневный дамп по cron.
• Добавьте "CONN_MAX_AGE" в настройки базы, чтобы Django переиспользовал соединения и не открывал новое на каждый запрос.
• Уберите файл db.sqlite3 из репозитория и из .gitignore, если он там был, чтобы никто случайно не запустил проект на старой базе.

Инвалидация кеша и настройка пула соединений через PgBouncer — отдельные темы, здесь мы только переключили движок и перенесли данные.