À propos de ce cours
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.
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 / option | Effet 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: true | UNIQUE 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: true | tinyint DEFAULT 1, relu comme true |
nullable: true | DEFAULT NULL; sans cette option, toutes les colonnes sont NOT NULL |
@CreateDateColumn, @UpdateDateColumn | datetime(6) remplis par MySQL ; relus comme des Date |
@Index(['nom', 'prenom']) | index composé pour accélérer les recherches par nom |
select: false | la 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
| Besoin | Option type | Type 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' + enum | un 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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !