Перейти к содержанию

Гайд по работе с базой данных

Этот документ описывает правила и архитектуру базы данных Gifty: как безопасно выполнять запросы, где искать схему и как устроены данные.

Глобальный обзор (Overview)

База данных Gifty (PostgreSQL) — это центральное хранилище знаний о товарах, пользователях и логике рекомендаций. Архитектурно данные разделены на несколько ключевых доменов:

  1. Каталог товаров (products): Сердце системы. Здесь хранятся нормализованные данные о товарах, включая цены, описания, ссылки и изображения.
  2. Система парсинга (parsing): Таблицы parsing_sources (реестр магазинов) и category_map (маппинг внешних категорий во внутренние).
  3. Рекомендательный движок (recsys): Включает в себя product_embeddings (векторные представления для семантического поиска) и расширенные атрибуты товаров (психологические профили, "гифтабельность").
  4. Пользователи и сессии (users & auth): Профили пользователей, привязки социальных сетей (OAuth) и история взаимодействий.

Подробное описание схемы

Для получения детальной информации о полях, типах данных и связях между таблицами, обратитесь к разделу автоматической документации моделей:

👉 Подробное описание моделей БД

Роли и ответственность

  • Доступ к базе выдается по необходимости и в рамках вашей роли.
  • Любые изменения схемы должны быть согласованы с ментором или ответственным за БД.

Безопасная работа с данными

  1. Всегда проверяйте окружение, в котором работаете.
  2. Избегайте изменений в проде без явного согласования.
  3. Для массовых обновлений используйте транзакции и делайте предварительный SELECT.
  4. Не выгружайте персональные данные вне защищенных каналов.

Как смотреть схему

  • Используйте DataGrip для навигации по таблицам, индексам и связям.
  • Для сложных объектов ищите миграции в репозитории (каталог alembic).

Alembic

Для управления структурой базы данных мы используем Alembic. Это позволяет безопасно обновлять схему на всех серверах.

Золотые правила:

  1. НИКОГДА не редактируйте существующие файлы миграций в alembic/versions. Если ошиблись — создайте новую миграцию, исправляющую ошибку.
  2. Всегда проверяйте сгенерированный код миграции. Alembic может не заметить переименование колонок или специфичные типы данных.
  3. Миграции автоматически применяются в продакшене при запуске контейнеров.

Основные команды:

# Создать новую миграцию (автогенерация на основе моделей)
alembic revision --autogenerate -m "описание изменений"

# Применить миграции до самой последней версии
alembic upgrade head

# Откатить последнюю миграцию (использовать осторожно!)
alembic downgrade -1

Tip

Тестируйте миграции на локальной БД (alembic upgrade head) перед тем, как открывать Pull Request.

Практики запроса данных

  • Всегда ограничивайте выборку (LIMIT), пока не уверены в объеме.
  • Добавляйте условия по ключам/индексам.
  • Для аналитических запросов используйте отдельные витрины, если они есть.

Частые вопросы

Где взять доступ?

Через телеграм‑бота или у ментора. Инструкции по подключению доступны в онбординге.

Кого спросить, если что-то не так?

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