Cómo manejar migraciones en Express usando Sequelize

Introducción Durante el desarrollo de sus proyectos, es posible que necesite realizar cambios en sus esquemas de base de datos iniciales. Los esquemas de base de datos definen la estructura de los datos almacenados en la base de datos. Para realizar estos cambios de una manera que evite la pérdida de datos existentes, se requerirá el uso de la migración de base de datos. La migración de bases de datos es simplemente el proceso de hacer modificaciones controladas por versiones y reversibles a los esquemas de bases de datos. En este tutorial, aprenderás cómo implementar la migración de bases de datos en tu aplicación Express y Postgres. aprenderás cómo crear archivos de migración, hacer cambios de los archivos de migración a la base de datos, y revertir los cambios realizados a la base de datos. aprenderás cómo hacer todo esto usando la Interfaz de línea de comandos de secuela (CLI) y la biblioteca Umzug. también aprenderás cómo llenar tu base de datos con datos de prueba o estúpidos. Precondiciones Para seguir este tutorial, necesitarás lo siguiente: 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) Proyecto Instalación Para mantener el artículo conciso, este tutorial se basa en la API de Task Manager creada en el . Artículo anteriorTutorial https://hackernoon.com/how-to-connect-an-express-application-to-postgres-using-sequelize?embedable=true Clone el Proyecto Base: El primer paso es clonar el repositorio de la API de Task Manager y navegar a la carpeta del proyecto: git clone https://github.com/michaelikoko/tasks-manager-api.git cd tasks-manager-api Instalar dependencias: Instalar las dependencias necesarias del proyecto listadas en package.json: npm install Check Project Structure: After installation, you should have a project structure that looks like this: Configuración de la base de datos: Como se indica en los prerequisitos, asegúrese de que tenga una instancia de Postgres en ejecución local o remota. Cree una nueva base de datos y almacene la cadena de conexión de la base de datos en un archivo .env en el directorio raíz: PORT=5000 DATABASE_URL=postgresql://user:password@localhost:5432/mydatabase Migraciones con Sequelize CLI En esta sección, aprenderá cómo manejar migraciones utilizando la interfaz Sequelize Command-Line ( ) Aprenderá a configurar , cómo hacer y revertir cambios al esquema usando un archivo de migración, y algunos comandos utilizados por Gestionar las migraciones. sequelize-cli sequelize-cli sequelize-cli Configuración de Sequelize CLI Instalar el Sequelize CLI usando un gestor de paquetes: npm install --save-dev sequelize-cli Configurar Sequelize CLI en el proyecto usando el comando init: npx sequelize-cli init Este comando crea las carpetas necesarias requeridas por Sequelize CLI: , de , de , y . If any of these folders exist before running the command(as in our case with ), Sequelize CLI does not overwrite them, but instead generates the missing ones. config models migrations seeders models Finalmente, configure cómo Sequelize CLI se conecta a la base de datos. Por defecto, Sequelize CLI genera una archivo, que puede hacer uso de si desea hardcode credenciales de base de datos. Sin embargo, en este tutorial, usted hará uso de la configuración dinámica para acceder a la URL de la base de datos, que se almacenará como una variable de entorno de . config/config.json .env En la carpeta config, elimine config.json y crea config.js con los siguientes contenidos: require('dotenv').config(); const {DATABASE_URL} = require('../utils/config'); module.exports = { development: { url: DATABASE_URL, dialect: 'postgres', seederStorage: "sequelize", seederStorageTableName: "SequelizeData" } }; Para la simplicidad en este tutorial, usted está centrándose sólo en el entorno de desarrollo. Debe proporcionar el camino a config.js a Sequelize CLI. En el directorio raíz del proyecto, crea el archivo de configuración .sequelizerc con el siguiente contenido: // .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'), }; Creación de archivos de migración Ahora que ha configurado Sequelize CLI, puede proceder a crear el primer archivo de migración para el Un archivo de migración en Sequelize es un archivo JavaScript que controla cómo implementar y revertir migraciones. 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 Ambos los y La función tiene dos parámetros: up down QueryInterface: El objeto QueryInterface es generalmente el primer parámetro. El objeto es una instancia de la clase QueryInterface. El QueryInterface contiene métodos que Sequelize utiliza para comunicarse con bases de datos. El objeto tiene los siguientes métodos: : 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 Sequelize: El objeto Sequelize es generalmente el segundo parámetro, y contiene todos los tipos de datos proporcionados, por ejemplo STRING, INTEGER, BOOLEAN, y así sucesivamente. Puede utilizar el comando migración:generar para generar un archivo de migración, que se guarda en la carpeta migraciones. npx sequelize-cli migration:generate --name create-task-table Sustituye el contenido del archivo de migración recién creado: con lo siguiente: 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"); }, }; El El archivo de migración es responsable de la creación de en la base de datos. en la Funciones: Usted utiliza la el método para crear la tabla mediante la transmisión del nombre de la tabla de bases de datos ( ), y un objeto de las propiedades de la tabla (similar a la definición de un modelo en Sequelize). Funciones: Usted utiliza la Método para eliminar el Tabla de la base de datos. XXXXXXXXXXXXXX-create-task-table.js Task up queryInterface.createTable Task down queryInterface.dropTable Task Corren las migraciones Los archivos de migración deben ejecutarse para ejecutar los cambios en la base de datos. El mando: db:migrate npx sequelize-cli db:migrate El El mando hace lo siguiente: db:migrate Primero, crea una tabla llamada SequelizeMeta en la base de datos si no existe. Sequelize CLI utiliza la tabla SequelizeMeta para mantener un registro de las migraciones que se han ejecutado en la base de datos. En segundo lugar, busca cualquier archivo de migración que no haya sido ejecutado. Esto se determina comprobando los archivos de migración en la carpeta de migración contra los archivos registrados en la tabla SequelizeMeta. Por último, ejecuta el contenido de todos los archivos de migración que no se han ejecutado. Puedes utilizar el para ejecutar solo un archivo de migración individual. Por ejemplo, para ejecutar solo el Archivo de migración: --name XXXXXXXXXXXXXX-create-task-table.js npx sequelize-cli db:migrate --name XXXXXXXXXXXXXX-create-task-table.js Modificación de un modelo existente La importancia de usar migraciones realmente resplandece cuando necesita hacer cambios en el esquema de un modelo de base de datos existente. Las migraciones le permiten realizar cambios de forma segura en el esquema de la base de datos al mismo tiempo que garantiza la integridad de los datos. Por ejemplo, usted va a hacer un cambio en la en la API de Gerenciador de Tareas. se va a agregar un de la columna al esquema. Esto se puede hacer en los siguientes pasos: Task dueDate Crear el archivo de migración usando el comando migración:generar: npx sequelize-cli migration:generate --name add-dueDate-column Sustituye el contenido del archivo de migración generado XXXXXXXXXXXX-add-dueDate-column.js por el siguiente: '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") } }; Añade la columna dueDate al esquema del modelo de tareas en 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 Desearía asegurarse de que la fecha de vencimiento se pueda añadir al crear nuevas tareas a través del punto final de la API. Haga los siguientes cambios a la lógica del controlador en 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, }); }); //... Por último, ejecute el archivo de migración utilizando el comando db:migrate: npx sequelize-cli db:migrate Revertir la migración Database migration gives you the ability to safely revert changes made to the database. Sequelize CLI provides various commands that can be used to revert migration changes: Puede desactivar la migración más reciente con el comando db:migrate:undo: npx sequelize-cli db:migrate:undo Puede desactivar todas las migraciones realizadas y volver al estado inicial con el comando db:migrate:undo:all: npx sequelize-cli db:migrate:undo:all También puede utilizar el comando db:migrate:undo:all para volver a una migración particular pasando el nombre del archivo de migración con el --to flag. Por ejemplo, para volver a la migración XXXXXXXXXXXX-create-task-table.js: npx sequelize-cli db:migrate:undo:all --to XXXXXXXXXXXXXX-create-task-table.js Seed Data con Sequelize CLI La semilla de base de datos es la técnica de llenar su base de datos con datos existentes, a menudo estúpidos, para fines de prueba o desarrollo. Sequelize proporciona una manera de sembrar su base de datos en su aplicación Express usando semillas. Seeders son scripts que le permiten llenar su base de datos con datos de muestra. En esta sección, aprenderá cómo generar archivos de semillas, ejecutar semillas y desactivar semillas usando Sequelize CLI. Generar una semilla Para crear un archivo de semillas, puede utilizar el orden, pasando el nombre del archivo de semillas al flag. El comando guarda el archivo de semillas generado en el El archivo de semillas tiene la estructura con los archivos de migración, utilizando el mismo y las funciones. seed:generate --name seeders up down Puede seguir creando un archivo de semillas para la API de Gerenciador de tareas que cubrirá la Tabla con datos de tareas de muestra. Para crear el archivo, utilice el siguiente comando: Tasks npx sequelize-cli seed:generate --name sample-tasks Este comando creará el siguiente archivo en el El folleto: • El El archivo debe tener los siguientes contenidos: 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, {}); }, }; Caminar por los Seeders Para efectuar los cambios en la base de datos, debe ejecutar el archivo de semillas. Sequelize CLI proporciona la Comando para ejecutar los archivos de semillas. db:seed Para ejecutar todos los archivos de semillas en el Folders, utiliza el siguiente comando: seeders npx sequelize-cli db:seed:all También puede ejecutar un archivo de semillas particular utilizando el bandera y especificando el nombre del archivo. Por ejemplo, para ejecutar solo el archivo de semillas : --seed XXXXXXXXXXXXXX-sample-tasks.js npx sequelize-cli db:seed --seed XXXXXXXXXXXXXX-sample-tasks.js Recuperación de semillas Sequelize CLI también proporciona varios comandos que reverten los cambios realizados por los archivos de semillas: Puede utilizar el siguiente comando para desactivar todas las semillas: npx sequelize-cli db:seed:undo:all Puede usar el siguiente comando para desactivar un archivo de semillas específico, por ejemplo, 20250913081512-sample-tasks.js: npx sequelize-cli db:seed:undo --seed 20250913081512-sample-tasks.js Puede utilizar el siguiente comando para desactivar la semilla más reciente: npx sequelize-cli db:seed:undo Migraciones con Umzug Hasta ahora en el tutorial, usted ha utilizado la herramienta Sequelize CLI para ejecutar migraciones. Si necesita más control sobre cómo se realizan las migraciones y desea ejecutarlas manualmente, puede hacer uso de la de la biblioteca. Umzug Umzug se describe como: Herramienta de migración agnóstica para Node.js Herramienta de migración agnóstica para Node.js Coloque la humedad Comienza con la instalación de la biblioteca umzug: npm install umzug Cree el objeto de configuración migratorConfig. Usted utiliza este objeto para configurar una instancia Umzug al pasarla al constructor. Edite el archivo utils/db.js de la siguiente manera: //... 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, }; // ... Crear la función runMigrations. La migración realiza migraciones en los archivos de migración que se encuentran en la carpeta de migraciones. En el objeto migratorConfig, se le dice a Sequelize que siga el seguimiento de las migraciones que se han ejecutado, por lo que la función runMigrations no hace nada si no hay nuevos archivos de migración. // ... 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), }); }; Cree la función undoMigrations que reverte la migración anterior.Añade el siguiente código 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), }); }; // ... Por último, el El archivo debe parecer así: 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(); El function should have the following contents: util/undoMigrations.js const { undoMigrations } = require("./db"); undoMigrations(); Finalmente, crea los scripts npm en 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" } //... } Migraciones con Umzug Cuando se utiliza la biblioteca Umzug para ejecutar migraciones, se crearán manualmente los archivos de migración, como los creados utilizando el comando Sequelize CLI No va a trabajar. migration:generate Por ejemplo, el archivo de migración, que añade el Columna a la la tabla, debe parecer así cuando se ejecuta utilizando 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"); }, }; Para ejecutar el archivo de migración, utilice el npm script you set up in , which calls the Funciones : migration:up package.json runMigrations npm run migration:up Revertir la migración con Umzug Para desactivar la última migración, utiliza el Escribe el script npm que llama Funciones : migration:down undoMigration npm run migration:down Conclusión Al final de este tutorial, aprendió la importancia de utilizar migraciones de bases de datos al desarrollar sus aplicaciones. Aprendió a usar el Sequelize CLI para generar archivos de migración, ejecutar migraciones y revertir cambios hechos a la base de datos. También aprendió a usar el Sequelize CLI para crear archivos de semillas para llenar su base de datos con datos de muestra. El código para este tutorial se puede encontrar en . GitHub Para obtener más información sobre las migraciones de bases de datos, visite los siguientes recursos: Documentación Secundaria Descargar CLI GitHub Descargar en GitHub