• user_progress.user_id - первичный ключ, а PostgreSQL создаёт под PK уникальный индекс автоматически. Второй индекс на тот же столбец - точная копия, которая только замедляет запись.
• completions.user_id - ведущий столбец составного UNIQUE (user_id, lesson_id). Запросы вида WHERE user_id = $1 этот индекс используют, как разобрано в уроке Индексы: составной индекс работает по префиксу столбцов.

Единственный сценарий, в котором отдельный узкий индекс оправдан, - когда запросов по user_id очень много, а составной индекс заметно шире, поэтому хуже помещается в кэш. Это решается замером EXPLAIN (ANALYZE, BUFFERS) на реальных данных, а не добавлением индекса на всякий случай: каждый индекс - это цена на каждом INSERT в completions, а пишем мы туда в той же транзакции, что и в read model.

HTTP Handler

// internal/handler/lesson_handler.go

func (h *LessonHandler) CompleteLesson(w http.ResponseWriter, r *http.Request) {
    userID := middleware.UserIDFromContext(r.Context())
    lessonID := chi.URLParam(r, "lessonID")
    trackID := chi.URLParam(r, "trackID")

    err := h.completeLesson.Execute(r.Context(), usecase.CompleteLessonInput{
        UserID:   userID,
        LessonID: lessonID,
        TrackID:  trackID,
    })
    if err != nil {
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }

    w.WriteHeader(http.StatusNoContent)
}

func (h *LessonHandler) GetProgress(w http.ResponseWriter, r *http.Request) {
    userID := middleware.UserIDFromContext(r.Context())

    progress, err := h.getProgress.Execute(r.Context(), userID)
    // Разные причины - разные коды. Одна ветка `if err != nil` с 404
    // превратила бы недоступную базу в «нет такого пользователя»:
    // клиент перестал бы повторять запрос, а мониторинг увидел бы 404
    // вместо ошибки сервера.
    switch {
    case errors.Is(err, domain.ErrProgressNotFound):
        http.Error(w, "not found", http.StatusNotFound)
        return
    case err != nil:
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }

    json.NewEncoder(w).Encode(progress)
}

Docker Compose для разработки

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: cqrs_demo
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    healthcheck:
      test: pg_isready -U app
      interval: 5s
      retries: 5

  api:
    build: .
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://app:secret@postgres:5432/cqrs_demo
    ports:
      - "8080:8080"

Только postgres и api - никаких брокеров. Это и есть чистый CQRS без event-driven.

Тест use case

func TestCompleteLessonUseCase(t *testing.T) {
    db := testdb.Open(t) // тестовая БД из testcontainers
    repo := repository.NewCompletionRepo(db)
    progressRepo := repository.NewProgressRepo(db)
    uc := usecase.NewCompleteLessonUseCase(repo, progressRepo, db)

    userID := uuid.New()
    err := uc.Execute(context.Background(), usecase.CompleteLessonInput{
        UserID:   userID,
        LessonID: "go-01",
        TrackID:  "go",
    })
    require.NoError(t, err)

    // Проверяем write model
    completions, _ := repo.FindByUser(context.Background(), userID)
    assert.Len(t, completions, 1)

    // Проверяем read model
    progress, _ := progressRepo.Get(context.Background(), userID)
    assert.Equal(t, 1, progress.CompletedLessons)
}

Типичная ошибка

Обновлять read model асинхронно (через фоновую горутину или брокер), когда в этом нет необходимости. Если read model обновляется в той же транзакции - он всегда консистентен, нет eventual consistency, нет задержек. Брокер нужен, когда событие должны обработать несколько систем - тогда смотри Message Brokers.

Мини-задание

• Реализуй CompletionRepository.SaveTx и ProgressRepository.UpdateTx принимающие *sql.Tx
• Добавь UNIQUE constraint и проверь что повторный вызов возвращает специфичную ошибку (не 500)
• Напиши интеграционный тест с testcontainers: PostgreSQL без моков
• Добавь endpoint GET /api/users/:id/completions возвращающий полный список пройденных уроков из write model