Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les entités (@Entity, @Column, @PrimaryGeneratedColumn)

Cette leçon apprend à décrire une table MySQL par une classe TypeORM. Une entité Stagiaire complète est exécutée et la table réellement créée (SHOW CREATE TABLE) est affichée en regard : clé primaire,...

0 chapitres 0 QCM Accès gratuit
Les entités (@Entity, @Column, @PrimaryGeneratedColumn)

À propos de ce cours

Cette leçon apprend à décrire une table MySQL par une classe TypeORM. Une entité Stagiaire complète est exécutée et la table réellement créée (SHOW CREATE TABLE) est affichée en regard : clé primaire, longueurs, unicité, nom de colonne, enum, booléen, décimal, texte, colonnes de dates automatiques, index composé et colonne non sélectionnée par défaut. La relecture des données révèle deux pièges réels : les DECIMAL renvoyés sous forme de texte, corrigés par un transformateur, et le type Object des unions string | null qui empêche le démarrage. Activités corrigées.

Objectifs de la leçon

  • Écrire une entité avec @Entity, @PrimaryGeneratedColumn et @Column.
  • Choisir les types et options des colonnes.
  • Utiliser les colonnes automatiques de dates et les index.
  • Éviter les pièges du DECIMAL et des types union.
Une entité = une table

Une entité est une classe décorée par @Entity(): chaque instance correspond à une ligne, chaque propriété décorée par @Column() à une colonne. TypeORM lit les décorateurs et les types TypeScript (grâce à emitDecoratorMetadata, leçon 4.7) pour savoir comment créer la table.

Correspondance entre une entité et une table

Chaque décorateur produit une colonne avec ses contraintes.

Une entité complète

📄 src/stagiaires/stagiaire.entity.ts

import {
  Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn, UpdateDateColumn, ValueTransformer,
} from 'typeorm';

export enum Statut {
  Inscrit = 'inscrit',
  Diplome = 'diplome',
  Abandon = 'abandon',
}

// MySQL renvoie les DECIMAL sous forme de texte : ce transformateur les convertit en nombre
const decimalEnNombre: ValueTransformer = {
  to: (valeur?: number | null) => valeur,
  from: (valeur?: string | null) => (valeur === null || valeur === undefined ? null : Number(valeur)),
};

@Entity('stagiaires')                          // nom de la table
@Index(['nom', 'prenom'])                       // index composé pour les recherches
export class Stagiaire {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 50 })
  nom: string;

  @Column({ length: 50 })
  prenom: string;

  @Column({ length: 120, unique: true })
  email: string;

  @Column({ type: 'char', length: 8, unique: true })
  cin: string;

  @Column({ type: 'date', name: 'date_naissance' })   // nom de colonne différent de la propriété
  dateNaissance: string;

  @Column({ type: 'enum', enum: Statut, default: Statut.Inscrit })
  statut: Statut;

  @Column({ default: true })
  actif: boolean;

  @Column({ type: 'decimal', precision: 7, scale: 3, default: 0 })
  bourse: number;                                     // ⚠ sans transformateur

  @Column({ type: 'decimal', precision: 4, scale: 2, nullable: true, transformer: decimalEnNombre })
  moyenne: number | null;

  @Column({ type: 'text', nullable: true })
  remarques: string | null;

  @Column({ name: 'mot_de_passe_hache', nullable: true, select: false })   // jamais lu par défaut
  motDePasseHache: string;

  @CreateDateColumn({ name: 'cree_le' })
  creeLe: Date;

  @UpdateDateColumn({ name: 'modifie_le' })
  modifieLe: Date;
}

Avec synchronize: true, TypeORM crée la table au démarrage. Le programme affiche ensuite sa définition réelle, enregistre un stagiaire et le relit :

Résultat réellement obtenu :

