Modèles de données efficaces avec Convex

Convex est le back-end applicatif de NowStack. Les lectures et écritures passent par ses requêtes, mutations et actions afin de centraliser l’authentification, les accès aux organisations et les mises à jour en temps réel.

Modéliser les données dans Convex

Définissez les tables et leurs index dans convex/schema.ts :

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  projects: defineTable({
    organizationId: v.string(),
    name: v.string(),
    status: v.union(v.literal("draft"), v.literal("active")),
  }).index("by_organization", ["organizationId"]),
});

Interroger avec des index

Utilisez les index pour cibler un sous-ensemble de données :

const projects = await ctx.db
  .query("projects")
  .withIndex("by_organization", (q) =>
    q.eq("organizationId", args.organizationId),
  )
  .collect();

Réserver les écritures aux mutations

Les mutations doivent porter les modifications des données applicatives :

await ctx.db.insert("projects", {
  organizationId: args.organizationId,
  name: args.name,
  status: "draft",
});

Utiliser les actions pour les services externes

Utilisez une action lorsqu’une fonction doit appeler Stripe, Resend, Cloudflare R2 ou un autre service externe. Conservez si possible l’écriture en base dans une mutation, appelée par l’action après la réussite de la requête externe.

Conseils pratiques

• Protégez les fonctions liées à une organisation avec les builders partagés.
• Gardez les routes d’API publiques légères et confiez les données à Convex.
• Stockez les secrets du back-end dans l’environnement Convex.
• Ajoutez les index avant d’introduire de nouveaux schémas de requête.
• Utilisez des mappers de DTO partagés lorsqu’une même forme de donnée revient à plusieurs endroits.