À propos de ce cours
Objectifs de la leçon
- Comprendre pourquoi les migrations remplacent synchronize en production.
- Configurer la CLI de TypeORM avec un DataSource.
- Générer, relire, exécuter et annuler des migrations.
- Écrire un seeder idempotent.
Pourquoi des migrations ?
Le schéma de la base évolue avec l'application : nouvelle table, nouvelle colonne, index… Avec synchronize, ces changements sont appliqués automatiquement, sans contrôle et avec un risque de perte de données (leçon 11.3, activité 4). Une migration est un fichier de code qui décrit un changement de schéma, dans les deux sens :
up(): appliquer le changement ;down(): l'annuler.
Les migrations sont versionnées avec le code (Git), relues comme le reste, et appliquées dans le même ordre sur chaque base : poste de chaque développeur, serveur de test, production.
Chaque changement de schéma devient un fichier versionné.
Configurer la CLI
La CLI de TypeORM ne connaît pas NestJS : elle a besoin d'un fichier qui exporte un DataSource. On utilise la version compilée (dist/), ce qui évite d'installer ts-node.
📄 src/data-source.ts
import 'dotenv/config';
import { DataSource } from 'typeorm';
// Source de données utilisée par la CLI de TypeORM (migrations) et par les seeders
export default new DataSource({
type: 'mysql',
host: process.env.DB_HOTE,
port: Number(process.env.DB_PORT ?? 3306),
username: process.env.DB_UTILISATEUR,
password: process.env.DB_MOT_DE_PASSE,
database: process.env.DB_NOM,
entities: [__dirname + '/**/*.entity.js'],
migrations: [__dirname + '/migrations/*.js'],
synchronize: false, // ✓ le schéma n'évolue QUE par les migrations
});
📄 package.json (extrait)
{
"scripts": {
"typeorm": "typeorm -d dist/data-source.js",
"migration:generate": "npm run build && npm run typeorm -- migration:generate src/migrations/$npm_config_name",
"migration:create": "typeorm migration:create src/migrations/$npm_config_name",
"migration:run": "npm run build && npm run typeorm -- migration:run",
"migration:revert": "npm run typeorm -- migration:revert",
"migration:show": "npm run typeorm -- migration:show",
"seed": "npm run build && node dist/seeds/seed.js"
}
}
Dans l'application, synchronize passe à false. On peut demander à NestJS d'appliquer les migrations au démarrage (migrationsRun: true et migrations: [...] dans forRootAsync), mais beaucoup d'équipes préfèrent les lancer explicitement lors du déploiement.
Le cycle complet, exécuté
Départ : une base vide et l'entité Groupe (code, intitulé). Puis on ajoute une colonne capacite à l'entité :
📄 src/groupes/groupe.entity.ts (version 2)
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
@Entity('groupes')
export class Groupe {
@PrimaryGeneratedColumn()
id: number;
@Column({ length: 10, unique: true })
code: string;
@Column({ length: 80 })
intitule: string;
@Column({ type: 'smallint', default: 20 }) // ← nouvelle colonne
capacite: number;
}
📄 src/seeds/seed.ts
import 'reflect-metadata';
import source from '../data-source';
import { Groupe } from '../groupes/groupe.entity';
const GROUPES = [
{ code: 'DEV101', intitule: 'Développement web 1', capacite: 20 },
{ code: 'DEV102', intitule: 'Développement web 2', capacite: 18 },
{ code: 'RES201', intitule: 'Réseaux informatiques', capacite: 15 },
];
async function semer() {
await source.initialize();
const depot = source.getRepository(Groupe);
let crees = 0;
let misAJour = 0;
// Idempotent : on cherche chaque groupe par son code ; on le crée ou on le met à jour → relançable sans doublons
for (const donnees of GROUPES) {
const existant = await depot.findOneBy({ code: donnees.code });
if (existant) {
await depot.save(depot.merge(existant, donnees));
misAJour++;
} else {
await depot.save(depot.create(donnees));
crees++;
}
}
console.log(`Seeder : ${crees} créé(s), ${misAJour} mis à jour, ${await depot.count()} groupes en base`);
await source.destroy();
}
semer().catch((e) => {
console.error('Seeder en échec :', e.message);
process.exit(1);
});
Commandes et résultats :
$ npm run build && npm run migration:generate --name=Initialisation
Migration src/migrations/1794728928674-Initialisation.ts has been generated successfully.
$ cat src/migrations/*-Initialisation.ts
import { MigrationInterface, QueryRunner } from "typeorm";
export class Initialisation1794728928674 implements MigrationInterface {
name = 'Initialisation1794728928674'
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`CREATE TABLE \`groupes\` (\`id\` int NOT NULL AUTO_INCREMENT, \`code\` varchar(10) NOT NULL, \`intitule\` varchar(80) NOT NULL, UNIQUE INDEX \`IDX_eaeaaf5cb24d2ab58e7ec9184f\` (\`code\`), PRIMARY KEY (\`id\`)) ENGINE=InnoDB`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`DROP INDEX \`IDX_eaeaaf5cb24d2ab58e7ec9184f\` ON \`groupes\``);
await queryRunner.query(`DROP TABLE \`groupes\``);
}
}
$ npm run build && npm run migration:run
query: SELECT version() as version
query: SELECT * FROM `INFORMATION_SCHEMA`.`COLUMNS` WHERE `TABLE_SCHEMA` = ? AND `TABLE_NAME` = ? -- PARAMETERS: ["ch11_s118","migrations"]
query: CREATE TABLE `migrations` (`id` int NOT NULL AUTO_INCREMENT, `timestamp` bigint NOT NULL, `name` varchar(255) NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB
query: SELECT * FROM `ch11_s118`.`migrations` `migrations` ORDER BY `id` DESC
0 migrations are already loaded in the database.
1 migrations were found in the source code.
1 migrations are new migrations must be executed.
query: START TRANSACTION
query: CREATE TABLE `groupes` (`id` int NOT NULL AUTO_INCREMENT, `code` varchar(10) NOT NULL, `intitule` varchar(80) NOT NULL, UNIQUE INDEX `IDX_eaeaaf5cb24d2ab58e7ec9184f` (`code`), PRIMARY KEY (`id`)) ENGINE=InnoDB
query: INSERT INTO `ch11_s118`.`migrations`(`timestamp`, `name`) VALUES (?, ?) -- PARAMETERS: [1794728928674,"Initialisation1794728928674"]
Migration Initialisation1794728928674 has been executed successfully.
query: COMMIT
$ (ajout de la colonne capacite dans l'entité) npm run build && npm run migration:generate --name=AjoutCapacite
Migration src/migrations/1794728932295-AjoutCapacite.ts has been generated successfully.
$ cat src/migrations/*-AjoutCapacite.ts
import { MigrationInterface, QueryRunner } from "typeorm";
export class AjoutCapacite1794728932295 implements MigrationInterface {
name = 'AjoutCapacite1794728932295'
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`ALTER TABLE \`groupes\` ADD \`capacite\` smallint NOT NULL DEFAULT '20'`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`ALTER TABLE \`groupes\` DROP COLUMN \`capacite\``);
}
}
$ npm run build && npm run migration:run
query: SELECT version() as version
query: SELECT * FROM `INFORMATION_SCHEMA`.`COLUMNS` WHERE `TABLE_SCHEMA` = ? AND `TABLE_NAME` = ? -- PARAMETERS: ["ch11_s118","migrations"]
query: SELECT * FROM `ch11_s118`.`migrations` `migrations` ORDER BY `id` DESC
1 migrations are already loaded in the database.
2 migrations were found in the source code.
Initialisation1794728928674 is the last executed migration. It was executed on Sun Nov 15 2026 08:48:48 GMT+0100 (GMT+01:00).
1 migrations are new migrations must be executed.
query: START TRANSACTION
query: ALTER TABLE `groupes` ADD `capacite` smallint NOT NULL DEFAULT '20'
query: INSERT INTO `ch11_s118`.`migrations`(`timestamp`, `name`) VALUES (?, ?) -- PARAMETERS: [1794728932295,"AjoutCapacite1794728932295"]
Migration AjoutCapacite1794728932295 has been executed successfully.
query: COMMIT
$ npm run migration:show
[X] 1 Initialisation1794728928674
[X] 2 AjoutCapacite1794728932295
$ npm run seed (première fois)
Seeder : 3 créé(s), 0 mis à jour, 3 groupes en base
$ npm run seed (deuxième fois)
Seeder : 0 créé(s), 3 mis à jour, 3 groupes en base
$ npm run migration:revert
query: SELECT version() as version
query: SELECT * FROM `INFORMATION_SCHEMA`.`COLUMNS` WHERE `TABLE_SCHEMA` = ? AND `TABLE_NAME` = ? -- PARAMETERS: ["ch11_s118","migrations"]
query: SELECT * FROM `ch11_s118`.`migrations` `migrations` ORDER BY `id` DESC
2 migrations are already loaded in the database.
AjoutCapacite1794728932295 is the last executed migration. It was executed on Sun Nov 15 2026 08:48:52 GMT+0100 (GMT+01:00).
Now reverting it...
query: START TRANSACTION
query: ALTER TABLE `groupes` DROP COLUMN `capacite`
query: DELETE FROM `ch11_s118`.`migrations` WHERE `timestamp` = ? AND `name` = ? -- PARAMETERS: [1794728932295,"AjoutCapacite1794728932295"]
Migration AjoutCapacite1794728932295 has been reverted successfully.
query: COMMIT
$ npm run migration:show
[X] 1 Initialisation1794728928674
[ ] AjoutCapacite1794728932295
$ SELECT * FROM migrations;
id name
1 Initialisation1794728928674
Lecture
migration:generatecompare les entités à la base réelle et écrit le SQL nécessaire. Le nom du fichier commence par un horodatage, qui fixe l'ordre d'exécution.- Toujours relire le fichier généré avant de l'exécuter : c'est du code qui va modifier la base.
down()fait l'inverse exact deup(). migration:runcrée la tablemigrationssi nécessaire, exécute les migrations nouvelles dans une transaction, et enregistre leur nom.- Après la modification de l'entité, la seconde migration ne contient que la différence :
ALTER TABLE … ADD capacite. migration:show:[X]= appliquée,[ ]= en attente.- Le seeder, relancé, ne crée pas de doublon : il met à jour les groupes existants (idempotence).
migration:revertexécute ledown()de la dernière migration et la retire de la tablemigrations. Relancez-la plusieurs fois pour remonter plus loin.
Règles d'or: (1) ne jamais modifier une migration déjà exécutée sur une autre base que la vôtre : créez-en une nouvelle ; (2) versionner les migrations avec le code de l'entité qui les a provoquées ; (3) migration:generate ne voit pas les renommages : un renommage de colonne généré devient DROP + ADD, à remplacer à la main par RENAME COLUMN; (4) pour du SQL écrit à la main (données, renommage), migration:create crée un fichier vide.
Seeders : données de départ
Un seeder remplit la base avec des données nécessaires (listes de référence : groupes, catégories) ou utiles en développement (comptes de test). TypeORM n'impose pas de format : un simple script qui utilise le même DataSource suffit. Il doit être idempotent (relançable sans effet indésirable) : chercher avant de créer, ou ne rien faire si les données sont déjà présentes (TP 7).
| Migration | Seeder | |
|---|---|---|
| Contenu | structure (tables, colonnes, index) ; parfois une transformation de données | données |
| Exécution | une seule fois par base, suivie dans migrations | à la demande, relançable |
| En production | oui, à chaque déploiement | données de référence seulement, jamais de comptes de test |
Activités
Activité 1 Première migration
Dans votre projet, passez synchronize à false, créez data-source.ts et les scripts npm, supprimez les tables (ou utilisez une base neuve), puis générez et exécutez la migration Initialisation. Commitez la migration avec le message « db: migration initiale ».
Voir le corrigé
npm run migration:generate --name=Initialisation
# relire src/migrations/…-Initialisation.ts
npm run migration:run
npm run migration:show
git add src/migrations src/data-source.ts package.json && git commit -m "db: migration initiale"
Sous Windows, npm exécute les scripts avec cmd.exe, qui ne comprend pas $npm_config_name: passez directement le chemin, après un npm run build: npm run typeorm -- migration:generate src/migrations/Initialisation.
Activité 2 Renommer sans perdre de données
Vous voulez renommer la colonne intitule en libelle. Générez la migration, constatez le problème, puis corrigez-la.
Voir le corrigé
// généré : perte de données !
await queryRunner.query(`ALTER TABLE \`groupes\` DROP COLUMN \`intitule\``);
await queryRunner.query(`ALTER TABLE \`groupes\` ADD \`libelle\` varchar(80) NOT NULL`);
// corrigé à la main
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query('ALTER TABLE `groupes` RENAME COLUMN `intitule` TO `libelle`');
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query('ALTER TABLE `groupes` RENAME COLUMN `libelle` TO `intitule`');
}
Activité 3 Migration de données
On ajoute la colonne email (obligatoire et unique) à une table formateurs qui contient déjà 12 lignes. Pourquoi la migration générée échoue-t-elle ? Proposez une migration en trois étapes.
Voir le corrigé
ADD email varchar NOT NULL donne la valeur vide à toutes les lignes existantes, puis l'index unique échoue (12 valeurs identiques). Solution : (1) ajouter la colonne nullable; (2) remplir les valeurs (UPDATE formateurs SET email = CONCAT('formateur', id, '@exemple.tn'), ou une vraie source de données) ; (3) passer la colonne en NOT NULL et ajouter l'index unique. Le tout dans le même up(), et l'inverse dans down().
Activité 4 Un seeder de développement
Écrivez un seeder qui crée 3 groupes et 30 stagiaires répartis dans ces groupes, seulement si la table des stagiaires est vide, et qui refuse de s'exécuter si NODE_ENV vaut production.
Voir le corrigé
if (process.env.NODE_ENV === 'production') {
console.error('Seeder de développement interdit en production');
process.exit(1);
}
await source.initialize();
await source.transaction(async (m) => {
if (await m.count(Stagiaire)) return console.log('Stagiaires déjà présents : rien à faire');
const groupes = await m.save(Groupe, [{ code: 'DEV101', intitule: 'Dév. 1' }, { code: 'DEV102', intitule: 'Dév. 2' }, { code: 'RES201', intitule: 'Réseaux' }]);
await m.save(Stagiaire, Array.from({ length: 30 }, (_, i) => ({ nom: `Stagiaire ${i + 1}`, groupe: groupes[i % 3] })));
});
La transaction garantit qu'un seeder interrompu ne laisse pas une base à moitié remplie.
À retenir
- Une migration décrit un changement de schéma : up() l'applique, down() l'annule.
- La CLI de TypeORM utilise un DataSource exporté (dist/data-source.js) ; synchronize: false.
- migration:generate (puis relire !), migration:run, migration:show, migration:revert.
- La table migrations mémorise les migrations appliquées ; ne jamais modifier une migration déjà partagée.
- Seeders : scripts relançables (idempotents) pour les données de départ.
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 !