CREATE TABLE `stagiaires` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `nom` varchar(50) NOT NULL,
  `prenom` varchar(50) NOT NULL,
  `email` varchar(120) NOT NULL,
  `cin` char(8) NOT NULL,
  `date_naissance` date NOT NULL,
  `statut` enum('inscrit','diplome','abandon') NOT NULL DEFAULT 'inscrit',
  `actif` tinyint(4) NOT NULL DEFAULT 1,
  `bourse` decimal(7,3) NOT NULL DEFAULT 0.000,
  `moyenne` decimal(4,2) DEFAULT NULL,
  `remarques` text DEFAULT NULL,
  `mot_de_passe_hache` varchar(255) DEFAULT NULL,
  `cree_le` datetime(6) NOT NULL DEFAULT current_timestamp(6),
  `modifie_le` datetime(6) NOT NULL DEFAULT current_timestamp(6) ON UPDATE current_timestamp(6),
  PRIMARY KEY (`id`),
  UNIQUE KEY `IDX_746c11ce1e2323e7be4333d0e4` (`email`),
  UNIQUE KEY `IDX_cc0f111623ab41e6d6623eb272` (`cin`),
  KEY `IDX_e996be554ca89c190bbc113704` (`nom`,`prenom`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci

Relu depuis la base : Stagiaire {
  id: 1,
  nom: 'Ben Ali',
  prenom: 'Sami',
  email: 'sami@exemple.tn',
  cin: '01234567',
  dateNaissance: '2005-03-14',
  statut: 'inscrit',
  actif: true,
  bourse: '120.500',
  moyenne: 14.25,
  remarques: null,
  motDePasseHache: undefined,
  creeLe: 2026-11-15T07:48:36.273Z,
  modifieLe: 2026-11-15T07:48:36.273Z
}
typeof bourse = string | typeof moyenne = number | typeof actif = boolean | creeLe est une Date ? true
Lecture explicite du mot de passe : $2b$10$abc
Lecture détaillée
Décorateur / optionEffet constaté
@PrimaryGeneratedColumn()id int AUTO_INCREMENT + PRIMARY KEY ('uuid' en argument pour un identifiant UUID)
@Column({ length: 50 })varchar(50) NOT NULL; sans length: varchar(255)
unique: trueUNIQUE KEY au nom généré (IDX_…)
name: 'date_naissance'la colonne s'appelle date_naissance, la propriété reste dateNaissance
type: 'date'relu comme une chaîne '2005-03-14' (pas de problème de fuseau horaire)
type: 'enum'enum('inscrit','diplome','abandon') avec sa valeur par défaut
boolean + default: truetinyint DEFAULT 1, relu comme true
nullable: trueDEFAULT NULL; sans cette option, toutes les colonnes sont NOT NULL
@CreateDateColumn, @UpdateDateColumndatetime(6) remplis par MySQL ; relus comme des Date
@Index(['nom', 'prenom'])index composé pour accélérer les recherches par nom
select: falsela colonne n'est pas lue par find(); il faut la demander explicitement (utile pour les mots de passe, chapitre 13)
Piège n° 1 : DECIMAL relu comme du texte

bourse a été enregistrée avec 120.5 mais relue comme la chaîne '120.500', alors que la propriété est déclarée number. Le pilote MySQL renvoie les DECIMAL en texte pour ne pas perdre de précision (les nombres JavaScript sont approximatifs au-delà de 15 chiffres). Conséquence : stagiaire.bourse + 10 donnerait '120.50010'. Pour moyenne, le transformateur decimalEnNombre convertit la valeur à la lecture : on obtient bien le nombre 14.25.

Pour des montants financiers où chaque centime compte, on peut garder la chaîne et faire les calculs avec une bibliothèque décimale, ou stocker des entiers (millimes, centimes) dans une colonne int.

Piège n° 2 : une union « string | null » sans type
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity('contacts')
export class Contact {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ nullable: true })
  telephone: string | null;          // ✗ TypeScript publie le type « Object » pour une union
}

Au démarrage :

ERREUR : Data type "Object" in "Contact.telephone" is not supported by "mysql" database.

