Kaip tvarkyti migracijas naudojant „Express Sequelize“

Įvadas Plėtojant projektus gali tekti keisti pradines duomenų bazės schemas. duomenų bazės schemos apibrėžia duomenų, saugomų duomenų bazėje, struktūrą. Norėdami atlikti šiuos pakeitimus taip, kad nebūtų prarasti esamų duomenų, turėsite naudoti duomenų bazės perkėlimą. Duomenų bazės migracija yra paprasčiausiai versijų valdymo ir grįžtamų pakeitimų duomenų bazės schemoms procesas.Duomenų bazės migracija leidžia saugiai atlikti savo schemų pakeitimus ir grąžinti šiuos pakeitimus, jei atsiranda poreikis. Šiame vadovėlyje jūs sužinosite, kaip įgyvendinti duomenų bazės migraciją savo "Express" ir "Postgres" programose. Jūs sužinosite, kaip sukurti migracijos failus, atlikti pakeitimus iš migracijos failų į duomenų bazę ir grąžinti atliktus duomenų bazės pakeitimus. Jūs sužinosite, kaip visa tai padaryti naudojant "Sequelize Command-Line Interface" (CLI) ir "Umzug" biblioteką. Išankstinės sąlygos Norėdami sekti kartu su šiuo vadovu, jums reikės: 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) Projekto įkūrimas Norėdami išlaikyti straipsnį glaustą, šis vadovas remiasi Task Manager API, sukurtu . Ankstesnis Tutorial https://hackernoon.com/how-to-connect-an-express-application-to-postgres-using-sequelize?embedable=true Klonuoti bazinį projektą: pirmasis žingsnis yra klonuoti Task Manager API saugyklą ir naršyti į projekto aplanką: git clone https://github.com/michaelikoko/tasks-manager-api.git cd tasks-manager-api Įdiekite priklausomybes: Įdiekite reikiamas projekto priklausomybes, išvardytas package.json: npm install Patikrinkite projekto struktūrą: Įdiegus, turėtumėte turėti tokią projekto struktūrą: Duomenų bazės nustatymas: Kaip nurodyta išankstiniuose reikalavimuose, įsitikinkite, kad turite „Postgres“ instancę, kuri veikia vietoje arba nuotoliniu būdu. Sukurkite naują duomenų bazę ir išsaugokite duomenų bazės ryšio eilutę .env faile šaknų kataloge: PORT=5000 DATABASE_URL=postgresql://user:password@localhost:5432/mydatabase Migracijos su Sequelize CLI Šiame skyriuje jūs sužinosite, kaip tvarkyti migracijas naudojant „Sequelize Command-Line“ sąsają ( Jūs išmoksite, kaip sukurti , kaip atlikti ir atkurti schemos pakeitimus naudojant perkėlimo failą ir kai kurias komandas, kurias naudoja spręsti migracijos klausimus. sequelize-cli sequelize-cli sequelize-cli Parsisiųsti Sequelize CLI Įdiekite „Sequelize CLI“ naudodami paketų tvarkyklę: npm install --save-dev sequelize-cli Nustatykite „Sequelize CLI“ projekte naudodami init komandą: npx sequelize-cli init Ši komanda sukuria būtinus aplankus, kurių reikalauja „Sequelize CLI“: , , ir Jei bet kuris iš šių aplankų egzistuoja prieš paleidžiant komandą (kaip mūsų atveju su ), Sequelize CLI nerašo jų, bet vietoj to generuoja trūkstamus. config models migrations seeders models Galiausiai konfigūruojate, kaip „Sequelize CLI“ prisijungia prie duomenų bazės. failą, kurį galite naudoti, jei norite įtvirtinti duomenų bazės įgaliojimus. Tačiau šiame vadove naudosite dinaminę konfigūraciją, kad galėtumėte pasiekti duomenų bazės URL, kuris bus saugomas kaip aplinkos kintamasis iš . config/config.json .env Konfig aplanke ištrinkite config.json ir sukurkite config.js su tokiu turiniu: require('dotenv').config(); const {DATABASE_URL} = require('../utils/config'); module.exports = { development: { url: DATABASE_URL, dialect: 'postgres', seederStorage: "sequelize", seederStorageTableName: "SequelizeData" } }; Dėl paprastumo šiame vadove jūs sutelkiate dėmesį tik į plėtros aplinką. Projekto šaknų kataloge sukurkite konfig.js konfigūracijos failą su tokiu turiniu: // .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'), }; Sukurkite migracijos failus Dabar, kai konfigūruojate „Sequelize CLI“, galite pradėti kurti pirmąjį migracijos failą „Sequelize“ migracijos failas yra „JavaScript“ failas, kuris kontroliuoja, kaip įgyvendinti ir atkurti migracijas. 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 Abu šie ir Funkcijos turi du parametrus: up down QueryInterface: QueryInterface objektas paprastai yra pirmasis parametras. Objektas yra QueryInterface klasės pavyzdys. QueryInterface yra metodų, kuriuos Sequelize naudoja bendrauti su duomenų bazėmis. Objektas turi šiuos metodus: : 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: Sequelize objektas paprastai yra antrasis parametras, ir jame yra visi pateikti duomenų tipai, pvz., STRING, INTEGER, BOOLEAN ir pan. Galite naudoti komandą migration:generate, kad sukurtumėte migracijos failą, kuris yra išsaugotas migracijos aplanke. Naudokite šią komandą terminale, kad sukurtumėte migracijos failą create-task-table: npx sequelize-cli migration:generate --name create-task-table Pakeiskite ką tik sukurto migracijos failo turinį: su tuo, kas toliau: 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"); }, }; Tų migracijos failas yra atsakingas už sukūrimo Duomenų bazės lentelė. „Dėl funkcijos, jūs naudojate Taisyklės, kuriomis remiantis pateikiamas duomenų bazės pavadinimas ( ), ir lentelės savybių objektas (panašus į modelio apibrėžimą sekime). funkcijos, jūs naudojate Metodas pašalinti Lentelė iš duomenų bazės. XXXXXXXXXXXXXX-create-task-table.js Task up queryInterface.createTable Task down queryInterface.dropTable Task Migracijos bėgimas Migracijos failus reikia paleisti, kad būtų galima atlikti duomenų bazės pakeitimus. Komandoje yra: db:migrate npx sequelize-cli db:migrate Tų Komanda atlieka šiuos veiksmus: db:migrate Pirma, ji sukuria lentelę, pavadintą SequelizeMeta duomenų bazėje, jei ji neegzistuoja. Sequelize CLI naudoja SequelizeMeta lentelę, kad išlaikytų duomenų bazėje vykdomų migracijų įrašą. Tai nustatoma patikrinus migracijos failus migracijos aplanke prieš failus, įrašytus SequelizeMeta lentelėje. Galiausiai jis atlieka visų migravimo failų, kurie nebuvo paleisti, turinį. Jūs galite naudoti kad būtų galima paleisti tik atskirą migracijos failą. Pavyzdžiui, kad būtų galima paleisti tik Migracijos archyvas: --name XXXXXXXXXXXXXX-create-task-table.js npx sequelize-cli db:migrate --name XXXXXXXXXXXXXX-create-task-table.js Esamo modelio keitimas Kai migracijos naudojimo svarba iš tikrųjų šviečia, kai reikia atlikti esamo duomenų bazės modelio schemos pakeitimus.Migracijos leidžia saugiai atlikti duomenų bazės schemos pakeitimus, tuo pačiu užtikrinant duomenų vientisumą. Pavyzdžiui, jūs ketinate atlikti pakeitimą į modelio schemą užduočių valdytojo API. Jūs pridėsite Įtraukimas į schemą.Tai galima padaryti šiais žingsniais: Task dueDate Sukurkite migracijos failą naudodami komandą migration:generate: npx sequelize-cli migration:generate --name add-dueDate-column Pakeiskite sukurto migracijos failo XXXXXXXXXXXX-add-dueDate-column.js turinį taip: '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") } }; Įdėkite „duodate“ stulpelį į užduočių modelio schemą modeliuose/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 Norėtumėte įsitikinti, kad naujų užduočių kūrimo metu per API galinį tašką galima pridėti terminą. atlikite šiuos keitimus valdiklio logikai 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, }); }); //... Galų gale, paleiskite migracijos failą naudodami komandą db:migrate: npx sequelize-cli db:migrate Grįžta migracija Duomenų bazės migracija suteikia galimybę saugiai atkurti duomenų bazėje padarytus pakeitimus. „Sequelize CLI“ suteikia įvairias komandas, kuriomis galima atkurti migracijos pakeitimus: Galite atšaukti naujausią migraciją naudodami db:migrate:undo komandą: npx sequelize-cli db:migrate:undo Galite atšaukti visas atliktas migracijas ir grįžti į pradinę būseną naudodami db:migrate:undo:all komandą: npx sequelize-cli db:migrate:undo:all Taip pat galite naudoti komandą db:migrate:undo:all, kad grįžtumėte į tam tikrą migraciją, perduodami migracijos failo pavadinimą su ženklu - į vėliavą. npx sequelize-cli db:migrate:undo:all --to XXXXXXXXXXXXXX-create-task-table.js Duomenų sėjos su Sequelize CLI Duomenų bazės sėjos yra jūsų duomenų bazės užpildymo metodas esamais, dažnai netikrais duomenimis, testavimo ar plėtros tikslais. „Sequelize“ suteikia būdą sėti savo duomenų bazę „Express“ programoje naudojant sėjos. Šiame skyriuje sužinosite, kaip generuoti sėklų failus, paleisti sėklas ir panaikinti sėklas naudojant Sequelize CLI. Sukurkite sėklą Norėdami sukurti sėklų failą, galite naudoti komandą, perduodant sėklų failo pavadinimą į Komanda išsaugo generuotą sėklų failą Sėklų failas turi struktūrą su migracijos failais, naudojant tą patį ir ir funkcijų. seed:generate --name seeders up down Galite pradėti kurti užduočių valdytojo API sėklų failą, kuris užpildys lentelę su pavyzdžių užduočių duomenimis. Norėdami sukurti failą, naudokite šią komandą: Tasks npx sequelize-cli seed:generate --name sample-tasks Ši komanda sukurs šiuos failus Lentelė : • The Failas turi turėti tokį turinį: 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, {}); }, }; Važiuoja sėklos Norėdami atlikti duomenų bazės pakeitimus, turite paleisti sėklų failą. Užsakymas paleisti sėklų failus. db:seed Norėdami paleisti visus sėklų failus į Lentelėje naudokite šią komandą: seeders npx sequelize-cli db:seed:all Taip pat galite paleisti tam tikrą sėklų failą naudodami vėliavą ir nurodo failo pavadinimą. Pavyzdžiui, norėdami paleisti tik sėklų failą : --seed XXXXXXXXXXXXXX-sample-tasks.js npx sequelize-cli db:seed --seed XXXXXXXXXXXXXX-sample-tasks.js Grąžinkite sėklas Sequelize CLI taip pat suteikia įvairias komandas, kurios grąžina bet kokius sėklų failų padarytus pakeitimus: Galite naudoti šią komandą, kad atšauktumėte visas sėklas: npx sequelize-cli db:seed:undo:all Galite naudoti šią komandą, kad atšauktumėte tam tikrą sėklų failą, pvz., 20250913081512-sample-tasks.js: npx sequelize-cli db:seed:undo --seed 20250913081512-sample-tasks.js Galite naudoti šią komandą, kad atšauktumėte naujausią sėklą: npx sequelize-cli db:seed:undo Migracijos su Umzug Iki šiol pamokoje jūs naudojate „Sequelize CLI“ įrankį, kad galėtumėte paleisti migracijas.Jei jums reikia daugiau kontrolės, kaip atliekamos migracijos, ir norite jas paleisti rankiniu būdu, galite naudoti Į biblioteką. šlapinimasis Umzug apibūdinamas kaip: Agnostikos migracijos įrankis Node.js Agnostikos migracijos įrankis Node.js Nustatykite įtampą Pradėkite nuo įdiegimo umzug biblioteką: npm install umzug Sukurkite migratorConfig konfigūracijos objektą. Naudokite šį objektą, kad konfigūruotumėte Umzug instanciją, perduodami jį konstruktoriui. //... 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, }; // ... Sukurkite „runMigrations“ funkciją. „runMigrations“ atlieka migracijos failų, esančių migracijos aplanke, perkėlimus. „migratorConfig“ objekte nurodysite „Sequelize“, kad būtų galima sekti atliktas migracijas, todėl „runMigrations“ funkcija nieko nedaro, jei nėra naujų migracijos failų. „utils/db.js“ pridėkite šį kodą: // ... 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), }); }; Sukurkite funkciją „undoMigrations“, kuri pakeičia ankstesnę migraciją. į „utils/db.js“ įtraukite šį kodą: //... 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), }); }; // ... Galiausiai, The Failas turėtų atrodyti taip: 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(); Tų Funkcija turi turėti tokį turinį: util/undoMigrations.js const { undoMigrations } = require("./db"); undoMigrations(); Galiausiai sukurkite npm scenarijus 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" } //... } Vykdyti migraciją su Umzug Naudodami Umzug biblioteką, kad galėtumėte paleisti migracijas, rankiniu būdu sukursite migracijos failus, kaip ir tuos, kurie buvo sukurti naudojant komandą Sequelize CLI. Nebus dirbti migration:generate Pavyzdžiui, į migration file, which adds the Kolonos į lentelė, turėtų atrodyti taip, kai vykdoma naudojant 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"); }, }; Norėdami paleisti migracijos failą, naudokite NPM scenarijus, kurį sukūrėte Tai, kas vadinama Funkcijos : migration:up package.json runMigrations npm run migration:up Migracijos atkūrimas su Umzug Norėdami atšaukti paskutinę migraciją, naudokite npm scenarijus, kuris vadinamas Funkcijos : migration:down undoMigration npm run migration:down Išvada Šio vadovėlio pabaigoje sužinojote, kaip svarbu naudoti duomenų bazių perkėlimus kuriant savo programas. Jūs sužinojote, kaip naudoti Sequelize CLI, kad sukurtumėte perkėlimo failus, atliktumėte perkėlimus ir grąžintumėte duomenų bazėje padarytus pakeitimus. Jūs taip pat sužinojote, kaip naudoti Sequelize CLI, kad sukurtumėte sėklų failus, kad jūsų duomenų bazė būtų užpildyta pavyzdiniais duomenimis. Šios instrukcijos kodą galima rasti . „GitHub“ Norėdami sužinoti daugiau apie duomenų bazės perkėlimą, apsilankykite šiuose ištekliuose: Sequelizuoti dokumentaciją Atsisiųskite Github Išsaugoti Github