---
id: add-nullable-column-to-list-endpoint
type: recipe
title: Добавить nullable-колонку в эндпоинт списка, не расширяя select
status: validated
confidence: high
applicability: Административная панель с серверным рендерингом, где запрос списка перечисляет колонки явно
tags: [php, sql, migration, api]
created_at: 2026-10-01
updated_at: 2026-10-22
last_verified_at: 2026-10-22
source: agent execution
related: [retry-migration-until-it-passes]
---

# Пример: рецепт

## Problem

На экране списка нужно показать ещё одно поле. Соблазнительная правка — `SELECT *`, которая тихо меняет
выдачу трёх других эндпоинтов, использующих тот же построитель запросов.

## When to use

- Колонка уже есть в таблице либо миграция добавляет её как nullable.
- Запрос списка перечисляет колонки явно.
- Поле только для отображения: фильтрация и сортировка не добавляются.

## When not to use

- Колонка вычисляется из других таблиц: меняется join, а не select.
- Эндпоинт кешируется по сессии: новое поле появится позже и будет выглядеть дефектом.
- Колонка не nullable, а таблица большая: миграция блокирует таблицу.

## Prerequisites

- Доступ к схеме живой таблицы, а не только к миграциям.
- Тест, который уже покрывает эндпоинт, чтобы регресс был виден.

## Inputs

- Настоящее имя колонки.
- Условие приёмки: что должен увидеть ревьюер.

## Procedure

1. Прочитать миграцию, создавшую колонку, и подтвердить реальное имя. `[факт]` из файла.
2. Подтвердить допустимость NULL; не-nullable колонка требует сначала бэкфилла.
3. Добавить поле в явный список выборки.
4. Добавить его в presenter, отформатировав значение (даты в ISO, NULL как тире).
5. Дополнить существующий тест одной строкой с NULL.
6. Прогнать набор тестов.

## Commands or code

```text
# Только очищенный пример. Имена — заполнители.
grep -n "<column_name>" migrations/*.sql
php tests/run.php --filter <endpoint_name>
```

## Expected result

Эндпоинт отдаёт новое поле; экран рисует дату для строк, где она есть, и `<dash>` для остальных.
Выдача ни одного другого эндпоинта не меняется.

## Validation

- Набор тестов зелёный.
- Одно утверждение на строке с NULL.
- `git diff --stat` затрагивает ровно список выборки, presenter и тест.

## Rollback

Откатить правки списка выборки и presenter. Схема не меняется, поэтому откат — один revert-коммит.
Если добавлялась nullable-колонка, её удаление — отдельное действие и требует правила резервной копии.

## Known failures

- `retry-migration-until-it-passes` — вариант миграции, скрывающий частичное применение.
- Тире в подмножестве шрифта (кириллица или латиница): символ может отсутствовать в subset — проверять
  на отрисованной странице, а не в исходнике.