Déploiement d’une API NestJS et Prisma sans erreurs de relation ou P1001

Presque toutes les fonctionnalités backend que l’équipe développe par la suite, de l’authentification à la multi-tenancy et au contrôle d’accès basé sur les rôles, reposent sur les premières heures de configuration du projet. Si les variables d’environnement, la connexion à la base de données, les relations entre schémas et les migrations sont mal configurées au début, chaque demande de fusion ultérieure hérite de ce désordre. Ce guide explique comment mettre en place une API NestJS soutenue par Prisma et PostgreSQL, décrit les trois problèmes qui entravent le plus souvent ce premier objectif, et vous fournit une liste de contrôle pour savoir quand les fondations sont réellement posées.

À quoi ressemble un bootstrap terminé

Il est utile de définir l’objectif avant même d’utiliser la CLI. Un bootstrap est complet lorsque quelqu’un qui le examine peut cloner la branche et confirmer ce qui suit :

Prisma connecté à une base de données PostgreSQL

Configuration chargée à partir de variables d’environnement plutôt que de valeurs codées en dur

Un ensemble initial de modèles de données reflétant le domaine

Une migration qui s’applique correctement à une base de données vide

Une demande de fusion ciblée que le reste de l’équipe peut examiner et intégrer

Les contraintes sont délibérément restreintes : NestJS et Prisma comme seuls framework et ORM, PostgreSQL comme base de données, ainsi que les conventions existantes de l’équipe pour la configuration et Git.

L’ensemble d’outils

• Framework et langage : NestJS avec TypeScript
• Accès aux données : prisma (l’interface en ligne de commande) et @prisma/client (le client de requêtes généré)
• Configuration : @nestjs/config
• Base de données : une instance locale PostgreSQL
• Vérification : la Prisma CLI, ainsi qu’un navigateur ou un client API pour appeler les points de terminaison

Mise en place du squelette du projet

Commencez par générer une application neuve à l’aide de la Nest CLI, puis ajoutez Prisma et initialisez-le au sein du projet. L’initialisation crée un répertoire prisma/ pour le schéma et les migrations, tandis que le code de votre application reste dans src/.

Ensuite, créez un fichier .env contenant DATABASE_URL, la chaîne de connexion PostgreSQL que Prisma lit. Chargez les paramètres de configuration via le module @nestjs/config afin que l’application récupère les valeurs de l’environnement plutôt que des valeurs littérales dispersées dans le code. Assurez-vous que .env figure dans .gitignore ; commiter des identifiants réels dès la première proposition de modification est une erreur facile à commettre et difficile à corriger.

la mise en place de Prisma 7 avec PostgreSQL dans un projet TypeScript Node.js, et consultez la documentation actuelle de Prisma pour des informations spécifiques à chaque version.

Modélisation des premières entités

• Tenant, représentant une organisation utilisant le système
• User, représentant une personne qui se connecte
• Role, pour l’affectation de rôles de base au sein d’un locataire
• Invite, pour intégrer de nouveaux utilisateurs dans un locataire

Ensemble, ils définissent ce dont dépendront les fonctionnalités ultérieures : les utilisateurs appartiennent à des locataires, occupent des rôles et arrivent via des invitations. Chaque relation nécessite un champ des deux côtés, ce qui est la cause du premier erreur mentionné ci-dessous.

Lorsque le schéma a été validé, exécutez la migration initiale afin que la structure de la base de données corresponde au schéma. Veillez à ce qu’elle ne contienne aucune expérience, car chaque collègue va l’appliquer localement.

Ajout d’un point de terminaison de santé

Du côté de l’API, ajoutez un seul contrôleur qui expose /health et renvoie simplement OK. Cela semble trivial, mais cela sert à une fin réelle : il vous permet, à votre pipeline CI et éventuellement à votre balanceur de charge ou orchestrateur, d’avoir un moyen simple de vérifier si le processus est en cours d’exécution et traite les requêtes.

Trois erreurs qui bloquent fréquemment le premier jalon

Prisma rejette une relation sans champ correspondant

Symptôme : la validation du schéma échoue, indiquant qu’une relation manque de son champ correspondant.

Cause : Prisma exige que les relations soient déclarées dans les deux modèles. Si User fait référence à Tenant mais que Tenant ne possède aucun champ listant ses utilisateurs, le schéma est incomplet du point de vue de Prisma.

Résolution : ajoutez les champs de référence manquants dans les modèles concernés, puis exécutez prisma format. Ce outil normalise le fichier et peut compléter automatiquement les champs de relation absents, il est donc conseillé de l’utiliser après chaque modification du schéma.

P1001 : impossible d’accéder au serveur de base de données

Symptôme : Prisma affiche le code d’erreur P1001 et ne parvient pas à se connecter à PostgreSQL.

Cause : généralement l’une de deux choses. Soit le serveur PostgreSQL n’est pas en cours d’exécution, soit le port indiqué dans DATABASE_URL ne correspond pas au port sur lequel le serveur écoute.

Résolution : vérifier que le processus de base de données est bien en cours d’exécution localement, puis comparer l’hôte et le port indiqués dans la chaîne de connexion avec la configuration réelle du serveur.

Une demande de fusion qui semble supprimer tout le contenu

Symptôme : un examinateur ouvre la demande de fusion et constate que tous les fichiers du répertoire ont été supprimés.

Cause : le commit a été effectué à partir d’un état Git incorrect, ce qui fait que la comparaison diffère fortement de ce qui était prévu.

Résolution : au lieu de tenter de réparer cette histoire complexe, créez une branche nouvelle à partir de la base correcte et appliquez uniquement les modifications prévues. Exécuter git status et examiner git diff par rapport à la branche cible avant de pousser permet de détecter ce type d’erreur tôt.

Vérification de la configuration

La vérification doit être répétable de manière monotone :

• Exécutez npx prisma migrate dev et confirmez que la migration s’applique sans erreur
• Démarrez le serveur NestJS
• Ouvrez /health dans un navigateur ou un client API et vérifiez la réponse OK

Lorsque la migration s’effectue correctement et que l’endpoint de santé répond, les bases sont prêtes pour la prochaine fonctionnalité.

Points clés

• Considérez le bootstrap comme un produit final avec des critères d’acceptation explicites, et non comme un squelette temporaire.

Déclarez chaque relation Prisma des deux côtés et laissez prisma format maintenir le schéma organisé.

Lorsque vous voyez P1001, vérifiez que PostgreSQL est en cours d’exécution et que le port indiqué dans DATABASE_URL est correct avant de chercher d’autres causes de problème.

Un point de contrôle de santé ne prend que quelques minutes mais s’avère utile pour les tests d’intégration continue, la surveillance et les vérifications de déploiement.

Des demandes de fusion petites, ciblées et présentant un historique propre font partie intégrante du travail d’ingénierie, et non une mesure ajoutée ultérieurement.

Lectures complémentaires

• Déployer NestJS sur Bun et Prisma 7 vers Cloud Run sans les erreurs de construction — Un pipeline GitHub Actions fonctionnel pour déployer une application NestJS sur Bun avec Prisma 7 et Neon vers Cloud Run, ainsi que les corrections Docker et de connexion qui posent problème aux équipes.
• MovieVault Walkthrough : une API de liste de suivi avec Express 5, Prisma 7 et JWT — Une spécification d’exercice full-stack chronométré ainsi que son backend basé sur Express, Prisma et JWT, accompagnée de notes d’analyse concernant les vérifications de propriété, les cascades et la gestion des erreurs.