Как мы обошли конфликт Alembic и PostGIS: почему стандартные инструменты миграции подвели?

Когда команда ItFox работала над проектом Velo – сервисом доставки а-ля «Яндекс.Еда» только для Нигерии, с технической стороны проект оказался нетривиальным — особенно на старте, когда закладывались ключевые архитектурные решения.

Один из серьезных вызовов, с которым мы столкнулись, — конфликт между Alembic и PostGIS. Ниже делимся, как решали проблему, что пробовали, и к какому решению пришли в итоге.

Контекст: зачем нам вообще PostGIS?

На Velo мы использовали PostgreSQL как основную СУБД. Так как сервис доставки по определению работает с геоданными, нам понадобилось расширение PostGIS — оно добавляет поддержку пространственных типов данных и операций к PostgreSQL. Он может хранить точки, линии, полигоны, различные 3D-объекты, может работать с координатами в различных системах и прочее.

Параллельно с этим мы использовали Alembic — стандартный инструмент для управления миграциями в SQLAlchemy. Именно он и стал источником основной боли.

Проблема: Alembic «не дружит» с PostGIS.

Чтобы объяснить, как работает Alembic, давайте начнем с простой аналогии.

Представьте себе Excel-файл. В нем есть таблицы — например, «Пользователи». У этой таблицы есть столбцы: имя, фамилия, номер телефона. Сама таблица — это наша база данных, а столбцы — это структура (схема), которая определяет, какие данные можно туда записывать.

Как это обычно бывает, на этапе активной разработки база данных часто меняется. Например, продуктовая команда решила добавить новое поле —  дату рождения клиента, чтобы создавать триггерные события. Просто так открыть базу и добавить колонку нельзя — особенно если проект уже в продакшен. Нужно зафиксировать изменение, чтобы другие члены команды могли воспроизвести его у себя локально и на боевых серверах.

Здесь и вступает в игру Alembic — инструмент, который позволяет создавать миграции: пошаговые инструкции по изменению структуры базы. Это могут быть добавление или удаление колонок, создание новых таблиц, изменение индексов и прочее.

От инструмента миграций требуется надежность и предсказуемость. А в нашем случае произошло следующее. PostGIS работает на уровне PostgreSQL и у него есть свои таблицы, индексы, схемы,  триггеры и прочие компоненты для его полноценной работы. Alembic «не понимал», что это системные объекты и считал, что эти объекты нужно обработать. В результате получались миграции на 1000+ строк бессмысленного кода, содержащие команды по «удалению» встроенных в PostGIS объектов.

Особенно это мешало в начале проекта, когда таблицы создавались часто — каждый такой коммит требовал ручной чистки миграций или отката.

Что мы пробовали?

Разместите
тендер бесплатно

Наша система сама подберет вам исполнителей на услуги, связанные с разработкой сайта или приложения, поисковой оптимизацией, контекстной рекламой, маркетингом, SMM и PR.

Заполнить заявку 13201 тендер
проведено за восемь лет работы нашего сайта.

Путь к решению был не самым прямым. Сначала мы пошли по классике:

1. Пробовали готовые рецепты с форума Alembic и Stack Overflow.
2. Искали решения в документации GeoAlchemy — Python-библиотеки для работы с PostGIS.
3. Экспериментировали с конфигурацией Alembic, чтобы исключить системные схемы из диффов.

Что-то из этого работало частично. Некоторые решения выглядели как костыли. Но ни одно из них не обеспечивало стабильной и чистой миграции.

Наше решение: кастомный Alembic-хелпер.

Ключевая мысль пришла после глубокого изучения документации GeoAlchemy. Там вскользь упоминалось, что универсального решения нет — каждый проект вынужден решать эту проблему по-своему.

Наша идея заключалась в том, чтобы перехватывать объекты миграции до их генерации и исключать из них все, что связано с PostGIS.

Мы написали кастомный Alembic-хелпер, который:

• перебирает все объекты миграции,
• идентифицирует объекты, относящиеся к PostGIS,
• исключает все PostGIS-компоненты из процесса миграции.

Этот скрипт стал частью нашей стандартной инфраструктуры миграций. Он работает в фоновом режиме, не мешает основной разработке, и избавил команду от необходимости вручную чистить каждую автосгенерированную миграцию.

Выводы

1. Некоторые технические риски неочевидны до начала активной разработки. На этапе проектирования многие решения кажутся формальными: выбираем PostgreSQL — добавляем PostGIS, используем SQLAlchemy — берем Alembic. Но при стыковке этих компонентов может всплыть несовместимость, способная затормозить процесс.
2. Система миграций — не вспомогательный инструмент, а основа устойчивой архитектуры. Без точного контроля над изменениями в базе данных проект рискует столкнуться с рассинхронизацией, ошибками на проде и долгими «ручными» обходами.
3. Решение проблемы с PostGIS и Alembic позволило нам избежать технического долга в критически важной части системы. Без этого пришлось бы либо ограничить функциональность, либо мириться с постоянными сбоями, ручной чисткой миграций и риском потери данных.
4. Инвестиции в архитектуру на старте — это экономия времени и денег в будущем. Благодаря кастомному Alembic-хелперу мы заложили масштабируемый фундамент, готовый к росту нагрузки, развитию продукта и расширению команды.

Кастомный Alembic-хелпер — один из примеров, как команда ItFox системно решает задачи. Готовы обсудить ваш проект и предложить архитектуру, которая выдержит не только MVP, но и зрелый highload-продукт. Записывайтесь на бесплатную консультацию или напишите нам в Телеграм.