Все заметки
Программирование

Миграция, которая положила сайт: очередь блокировок, NOT VALID, CONCURRENTLY и правило двух деплоев

Даже ALTER TABLE на миллисекунду может остановить весь сайт. Какой DDL что блокирует и как в Django добавить NOT NULL-колонку, индекс или удалить колонку без простоя.

Представьте обычный релиз. Вы добавляете в модель Order одно nullable-поле, makemigrations генерирует миграцию на две строки, CI запускает migrate до старта новых подов. Сам ALTER TABLE выполняется за миллисекунды. Но следующие полминуты каждая страница, которая трогает заказы, висит, пул соединений забивается, health check'и начинают падать.

Ничего не было «медленным» в привычном смысле. Миграция просто попросила у PostgreSQL блокировку в неудачный момент, и всё приложение выстроилось за ней в очередь. Эта статья о том, почему так происходит, какие DDL-операции действительно опасны и как менять схему в Django, не останавливая трафик: добавление колонки NOT NULL, создание индексов, удаление и переименование колонок и одна настройка, которая должна быть в каждой миграции, lock_timeout.

Почему «это же всего один ALTER TABLE» ломается

Почти любой ALTER TABLE в PostgreSQL берёт на таблицу блокировку ACCESS EXCLUSIVE. Это самая сильная блокировка: она конфликтует со всем, включая обычный SELECT, который держит ACCESS SHARE.

Наивная модель звучит так: «ALTER мгновенный, значит и блокировка мгновенная». Её ломают две вещи.

Во-первых, не все операции мгновенные. Некоторые переписывают всю таблицу или читают каждую строку, удерживая ACCESS EXCLUSIVE. На большой таблице это минуты полного простоя для этой таблицы.

Во-вторых, и это неожиданнее: даже мгновенной операции нужно дождаться блокировки, а пока она ждёт, она блокирует всех, кто пришёл после неё. PostgreSQL выдаёт блокировки в порядке очереди. Если длинный отчёт или забытая транзакция держит ACCESS SHARE, ваш ALTER ждёт. Каждый новый запрос, которому нужен ACCESS SHARE, теперь конфликтует с ожидающим запросом на ACCESS EXCLUSIVE и встаёт в очередь за ALTER, вместо того чтобы выполниться.

-- session 1: a long report or a forgotten open transaction
BEGIN;
SELECT count(*) FROM shop_order;  -- holds ACCESS SHARE until COMMIT

-- session 2: the migration
ALTER TABLE shop_order ADD COLUMN note text;  -- waits for ACCESS EXCLUSIVE

-- session 3: an ordinary request from the site
SELECT * FROM shop_order WHERE id = 42;  -- now waits too, behind session 2

Сессия 3 обычно выполняется мгновенно. Теперь она ждёт столько, сколько сессия 1 держит транзакцию открытой. На нагруженном сайте это значит, что застревают все воркеры, и вы получаете аварию из-за миграции, которая заняла бы миллисекунду.

Опасность DDL не только в том, сколько он выполняется, но и в том, сколько он ждёт блокировку, потому что все остальные встают в очередь за ним.

Когда это происходит, вот запрос, который покажет, кто кого блокирует:

SELECT pid,
       pg_blocking_pids(pid) AS blocked_by,
       state,
       now() - xact_start AS xact_age,
       left(query, 60) AS query
FROM pg_stat_activity
WHERE datname = current_database()
  AND state <> 'idle'
ORDER BY xact_start;

Какой DDL что блокирует

Практическая карта для PostgreSQL 16+. «Мгновенно» означает изменение только каталога; «скан» означает чтение каждой строки; «перезапись» означает запись новой копии таблицы.

Операция Блокировка Цена
ADD COLUMN nullable, без default ACCESS EXCLUSIVE мгновенно
ADD COLUMN ... DEFAULT <константа> ACCESS EXCLUSIVE мгновенно (с PG 11)
ADD COLUMN ... DEFAULT <volatile> (now(), gen_random_uuid()) ACCESS EXCLUSIVE перезапись
ALTER COLUMN ... TYPE ACCESS EXCLUSIVE обычно перезапись (кроме, например, расширения varchar, varchar → text)
ALTER COLUMN ... SET NOT NULL ACCESS EXCLUSIVE скан (пропускается, если есть валидный CHECK (col IS NOT NULL))
ADD CONSTRAINT ... CHECK / FOREIGN KEY ACCESS EXCLUSIVE / SHARE ROW EXCLUSIVE скан
ADD CONSTRAINT ... NOT VALID как выше мгновенно
VALIDATE CONSTRAINT SHARE UPDATE EXCLUSIVE скан, но чтение и запись продолжаются
CREATE INDEX SHARE строит индекс, запись заблокирована
CREATE INDEX CONCURRENTLY SHARE UPDATE EXCLUSIVE медленнее, запись продолжается
DROP COLUMN, RENAME COLUMN ACCESS EXCLUSIVE мгновенно

