Come gestire le migrazioni in Express utilizzando Sequelize

Introduction Durante lo sviluppo dei progetti, potrebbe essere necessario apportare modifiche ai schemi di database iniziali. Gli schemi di database definiscono la struttura dei dati memorizzati nel database. Per apportare queste modifiche in modo da evitare la perdita dei dati esistenti, è necessario utilizzare la migrazione del database. La migrazione del database è semplicemente il processo di apportare modifiche controllate dalla versione e reversibili a schemi di database.La migrazione del database consente di apportare modifiche ai schemi in modo sicuro e di invertire queste modifiche se necessario. In this tutorial, you will learn how to implement database migration in your Express and Postgres application. You will learn how to create migration files, commit changes from the migration files to the database, and revert changes made to the database. You will learn how to do all this using the Sequelize Command-Line Interface (CLI) and the Umzug library. You will also learn how to populate your database with test or dummy data. Prerequisiti Per seguire insieme a questo tutorial, avrai bisogno del seguente: A text editor (e.g., VS Code) NodeJS installed on your computer Basic knowledge of Express Basic knowledge of Git A Postgres instance running either locally or remotely An API client (e.g., Postman) Progetto Setup Per mantenere l'articolo conciso, questo tutorial si basa sull'API Task Manager creata nel . Tutorial precedente https://hackernoon.com/how-to-connect-an-express-application-to-postgres-using-sequelize?embedable=true Clonare il progetto di base: il primo passo consiste nel clonare il repository API Task Manager e navigare nella cartella del progetto: git clone https://github.com/michaelikoko/tasks-manager-api.git cd tasks-manager-api Installa dipendenze: installa le necessarie dipendenze del progetto elencate in package.json: npm install Controlla la struttura del progetto: dopo l'installazione, dovresti avere una struttura del progetto che sembra questo: Impostazione del database: come indicato nei presupposti, assicurati di avere un'istanza Postgres in esecuzione localmente o remotamente. Crea un nuovo database e memorizza la stringa di connessione del database in un file .env nel directory root: PORT=5000 DATABASE_URL=postgresql://user:password@localhost:5432/mydatabase Migrazioni con Sequelize CLI In questa sezione, imparerai come gestire le migrazioni utilizzando la sequelize Command-Line Interface ( 3) Imparerai a configurare , come apportare e invertire le modifiche allo schema utilizzando un file di migrazione, e alcuni comandi utilizzati da per gestire le migrazioni. sequelize-cli sequelize-cli sequelize-cli Impostazione Sequelize CLI Installa il Sequelize CLI utilizzando un gestore di pacchetti: npm install --save-dev sequelize-cli Impostare Sequelize CLI nel progetto utilizzando il comando init: npx sequelize-cli init Questo comando crea le cartelle necessarie richieste da Sequelize CLI: di di , e Se una di queste cartelle esiste prima di eseguire il comando (come nel nostro caso con Sequelize CLI non li sovrascrive, ma invece genera quelli mancanti. config models migrations seeders models Infine, si configura come Sequelize CLI si connette al database. Per impostazione predefinita, Sequelize CLI genera un file, che si può fare uso di se si desidera hardcode credenziali di database. Tuttavia, in questo tutorial, si farà uso di configurazione dinamica per accedere all'URL di database, che sarà memorizzato come una variabile ambiente da . config/config.json .env Nella cartella config, eliminare config.json e creare config.js con i seguenti contenuti: require('dotenv').config(); const {DATABASE_URL} = require('../utils/config'); module.exports = { development: { url: DATABASE_URL, dialect: 'postgres', seederStorage: "sequelize", seederStorageTableName: "SequelizeData" } }; Per semplicità in questo tutorial, ti stai concentrando solo sull'ambiente di sviluppo. È necessario fornire il percorso per config.js a Sequelize CLI. Nel directory root del progetto, creare il file di configurazione .sequelizerc con il seguente contenuto: // .sequelizerc const path = require('path'); module.exports = { config: path.resolve('config', 'config.js'), 'models-path': path.resolve('models'), 'seeders-path': path.resolve('seeders'), 'migrations-path': path.resolve('migrations'), }; Creare file di migrazione Ora che hai configurato Sequelize CLI, puoi procedere alla creazione del primo file di migrazione per model. A migration file in Sequelize is a JavaScript file that controls how to implement and revert migrations. In a typical migration file, you export two functions: task : The function contains logic for modifying the database to a new state. up up : The function contains logic for reverting the changes made in the function. down down up Both the e La funzione ha due parametri: up down queryInterface: L'oggetto queryInterface è di solito il primo parametro. L'oggetto è un'istanza della classe QueryInterface. QueryInterface contiene metodi che Sequelize utilizza per comunicare con i database. L'oggetto ha i seguenti metodi: : creates a new table queryInterface.createTable : adds a column to a table queryInterface.addColumn : changes the properties of a column queryInterface.changeColumn : removes a column queryInterface.removeColumn : inserts multiple data into a table queryInterface.bulkInsert : deletes multiple data from a table queryInterface.bulkDelete For a full list of available methods, visit the section of the Sequelize documentation. QueryInterface API : The object is usually the second parameter, and it contains all the provided data types, for example , , , and so on. You can use the command to generate a migration file, which is saved in the folder . Use the following command in a terminal to generate the migration file: Sequelize Sequelize STRING INTEGER BOOLEAN migration:generate migrations create-task-table npx sequelize-cli migration:generate --name create-task-table Replace the contents of the just created migration file: con il seguente: XXXXXXXXXXXXXX-create-task-table.js "use strict"; /** @type {import('sequelize-cli').Migration} */ module.exports = { async up(queryInterface, Sequelize) { await queryInterface.createTable("Tasks", { id: { type: Sequelize.DataTypes.INTEGER, autoIncrement: true, primaryKey: true, }, title: { type: Sequelize.DataTypes.STRING, allowNull: false, }, completed: { type: Sequelize.DataTypes.BOOLEAN, defaultValue: false, }, createdAt: { type: Sequelize.DataTypes.DATE, allowNull: false }, updatedAt: { type: Sequelize.DataTypes.DATE, allowNull: false } }); }, async down(queryInterface, Sequelize) { await queryInterface.dropTable("Tasks"); }, }; Il il file di migrazione è responsabile per la creazione del nella base di dati. in funzione, si utilizza la il metodo per creare la tabella passando il nome della tabella del database ( ), e un oggetto delle proprietà della tabella (simile a definire un modello in Sequelize). Se si dovesse invertire le modifiche apportate da questo file di migrazione, nel funzione, si utilizza la Il metodo per rimuovere il Tabella del database. XXXXXXXXXXXXXX-create-task-table.js Task up queryInterface.createTable Task down queryInterface.dropTable Task Run Migrations I file di migrazione devono essere eseguiti al fine di eseguire le modifiche nel database. command: db:migrate npx sequelize-cli db:migrate Il Il comando fa quanto segue: db:migrate In primo luogo, crea una tabella chiamata SequelizeMeta nel database se non esiste. Sequelize CLI utilizza la tabella SequelizeMeta per tenere traccia delle migrazioni eseguite nel database. In secondo luogo, cerca qualsiasi file di migrazione che non è stato eseguito. Questo è determinato controllando i file di migrazione nella cartella di migrazione contro i file registrati nella tabella SequelizeMeta. Lastly, it executes the content of all migration files that have not been run. The commands in the function of the migration file are being executed. up You can use the per eseguire solo un singolo file di migrazione. ad esempio, per eseguire solo il File di migrazione: --name XXXXXXXXXXXXXX-create-task-table.js npx sequelize-cli db:migrate --name XXXXXXXXXXXXXX-create-task-table.js Modifica di un modello esistente L'importanza di utilizzare le migrazioni risplende quando è necessario apportare modifiche allo schema di un modello di database esistente. Le migrazioni consentono di apportare in modo sicuro modifiche allo schema di database, garantendo al contempo l'integrità dei dati. For example, you're going to make a change to the schema del modello nell'API Task Manager. si sta aggiungendo un Inserisci la colonna al diagramma. Questo può essere fatto nei seguenti passaggi: Task dueDate Creare il file di migrazione utilizzando il comando migrazione:generare: npx sequelize-cli migration:generate --name add-dueDate-column Replace the content of the generated migration file with the following: XXXXXXXXXXXXXX-add-dueDate-column.js 'use strict'; /** @type {import('sequelize-cli').Migration} */ module.exports = { async up (queryInterface, Sequelize) { await queryInterface.addColumn("Tasks", "dueDate", { type: Sequelize.DataTypes.DATE, allowNull: true }) }, async down (queryInterface, Sequelize) { await queryInterface.removeColumn("Tasks", "dueDate") } }; Aggiungi la colonna dueDate allo schema del modello Task in models/task.js: const {Model, DataTypes} = require("sequelize") const {sequelize} = require("../utils/db") class Task extends Model {} Task.init({ id: { type: DataTypes.INTEGER, autoIncrement: true, primaryKey: true }, title: { type: DataTypes.STRING, allowNull: false }, completed: { type: DataTypes.BOOLEAN, defaultValue: false }, dueDate: { type: DataTypes.DATE, allowNull: true } }, { sequelize, modelName: "Task", timestamps: true, underscored: false, defaultScope: { attributes: { exclude: ["createdAt", "updatedAt"] } } }) module.exports = Task You would want to make sure that the due date can be added when creating new tasks through the API endpoint. Make the following changes to the controller logic in : index.js //... app.post("/api/tasks", async (req, res) => { const { title, dueDate } = req.body; if (!title) { return res.status(400).json({ message: "Title is required" }); } const dueDateObj = dueDate ? new Date(dueDate) : null; if (dueDateObj == "Invalid Date") { return res.status(400).json({ message: "Invalid due date format" }); } if (dueDateObj && dueDateObj < new Date()) { return res.status(400).json({ message: "Due date cannot be in the past" }); } const task = await Task.create({ title, dueDate: dueDateObj }); res.status(201).json({ message: "Task created successfully", task, }); }); //... Lastly, run the migration file using the command: db:migrate npx sequelize-cli db:migrate Ritorno delle migrazioni La migrazione del database consente di invertire in modo sicuro le modifiche apportate al database. Sequelize CLI fornisce vari comandi che possono essere utilizzati per invertire le modifiche di migrazione: È possibile annullare la migrazione più recente con il comando db:migrate:undo: npx sequelize-cli db:migrate:undo You can undo all migrations made and return to the initial state with the command: db:migrate:undo:all npx sequelize-cli db:migrate:undo:all Puoi anche usare il comando db:migrate:undo:all per tornare a una particolare migrazione passando il nome del file di migrazione con il nome --to flag. npx sequelize-cli db:migrate:undo:all --to XXXXXXXXXXXXXX-create-task-table.js Dati di semina con Sequelize CLI Database seeding is the technique of populating your database with existing, often dummy data, for testing or development purposes. Sequelize provides a way to seed your database in your Express application using seeders. Seeders are scripts that allow you to populate your database with sample data. In questa sezione, imparerai come generare file di semi, eseguire semi e cancellare semi utilizzando Sequelize CLI. Generate a Seeder Per creare un file di sementi, è possibile utilizzare il Commando, passando il nome del file del seme al flag. The command saves the generated seed file in the Il file semina ha la struttura con i file di migrazione, utilizzando lo stesso and functions. seed:generate --name seeders up down È possibile procedere alla creazione di un file di semi per l'API Task Manager che popolerà il Per creare il file, utilizzare il seguente comando: Tasks npx sequelize-cli seed:generate --name sample-tasks Questo comando creerà il seguente file nel Il Folletto: . The Il file deve avere i seguenti contenuti: seeders XXXXXXXXXXXXXX-sample-tasks.js XXXXXXXXXXXXXX-sample-tasks.js "use strict"; /** @type {import('sequelize-cli').Migration} */ module.exports = { async up(queryInterface, Sequelize) { await queryInterface.bulkDelete("Tasks", null, {}); // First, clear the Tasks table await queryInterface.bulkInsert( "Tasks", [ { title: "Finish project proposal", dueDate: new Date("2025-09-15"), createdAt: new Date(), updatedAt: new Date(), }, { title: "Team meeting", dueDate: new Date("2025-09-17"), createdAt: new Date(), updatedAt: new Date(), }, { title: "Code review", dueDate: null, createdAt: new Date(), updatedAt: new Date(), }, { title: "Update documentation", dueDate: new Date("2025-09-20"), createdAt: new Date(), updatedAt: new Date(), }, { title: "Refactor legacy code", dueDate: null, createdAt: new Date(), updatedAt: new Date(), }, ], {} ); }, async down(queryInterface, Sequelize) { await queryInterface.bulkDelete("Tasks", null, {}); }, }; Run Seeders In order to effect the changes to the database, you need to run the seed file. Sequelize CLI provides the Comando per eseguire file di sementi. db:seed To run all seed files in the In questo caso, si utilizza il seguente comando: seeders npx sequelize-cli db:seed:all You can also run a particular seed file by using the flag and specifying the name of the file. For example, to only run the seed file : --seed XXXXXXXXXXXXXX-sample-tasks.js npx sequelize-cli db:seed --seed XXXXXXXXXXXXXX-sample-tasks.js Ritorno dei semi Sequelize CLI also provides various commands that revert any changes made by seed files: You can use the following command to undo all seeds: npx sequelize-cli db:seed:undo:all You can use the following command to undo a specific seed file, for example, : 20250913081512-sample-tasks.js npx sequelize-cli db:seed:undo --seed 20250913081512-sample-tasks.js You can use the following command to undo the most recent seed: npx sequelize-cli db:seed:undo Migrazioni con Umzug So far in the tutorial, you have used the Sequelize CLI tool to run migrations. If you require more control on how migrations are performed and want to run them manually, you can make use of the della biblioteca. Umzag Umzug è descritto come: Framework Agnostic Migration Tool per Node.js Framework agnostic migration tool for Node.js Costruisci un umzug Inizia con l'installazione della libreria umzug: npm install umzug Create the configuration object. You use this object to configure an Umzug instance by passing it to the constructor. Edit the file as follows: migratorConfig utils/db.js //... const { Umzug, SequelizeStorage } = require("umzug"); const migratorConfig = { migrations: { glob: "migrations/*.js", }, storage: new SequelizeStorage({ sequelize, tableName: "SequelizeMeta" }), // Store performed migration files context: sequelize.getQueryInterface(), logger: console, }; // ... Crea la funzione runMigrations. La funzione esegue le migrazioni sui file di migrazione trovati nella cartella migrazioni. Nell'oggetto migratorConfig, dici a Sequelize di tenere traccia delle migrazioni eseguite, quindi la funzione runMigrations non fa nulla se non ci sono nuovi file di migrazione. Aggiungi il seguente codice a utils/db.js: // ... const runMigrations = async () => { await sequelize.authenticate(); const migrator = new Umzug(migratorConfig); const migrations = await migrator.up(); console.log("Migrations up to date", { files: migrations.map((mig) => mig.name), }); }; Creare la funzione undoMigrations che inverti la migrazione precedente. Aggiungi il seguente codice a utils/db.js: //... const undoMigrations = async () => { await sequelize.authenticate(); const migrator = new Umzug(migratorConfig); const migrations = await migrator.down(); console.log("Migrations reverted", { files: migrations.map((mig) => mig.name), }); }; // ... Finally, the Il file dovrebbe apparire così: utils/db.js const Sequelize = require("sequelize"); const { DATABASE_URL } = require("./config"); const { Umzug, SequelizeStorage } = require("umzug"); const sequelize = new Sequelize(DATABASE_URL); const connectToDB = async () => { try { await sequelize.authenticate(); console.log("Database connection established successfully."); } catch (error) { console.log("Unable to connect to the database:", error); return process.exit(1); } return null; }; const migratorConfig = { migrations: { glob: "migrations/*.js", }, storage: new SequelizeStorage({ sequelize, tableName: "SequelizeMeta" }), // Store performed migration files context: sequelize.getQueryInterface(), logger: console, }; const runMigrations = async () => { await sequelize.authenticate(); const migrator = new Umzug(migratorConfig); const migrations = await migrator.up(); console.log("Migrations up to date", { files: migrations.map((mig) => mig.name), }); }; const undoMigrations = async () => { await sequelize.authenticate(); const migrator = new Umzug(migratorConfig); const migrations = await migrator.down(); console.log("Migrations reverted", { files: migrations.map((mig) => mig.name), }); }; module.exports = { connectToDB, sequelize, runMigrations, undoMigrations, }; Create two files in the directory: and . These files will allow you to set up npm scripts to execute the and functions created. util runMigrations.js undoMigrations.js runMigrations undoMigrations The function should have the following contents: util/runMigrations.js const { runMigrations } = require("./db"); runMigrations(); Il function should have the following contents: util/undoMigrations.js const { undoMigrations } = require("./db"); undoMigrations(); Lastly, create the npm scripts in : package.json { //... "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "dev": "nodemon index.js", "start": "node index.js", "migration:up": "node utils/runMigrations.js", "migration:down": "node utils/undoMigrations.js" } //... } Migrazione con Umzug When using the Umzug library to run migrations, you will manually create the migration files, as the ones created using the Sequelize CLI command won't work. migration:generate For example, the migration file, which adds the Colonna alla table, should look like this when executed using Umzug: XXXXXXXXXXXXXX-add-dueDate-column.js dueDate Tasks const { DataTypes } = require("sequelize"); module.exports = { async up({ context: queryInterface }) { await queryInterface.addColumn("Tasks", "dueDate", { type: DataTypes.DATE, allowNull: true, }); }, async down({ context: queryInterface }) { await queryInterface.removeColumn("Tasks", "dueDate"); }, }; To run the migration file, you make use of the script npm che hai impostato in che chiama il function: migration:up package.json runMigrations npm run migration:up Revert Migrations with Umzug To undo the last migration, you make use of the npm script that calls the La funzione: migration:down undoMigration npm run migration:down Conclusion Alla fine di questo tutorial, hai imparato l'importanza di utilizzare le migrazioni di database durante lo sviluppo delle tue applicazioni. Hai imparato come usare il Sequelize CLI per generare file di migrazione, eseguire migrazioni e invertire le modifiche apportate al database. Hai anche imparato come usare il Sequelize CLI per creare file di semi al fine di riempire il tuo database con dati di campione. Infine, hai imparato come eseguire le migrazioni manualmente utilizzando la libreria Umzug. The code for this tutorial can be found on . GitHub To learn more about database migrations, visit the following resources: Documentazione sequenziale Sviluppo GitHub Cattura Github