Index et contraintes

Cette page recense chaque index, chaque contrainte d'unicité, chaque clé étrangère et chaque contrainte CHECK de la base, telle que la créent les migrations de backend/prisma/migrations/, avec la requête ou l'invariant qui la justifie.

Les index sont déclarés dans backend/prisma/schema.prisma par @id, @unique, @@unique et @@index. Les contraintes CHECK n'ont pas d'équivalent dans le schéma Prisma : elles sont écrites à la main dans la migration 20261109213843_infra_indexes_timestamptz_checks.

#Clés primaires

Chaque table a une clé primaire <Table>_pkey sur la colonne id, de type texte. PostgreSQL crée pour chacune un index B-tree unique.

Les UUID v7 commencent par un horodatage : les nouvelles lignes s'ajoutent en fin d'index, ce qui limite la fragmentation par rapport à des UUID v4 aléatoires.

#Contraintes d'unicité

#Unicité retirée : Ticket.transactionHash

La migration init avait créé Ticket_transactionHash_key, un index unique sur Ticket(transactionHash) : en mode simulé, une transaction fictive produisait un ticket. Sur la chaîne, un appel buyTickets(3) émet un seul événement pour trois tickets, qui partagent le même hachage. La migration 20261111150000_onchain_wallets_tickets_indexer :

1. crée l'index simple Ticket_transactionHash_idx ;
2. supprime l'index unique Ticket_transactionHash_key ;
3. crée l'index unique Ticket_lotteryId_ticketIndex_key.

L'ordre garantit qu'un index sur le hachage existe à tout moment pendant la migration.

#Valeurs NULL dans les index uniques

PostgreSQL considère deux NULL comme distincts dans un index unique. Conséquences voulues :

• plusieurs comptes peuvent avoir email à NULL ;
• les tickets simulés, dont ticketIndex est NULL, ne sont pas contraints par Ticket_lotteryId_ticketIndex_key.

#Index simples

#Pourquoi indexer les clés étrangères

PostgreSQL n'indexe pas automatiquement les colonnes de clé étrangère. Sans index, supprimer ou modifier une ligne parente oblige la base à parcourir toute la table enfant pour appliquer RESTRICT, CASCADE ou SET NULL, en tenant un verrou pendant ce parcours. La migration 20261109213843 a ajouté un index sur chaque clé étrangère existante, et la migration suivante a fait de même pour Partner.ownerId.

#Index composites

Les index (userId, purchasedAt), (userId, createdAt), (userId, claimedAt), (eventType, timestamp) et (status, submittedAt) mettent la colonne d'égalité en premier et la colonne de tri en second. Une requête « les 20 derniers éléments de tel compte » lit directement les bonnes entrées dans l'ordre, sans tri. Ces index servent aussi les requêtes qui ne filtrent que sur la première colonne ; c'est pourquoi il n'existe pas d'index séparé sur Ticket(userId) ou PointTransaction(userId).

#Clés étrangères

Toutes ont ON UPDATE CASCADE, valeur générée par Prisma ; les clés primaires n'étant jamais modifiées, cela n'a pas d'effet pratique.

RESTRICT sur les tickets, les mouvements de points et les échanges interdit de supprimer un compte qui a une activité. La suppression RGPD contourne ce point par l'anonymisation de la ligne User (voir Portefeuilles intégrés).

Les deux clés de IdentityDocument sont créées directement, sans NOT VALID : la table est nouvelle et vide au moment de la migration. Partner_ownerId_fkey a été ajoutée en NOT VALID puis validée par VALIDATE CONSTRAINT. Sur une table existante, cela évite de bloquer les écritures pendant la vérification des lignes ; voir Migrations.

#Contraintes CHECK

Les cinq contraintes sont ajoutées en NOT VALID puis validées dans la même migration. La règle, posée par la décision d'architecture sur les migrations, est que les invariants critiques sont garantis par la base et non seulement par le code.

Une violation remonte à l'application comme une erreur PostgreSQL de code 23514 (ou Prisma P2004). Le gestionnaire d'erreurs backend/src/middlewares/error.middleware.ts la traduit en HTTP 409 « L'opération viole une règle d'intégrité des données (solde ou stock insuffisant) ». De même, une violation d'unicité (23505 ou P2002) donne une 409 « Cette ressource existe déjà ». Le contrôle applicatif préalable (Solde d'EtherPoints insuffisant, stock épuisé) traite le cas normal avec un message précis ; la contrainte ne sert que dans les courses.

#Ce qui n'est pas contraint