Из таблицы следуют два правила. Первое: всё, что сканирует или переписывает под ACCESS EXCLUSIVE, нужно разбить на шаги, в которых тяжёлая работа идёт под более слабой блокировкой. Второе: даже мгновенным операциям нужен lock_timeout из-за очереди. Начнём со второго, это самое дешёвое исправление.

lock_timeout: лучше упасть быстро, чем заморозить сайт

lock_timeout ограничивает, сколько оператор может ждать блокировку. Если блокировку не удалось получить вовремя, оператор падает с canceling statement due to lock timeout, транзакция откатывается, и очередь за ней освобождается. Упавшая миграция, которую можно повторить, гораздо лучше замёрзшего сайта.

В PostgreSQL Django выполняет каждую миграцию внутри транзакции (если не указано atomic = False), поэтому SET LOCAL действует ровно на эту миграцию и сбрасывается при коммите:

# shop/migrations/0002_order_total_tiyin.py
from django.db import migrations, models


class Migration(migrations.Migration):
    dependencies = [("shop", "0001_initial")]

    operations = [
        migrations.RunSQL(
            "SET LOCAL lock_timeout = '3s'",
            reverse_sql="SET LOCAL lock_timeout = '3s'",
        ),
        migrations.AddField(
            model_name="order",
            name="total_tiyin",
            field=models.BigIntegerField(null=True),
        ),
    ]

Не путайте с statement_timeout: он ограничивает общее время выполнения, включая саму работу. Для DDL нужен в основном lock_timeout; для backfill, скорее всего, ни то, ни другое.

Раз lock timeout это ожидаемый исход, деплой должен повторять попытку, а не сдаваться. Грубый, но рабочий вариант:

for attempt in 1 2 3 4 5; do
  python manage.py migrate --noinput && break
  echo "migrate failed (attempt $attempt), retrying in 10s..."
  sleep 10
done

Этот цикл повторяет при любой ошибке, не только при lock timeout, поэтому держите число попыток небольшим и смотрите в лог, если падает раз за разом. И помните: внутри одной миграции блокировки накапливаются. Если миграция трогает три таблицы, она держит все три блокировки до коммита. Маленькие миграции держат это окно коротким.

Как безопасно добавить колонку NOT NULL

Сначала хорошая новость. Начиная с PostgreSQL 11, ADD COLUMN ... NOT NULL DEFAULT 'UZS' с константным default не переписывает таблицу: значение хранится в каталоге и возвращается для старых строк. Django для поля с default= генерирует именно это, а затем удаляет default в базе. Так что константный default безопасен (с lock_timeout).

Сложный случай, когда значение нужно вычислить для каждой строки. Допустим, мы переводим деньги с Decimal на целые тийины и нужна колонка total_tiyin, заполненная из total. Константный default тут бессмыслен, а ADD COLUMN ... NOT NULL без default на непустой таблице упадёт. План: расширить, заполнить, затем ужесточить:

-- 1. nullable column, no default: metadata only, instant
ALTER TABLE shop_order ADD COLUMN total_tiyin bigint;

-- 2. backfill in small batches, each in its own transaction (see below)

-- 3. constraint that is NOT checked against existing rows: instant
ALTER TABLE shop_order ADD CONSTRAINT order_total_tiyin_nn
    CHECK (total_tiyin IS NOT NULL) NOT VALID;

-- 4. full scan, but under SHARE UPDATE EXCLUSIVE: reads and writes continue
ALTER TABLE shop_order VALIDATE CONSTRAINT order_total_tiyin_nn;

-- 5. PostgreSQL sees the valid CHECK and skips its own full scan
ALTER TABLE shop_order ALTER COLUMN total_tiyin SET NOT NULL;