Pour une union de types, TypeScript publie le type Object dans les métadonnées : TypeORM ne sait pas quel type SQL choisir et l'application refuse de démarrer. Dès qu'une propriété est déclarée string | null (ou number | null), il faut préciser le type de colonne : @Column({ type: 'varchar', length: 20, nullable: true }).

Les principaux types de colonnes MySQL
BesoinOption typeType TypeScript
texte court / long'varchar' (+ length) / 'text'string
code de longueur fixe'char'string
entier'int', 'smallint', 'tinyint', 'bigint' (relu en chaîne)number
décimal exact'decimal' + precision, scale (+ transformateur)number ou string
date / date et heure'date' / 'datetime'string / Date
liste fermée'enum' + enumun enum TypeScript
document libre'json'un type ou une interface
Activités

Activité 1 L'entité Groupe

Écrivez l'entité Groupe: code unique de 6 caractères fixes, intitulé (80 caractères), niveau (initiation, perfectionnement, specialisation), capacité (entier court, 20 par défaut), date de début, salle facultative, archivé (booléen faux par défaut), date de création.

Voir le corrigé
export enum Niveau { Initiation = 'initiation', Perfectionnement = 'perfectionnement', Specialisation = 'specialisation' }

@Entity('groupes')
export class Groupe {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ type: 'char', length: 6, unique: true })
  code: string;

  @Column({ length: 80 })
  intitule: string;

  @Column({ type: 'enum', enum: Niveau })
  niveau: Niveau;

  @Column({ type: 'smallint', default: 20 })
  capacite: number;

  @Column({ type: 'date', name: 'date_debut' })
  dateDebut: string;

  @Column({ type: 'varchar', length: 20, nullable: true })     // type explicite : union avec null
  salle: string | null;

  @Column({ default: false })
  archive: boolean;

  @CreateDateColumn({ name: 'cree_le' })
  creeLe: Date;
}

Activité 2 Lire une erreur

Au démarrage : Data type "Object" in "Formation.prix" is not supported by "mysql" database. La propriété est prix: number | null. Corrigez, en gardant des montants exacts.

Voir le corrigé
@Column({ type: 'decimal', precision: 8, scale: 3, nullable: true, transformer: decimalEnNombre })
prix: number | null;

Le type explicite règle l'erreur ; le transformateur évite de recevoir une chaîne. Pour des calculs financiers stricts, préférez des millimes dans une colonne int.

Activité 3 Colonne JSON

Ajoutez à Stagiaire une colonne preferences de type JSON ({ langue: string; notifications: boolean }), facultative. Enregistrez puis relisez une valeur : quel est le type obtenu ?

Voir le corrigé
export interface Preferences { langue: string; notifications: boolean }

@Column({ type: 'json', nullable: true })
preferences: Preferences | null;

La valeur relue est un objet JavaScript. Pratique pour des données sans structure fixe, mais on ne peut ni contraindre ni indexer facilement leur contenu : à réserver aux informations accessoires.

Activité 4 Observer synchronize

Avec synchronize: true et logging: true, renommez la propriété remarques en commentaire (sans option name), relancez et lisez le SQL exécuté. Que sont devenues les remarques déjà saisies ?

Voir le corrigé

TypeORM ne sait pas qu'il s'agit d'un renommage : il exécute ALTER TABLE stagiaires DROP COLUMN remarques puis ADD commentaire. Les remarques sont perdues. C'est exactement la raison pour laquelle synchronize est interdit en production ; une migration écrite (leçon 11.8) utiliserait RENAME COLUMN.

À retenir

  • @Entity('nom_table') + @PrimaryGeneratedColumn() + @Column({ … }) décrivent une table.
  • Options : type, length, nullable, default, unique, name, select ; toutes les colonnes sont NOT NULL par défaut.
  • @CreateDateColumn / @UpdateDateColumn / @DeleteDateColumn : dates gérées automatiquement.
  • DECIMAL est relu en texte : transformateur ou montants entiers.
  • string | null (union) : préciser type, sinon « Data type Object is not supported ».

Cet article vous a-t-il aidé ?