Синхронизация профилей пользователей с базой данных
Мы настроили вход в приложение через Clerk: теперь пользователи могут авторизоваться. Но сейчас система напоминает гостиницу, где на ресепшене выдают ключи (Clerk), но в самой гостинице (Convex) нет списка гостей. Чтобы привязывать заказы или настройки к конкретному человеку, нужно перенести данные из системы авторизации в вашу базу данных.
Этот процесс называется синхронизация. Ваша цель — сделать так, чтобы в момент регистрации пользователя в таблице users в Convex автоматически появлялась запись о нем.
Как работает связь между сервисами
Для автоматизации процесса используются Webhooks (вебхуки). Это механизм, при котором один сервис (Clerk) отправляет HTTP-уведомление на адрес другого сервиса (Convex) сразу после события.
Как показано на Схеме 1, вебхук работает как курьер: он доставляет пакет данных о пользователе из Clerk в ваш бэкенд.
Ключевой элемент здесь — User Identity (внешний идентификатор). В Clerk у каждого пользователя есть уникальный ID (например, user_2NHz...). Мы сохраним его в Convex под именем clerkId. Это позволит мгновенно находить «своего» пользователя в базе, зная, кто именно авторизован в браузере.
Подготовка базы данных
Сначала обновим схему данных. Добавим таблицу users для хранения информации от Clerk.
В файле convex/schema.ts опишите таблицу:
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
export default defineSchema({
users: defineTable({
clerkId: v.string(), // ID из системы Clerk
email: v.string(),
name: v.optional(v.string()),
imageUrl: v.optional(v.string()),
}).index("by_clerkId", ["clerkId"]),
});
Создание приемника (Webhook Endpoint)
Теперь нужно создать в Convex URL-адрес, на который Clerk будет присылать данные. В Convex для этого используются httpAction.
Нам важно обеспечить идемпотентность. Это гарантия того, что если Clerk пришлет одно и то же уведомление дважды (например, из-за сбоя сети), в базе не появится дубликат пользователя.
Создайте файл convex/userSync.ts для логики сохранения:
// convex/userSync.ts
import { internalMutation } from "./_generated/server";
import { v } from "convex/values";
export const store = internalMutation({
args: { clerkId: v.string(), email: v.string(), name: v.string(), imageUrl: v.string() },
handler: async (ctx, args) => {
// Проверяем, нет ли уже такого пользователя
const existingUser = await ctx.db
.query("users")
.withIndex("by_clerkId", (q) => q.eq("clerkId", args.clerkId))
.unique();
if (!existingUser) {
await ctx.db.insert("users", args);
}
},
});
Для защиты данных используется библиотека svix. Она проверяет цифровую подпись сообщения, чтобы никто посторонний не мог отправить фальшивые данные в вашу базу.
Настройка в панели Clerk
Чтобы связать сервисы, выполните четыре шага в интерфейсе Clerk:
- Перейдите в раздел Webhooks.
- Нажмите Add Endpoint.
- Вставьте URL вашего Convex-деплоя (найдите его в Dashboard Convex → Deployment Settings) и добавьте в конце
/clerk-webhook. - Выберите событие
user.created.
После сохранения вы получите Webhook Secret. Скопируйте его и добавьте в Environment Variables в Dashboard Convex под именем CLERK_WEBHOOK_SECRET. 🔐
Проверка работы
Проверьте синхронизацию в реальном времени:
- Откройте Dashboard Convex на вкладке Data.
- Зарегистрируйте нового тестового пользователя в своем приложении.
- Убедитесь, что в таблице
usersавтоматически появилась строка с вашими данными.
Если запись появилась — поздравляем! Вы создали надежный мост между аутентификацией и базой данных. Теперь приложение «узнает» пользователей, сохраняя их User Identity.
В следующей теме мы научим ваше MVP работать с нейросетями через Convex Actions, чтобы продукт мог обрабатывать данные с помощью AI.