-- 6. the CHECK is now redundant
ALTER TABLE shop_order DROP CONSTRAINT order_total_tiyin_nn;

Весь трюк в шаге 5: начиная с PostgreSQL 12, SET NOT NULL пропускает полный скан, если валидный CHECK (col IS NOT NULL) уже доказывает, что NULL нет. Значит, дорогой скан происходит в шаге 4 под SHARE UPDATE EXCLUSIVE, которая не блокирует ни чтение, ни запись.

Теперь то же самое в Django. Сначала модель на переходный период. Новые строки должны быть корректными с момента появления колонки, иначе backfill гоняется за движущейся целью:

# shop/models.py (transition period)
from django.db import models


class Order(models.Model):
    total = models.DecimalField(max_digits=14, decimal_places=2)
    total_tiyin = models.BigIntegerField(null=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def save(self, *args, **kwargs):
        # dual write: new rows are already correct while the backfill runs
        self.total_tiyin = int(self.total * 100)
        super().save(*args, **kwargs)

Миграция 0002 показана в разделе про lock_timeout: nullable BigIntegerField. Дальше backfill. Он не должен быть одним огромным UPDATE: такой запрос держит блокировки строк на всю таблицу всё время выполнения, разом создаёт массу мёртвых кортежей и даёт всплеск WAL, который придётся проигрывать репликам. Маленькие батчи, каждый со своим коммитом, проход по первичному ключу через keyset pagination, чтобы не пересканировать начало таблицы:

# shop/migrations/0003_backfill_total_tiyin.py
from django.db import migrations
from django.db.models import BigIntegerField, F
from django.db.models.functions import Cast

BATCH_SIZE = 5_000


def backfill_total_tiyin(apps, schema_editor):
    Order = apps.get_model("shop", "Order")
    last_pk = 0
    while True:
        ids = list(
            Order.objects.filter(pk__gt=last_pk)
            .order_by("pk")
            .values_list("pk", flat=True)[:BATCH_SIZE]
        )
        if not ids:
            break
        Order.objects.filter(pk__in=ids, total_tiyin__isnull=True).update(
            total_tiyin=Cast(F("total") * 100, output_field=BigIntegerField())
        )
        last_pk = ids[-1]


class Migration(migrations.Migration):
    atomic = False  # every UPDATE commits on its own

    dependencies = [("shop", "0002_order_total_tiyin")]

    operations = [
        migrations.RunPython(backfill_total_tiyin, migrations.RunPython.noop),
    ]

Именно atomic = False делает так, что каждый update() коммитится отдельно. Если миграция упала посередине, её безопасно перезапустить: уже заполненные строки отсекает total_tiyin__isnull=True.

Затем constraint, в двух отдельных миграциях:

# shop/migrations/0004_order_total_tiyin_nn.py
from django.contrib.postgres.operations import AddConstraintNotValid
from django.db import migrations, models


class Migration(migrations.Migration):
    dependencies = [("shop", "0003_backfill_total_tiyin")]

    operations = [
        AddConstraintNotValid(
            model_name="order",
            constraint=models.CheckConstraint(
                condition=models.Q(total_tiyin__isnull=False),
                name="order_total_tiyin_nn",
            ),
        ),
    ]
# shop/migrations/0005_validate_order_total_tiyin_nn.py
from django.contrib.postgres.operations import ValidateConstraint
from django.db import migrations


class Migration(migrations.Migration):
    dependencies = [("shop", "0004_order_total_tiyin_nn")]

    operations = [
        ValidateConstraint(model_name="order", name="order_total_tiyin_nn"),
    ]

Почему отдельных? Если AddConstraintNotValid и ValidateConstraint стоят в одной атомарной миграции, блокировка ACCESS EXCLUSIVE от первой операции держится до коммита, то есть на протяжении всего скана валидации. Вы аккуратно разделили работу и тут же склеили её обратно. Разнесите их по разным миграциям или поставьте atomic = False.

Не забудьте добавить тот же CheckConstraint в Order.Meta.constraints, иначе следующий makemigrations сгенерирует RemoveConstraint.

Наконец колонка становится NOT NULL, а вспомогательный constraint удаляется (уберите его и из Meta.constraints):

# shop/migrations/0006_order_total_tiyin_not_null.py
from django.db import migrations, models


class Migration(migrations.Migration):
    dependencies = [("shop", "0005_validate_order_total_tiyin_nn")]

    operations = [
        migrations.RunSQL(
            "SET LOCAL lock_timeout = '3s'",
            reverse_sql="SET LOCAL lock_timeout = '3s'",
        ),
        migrations.AlterField(
            model_name="order",
            name="total_tiyin",
            field=models.BigIntegerField(),
        ),
        migrations.RemoveConstraint(
            model_name="order",
            name="order_total_tiyin_nn",
        ),
    ]

Перед мержем посмотрите, какой SQL Django выполнит на самом деле:

python manage.py sqlmigrate shop 0006

Там должны быть SET NOT NULL и DROP CONSTRAINT, без UPDATE. Если бы у поля был default, Django сначала выдал бы UPDATE ... SET total_tiyin = ... WHERE total_tiyin IS NULL, и sqlmigrate существует как раз для таких сюрпризов.

Индексы: CREATE INDEX CONCURRENTLY

Обычный CREATE INDEX держит блокировку SHARE: чтение работает, но каждый INSERT, UPDATE и DELETE в таблицу ждёт, пока индекс не построится. CREATE INDEX CONCURRENTLY берёт SHARE UPDATE EXCLUSIVE и строит индекс в несколько проходов, пока запись продолжается. Цена: он медленнее, ждёт транзакции, начавшиеся до него, и не может выполняться внутри блока транзакции.

В Django для этого есть готовая операция в django.contrib.postgres:

# shop/migrations/0007_order_created_at_idx.py
from django.contrib.postgres.operations import AddIndexConcurrently
from django.db import migrations, models


class Migration(migrations.Migration):
    atomic = False  # CREATE INDEX CONCURRENTLY cannot run inside a transaction

    dependencies = [("shop", "0006_order_total_tiyin_not_null")]

    operations = [
        AddIndexConcurrently(
            model_name="order",
            index=models.Index(fields=["created_at"], name="order_created_at_idx"),
        ),
    ]

makemigrations генерирует обычный AddIndex; замените его вручную на AddIndexConcurrently и добавьте atomic = False. Для удаления есть RemoveIndexConcurrently.

Если конкурентное построение упало (deadlock, нарушение уникальности, отменённый запрос), PostgreSQL оставляет невалидный индекс. Для чтения он не используется, но обновляется при каждой записи. Найдите и удалите его перед повтором:

-- indexes left behind by a failed CREATE INDEX CONCURRENTLY
SELECT indexrelid::regclass AS index_name
FROM pg_index
WHERE NOT indisvalid;

-- drop it without blocking writes, then run the migration again
DROP INDEX CONCURRENTLY IF EXISTS order_created_at_idx;

Удаление и переименование колонок: два деплоя

Здесь проблема не в блокировках. DROP COLUMN мгновенный. Проблема в том, что во время rolling deploy старый и новый код одновременно работают с одной базой.

Django никогда не пишет SELECT *: он перечисляет все колонки модели по именам. Если миграция удалит legacy_status, пока старые поды ещё обслуживают трафик, каждый запрос старого кода упадёт с column "legacy_status" does not exist. Обратное тоже ломается: если колонка NOT NULL без default в базе, а новый код о ней больше не знает, каждый INSERT нового кода упадёт.

Поэтому изменение делится на два релиза.

Деплой 1. Уберите поле из модели, но только из состояния Django, и сделайте колонку nullable, чтобы вставки нового кода работали:

# deploy 1: shop/migrations/0008_remove_legacy_status_from_state.py
from django.db import migrations


class Migration(migrations.Migration):
    dependencies = [("shop", "0007_order_created_at_idx")]

    operations = [
        migrations.SeparateDatabaseAndState(
            # Django forgets the field: new code no longer SELECTs or INSERTs it
            state_operations=[
                migrations.RemoveField(model_name="order", name="legacy_status"),
            ],
            # the column stays, but must accept rows that new code inserts
            database_operations=[
                migrations.RunSQL(
                    "ALTER TABLE shop_order "
                    "ALTER COLUMN legacy_status DROP NOT NULL",
                    reverse_sql=migrations.RunSQL.noop,
                ),
            ],
        ),
    ]

Деплой 2, после того как все поды работают на коде, который больше не упоминает поле:

# deploy 2: shop/migrations/0009_drop_legacy_status_column.py
from django.db import migrations


class Migration(migrations.Migration):
    dependencies = [("shop", "0008_remove_legacy_status_from_state")]

    operations = [
        migrations.RunSQL(
            "SET LOCAL lock_timeout = '3s'",
            reverse_sql=migrations.RunSQL.noop,
        ),
        migrations.RunSQL(
            "ALTER TABLE shop_order DROP COLUMN IF EXISTS legacy_status",
            reverse_sql=migrations.RunSQL.noop,
        ),
    ]

С переименованием та же история, только хуже: нет момента, когда существуют оба имени. Если вам нужно лишь более красивое имя в Python, базу не трогайте вообще:

from django.db import models


class Order(models.Model):
    # the Python name changes; the column in PostgreSQL stays "amount"
    total = models.DecimalField(max_digits=14, decimal_places=2, db_column="amount")

sqlmigrate для получившейся миграции не должен показывать переименование колонки. Если новое имя действительно нужно в базе, используйте expand/contract: добавьте новую колонку, пишите в обе, заполните, переключите чтение и удалите старую колонку в следующем деплое, как показано выше.

Подводные камни в продакшене

  • default=uuid.uuid4 в AddField. Django вызывает callable один раз при генерации SQL и использует это значение как DEFAULT для всех существующих строк. Все старые строки получают одинаковый UUID, и миграция с unique=True падает. Добавьте колонку nullable, заполните построчно, затем ужесточите.
  • Сессии idle in transaction. Соединение, которое сделало BEGIN и ушло вызывать внешний API, всё это время держит свои блокировки. lock_timeout спасёт сайт, но миграция всё равно не продвинется. Ищите state = 'idle in transaction' в pg_stat_activity и настройте idle_in_transaction_session_timeout.
  • Дыры в dual write. QuerySet.update(), bulk_create(), сырой SQL и save(update_fields=[...]) обходят логику save() выше. Проверьте все пути записи или, раз backfill можно перезапускать, прогоните его ещё раз прямо перед VALIDATE.
  • Внешние ключи. Добавление ForeignKey создаёт и индекс, и constraint, а constraint блокирует обе таблицы и сканирует ссылающуюся. На большой таблице подумайте о разбиении через RunSQL на конкурентный индекс и constraint NOT VALID, затем VALIDATE.
  • Смена типа. ALTER COLUMN TYPE из integer в bigint переписывает таблицу под ACCESS EXCLUSIVE. Делайте это как новую колонку плюс backfill, а не как AlterField.
  • CONCURRENTLY ждёт старые транзакции. Он не блокирует других, но ждёт транзакции, начавшиеся до него, так что длинный отчёт может затормозить сам шаг миграции.
  • Лаг репликации. Каждый батч backfill превращается в WAL, который реплики должны применить. Если вы читаете с реплик, следите за лагом и добавьте короткую паузу между батчами, если он растёт.

Чеклист

  • Для каждой миграции запускайте sqlmigrate и читайте SQL, а не только Python.
  • Ставьте SET LOCAL lock_timeout в начало каждой атомарной миграции, которая трогает большую или горячую таблицу, и пусть деплой повторяет попытки.
  • Ничто, что сканирует или переписывает большую таблицу, не выполняется под ACCESS EXCLUSIVE.
  • NOT NULL с вычисляемым значением: nullable-колонка, dual write, backfill батчами, CHECK ... NOT VALID, VALIDATE в отдельной миграции, SET NOT NULL, удаление CHECK.
  • Индексы на живых таблицах: AddIndexConcurrently с atomic = False; после сбоев проверяйте невалидные индексы.
  • Удаляйте и переименовывайте колонки в два деплоя: сначала код перестаёт их использовать, затем база их удаляет.
  • Перед большой миграцией загляните в pg_stat_activity на предмет длинных транзакций.

Итог

Миграция опасна по двум причинам: она может держать сильную блокировку во время тяжёлой работы, а может встать в очередь за блокировкой и затянуть в эту очередь все остальные запросы. Лечение каждый раз одно: вынести тяжёлую часть под более слабую блокировку (NOT VALID + VALIDATE, CONCURRENTLY, backfill батчами), держать шаги с сильной блокировкой крошечными и защищать их lock_timeout. А пока старый и новый код делят одну базу, давайте изменению схемы два деплоя вместо одного.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