{"id":25566510,"url":"https://github.com/pdmlab/massive-migrate","last_synced_at":"2025-04-12T10:51:29.069Z","repository":{"id":57291745,"uuid":"41419685","full_name":"PDMLab/massive-migrate","owner":"PDMLab","description":"Postgres migrations for Node.js based on Massive-js","archived":false,"fork":false,"pushed_at":"2016-06-13T21:09:40.000Z","size":31,"stargazers_count":8,"open_issues_count":4,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T09:59:06.564Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PDMLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-26T10:29:25.000Z","updated_at":"2023-12-29T16:10:20.000Z","dependencies_parsed_at":"2022-08-27T12:20:24.444Z","dependency_job_id":null,"html_url":"https://github.com/PDMLab/massive-migrate","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmassive-migrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmassive-migrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmassive-migrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmassive-migrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PDMLab","download_url":"https://codeload.github.com/PDMLab/massive-migrate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248557844,"owners_count":21124165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-20T22:32:57.103Z","updated_at":"2025-04-12T10:51:29.049Z","avatar_url":"https://github.com/PDMLab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# massive-migrate\n\nMassive-Migrate is a small migrations library based on [Massive-js](https://github.com/robconery/massive-js) that can help you implement migrations for Postgres databases using Node.js.\n\n## Installation\n\n```bash\nnpm install massive-migrate --save\n```\n\n## Usage\n\nOnce installed, you can use it by calling the `runUpMigration` function of a `Migrations` instance you've created before:\n\n```js\nvar massiveMigrate = require(\"massive-migrate\");\nvar conn = \"postgresql://postgres:postgres@localhost:5432/postgres\";\nvar migrationsDirectory = path.join(__dirname,'/migrations');\nvar name = '0.1.0';\nvar options =  {\n\tconnectionString : conn,\n\tdirectory : migrationsDirectory\n}\n\nmassiveMigrate(options, function (err, migrations) {\n    if (err) { \n        return console.log('migration error', err)\n    }\n    \n    migrations.runUpMigration({ name : name }, function(err) {\n        if(!err) {\n        \tconsole.log('migration done');\n        }\n    });\n});\n```\n\nSimple migrations can be a single file (like `0.1.0`-up.sql).  For situations where additional coding logic for each migration or multiple SQL migrations per `version` are required a directory can be created to hold up migrations and a `\u003cname\u003e-up.js` migration script.\n\n#### Simple Migrations\n\nThe simple migration directory layout for your `migrationsDirectory` will be like:\n\n```\n├── migrations\n│    └── 0.1.0-up.sql\n│    └── 0.2.0-up.sql\n└── app.js\n```\n\nThe migration file's name can be whatever you like but must end in `-up.sql` and should contain standard postgres SQL.  An example app.js to run these migrations could look like:\n\n```js\nvar massiveMigrate = require(\"massive-migrate\");\nvar conn = \"postgresql://postgres:postgres@localhost:5432/postgres\";\nvar migrationsDirectory = path.join(__dirname,'/migrations');\nvar options =  {\n\tconnectionString : conn,\n\tdirectory : migrationsDirectory\n}\n\nmassiveMigrate(options, function () {\n    migrations.runUpMigration({ name : '0.1.0' }, function(err) {\n        if(err) {\n            console.log(\"Error running migration\", err);\n            return;\n        }\n        migrations.runUpMigration({ name : '0.2.0' }, function(err) {\n            if(err) {\n                console.log(\"Error running migration\", err);\n                return;\n            }\n            console.log('Migrations successfully applied!');\n        }\n    });\n});\n```\n\n\n#### Advanced Migrations\n\nFor the second case where you want more control over the migrations or additional migration files per `version` you'll create a directory to hold the SQL migration files and a script to execute them.  For example, if want to do an `up`-migration to version `0.1.0`, you must have a directory `0.1.0` in your `migrationsDirectory`.\n\n```\n├── migrations\n│    └── 0.1.0\n└── app.js\n```\n\nThe parameter for the `up` function is an options object containing at least the name of the migration that should be run. The order of the operations to be done during the `0.1.0` `up` migration is defined in a script whose name by convention is `name` of the migration + `up.js`. Thus for the up migration `0.1.0` it is `0.1.0-up.js`.\n\nThe migration script has to reside below the `0.1.0` folder shown in the the tree above:\n\n```\n├── migrations\n│    └── 0.1.0\n│      └── 0.1.0-up.js\n└── app.js\n```\n\nAs the core idea of [Massive-js](https://github.com/robconery/massive-js) (on top of which Massive-Migrate is build) is the usage of `.SQL` files, the migrations themselve are written in `.SQL` files as well.\n\nIn our `0.1.0` `up` migration we want to create a table `customer` using the `createcustomertable.sql` file:\n\n```SQL\nBEGIN;\nCREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";\nCREATE TABLE IF NOT EXISTS Customer (\n  ID UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n  companyname1 VARCHAR(40),\n  companyname2 VARCHAR(40),\n  addressline1 VARCHAR(40),\n  addressline2 VARCHAR(40),\n  zipcode VARCHAR(10),\n  city VARCHAR(40),\n  salestaxidentificationnumber VARCHAR(14),\n  createdat DATE DEFAULT now()\n);\nEND;\n```\n\nWe also want to create a `salutation` table using the `createsalutationtable.sql` file:\n\n```SQL\nBEGIN;\nCREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";\nCREATE TABLE IF NOT EXISTS salutation (\n  ID UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n  salutation VARCHAR(40),\n  male BOOL,\n  female BOOL,\n  genderless BOOL,\n  createdat DATE DEFAULT now()\n);\nEND;\n```\n\nBoth `.SQL` files have to be in the `up` folder below your `0.1.0` migration folder:\n\n```\n├── migrations\n│    └── 0.1.0\n│         ├── up\n│         │    ├── createcustomertable.sql\n│         │    └── createsalutationtable.sql\n│         └── 0.1.0-up.js\n└── app.js\n```\n\nThe final piece for our migration is the implementation of the migration script named `0.1.0-up.js` which gets hooked up for the migration by Massive-Migrate:\n\n```js\nvar async = require('async');\n\nexports.up = function(db, options, callback) {\n    async.parallel([\n        function(cb) {\n            db.createsalutationtable(function(err, result){\n                if(err) {\n                    console.log('up error while creating salutation table: ', err)\n                }\n                console.log('created salutation table', result);\n                cb()\n            });\n\n        },\n        function(cb) {\n            db.createcustomertable(function(err, result) {\n                if(err) {\n                    console.log('up error while creating customer table: ', err)\n                }\n                console.log('created customer table', result);\n                cb()\n            })\n        }\n    ], function(err, result) {\n        callback(err)\n    })\n\n};\n```\n\nIf you run your application which calls the migration, you get this output:\n\n```bash`\n$ node app.js\ncreated salutation table\ncreated customer table\nmigration done\n```\n\nYour database now contains the two tables as well as a table `pgmigrations`:\n\n\n```\n│    id    │   name    │  scriptname  │  dateapplied  │\n├──────────┼───────────┼──────────────┼───────────────┤\n│  \u003cguid\u003e  │   0.1.0   │   0.1.0-up   │    \u003cdate\u003e     │\n```\n\n## Running a series of migrations\nIf you want to run more than one migration, you can just follow the convention and provide multiple migrations, each having their folder containing the `.SQL` files and their up script.\n\nThen you can run them in a series like this:\n\n```js\nvar massiveMigrate = require(\"massive-migrate\");\nvar conn = \"postgresql://postgres:postgres@localhost:5432/postgres\";\nvar migrationsDirectory = path.join(__dirname,'/migrations');\nvar options =  {\n\tconnectionString : conn,\n\tdirectory : migrationsDirectory\n}\n\nmassiveMigrate(options, function () {\n    migrations.runUpMigration({ name : '0.1.0' }, function(err) {\n        if(!err) {\n          migrations.runUpMigration({ name : '0.2.0' }, function(err) {\n        \t  console.log('migration done');\n        \t}\n        }\n    });\n});\n```\n\n## Passing custom params to the up script\nIf you want to pass custom params to the up script when calling the `runUpMigration` function, you can do so.\n\nJust apply your custom params to the options object like shown with the `seedTestData` param:\n\n```js\nvar massiveMigrate = require(\"massive-migrate\");\nvar conn = \"postgresql://postgres:postgres@localhost:5432/postgres\";\nvar migrationsDirectory = path.join(__dirname,'/migrations');\nvar name = '0.1.0';\nvar options =  {\n\tconnectionString : conn,\n\tdirectory : migrationsDirectory\n}\n\nmassiveMigrate(options, function () {\n    migrations.runUpMigration({ name : name, seedTestData : true }, function(err) {\n        if(!err) {\n        \tconsole.log('migration done');\n        }\n    });\n});\n```\n\nIn your `up`-script you can simply access the `seedTestData` param via the `options` param being passed in to the `up` function:\n\n\n```js\nexports.up = function(db, options, callback) {\n    async.parallel([\n        function(cb) {\n            db.createsalutationtable(function(err, result){\n                if(err) {\n                    console.log('up error while creating salutation table: ', err)\n                }\n                cb()\n            });\n\n        },\n        function(cb) {\n            db.createcustomertable(function(err, result) {\n                if(err) {\n                    console.log('up error while creating customer table: ', err)\n                    cb();\n                }\n                else {\n                    if(options.seedTestData) {\n                        db.seedcustomertestdata(function(err) {\n                            cb();\n                        })\n                    } else {\n                        cb();\n                    }\n                }\n            })\n        }\n    ], function(err, result) {\n        callback(err)\n    })\n};\n```\n\n## Does a migration already exist? \nIf you want to know if a migration has been applied already, you can ask the migrations:\n\n```js\nvar massiveMigrate = require(\"massive-migrate\");\nvar conn = \"postgresql://postgres:postgres@localhost:5432/postgres\";\nvar migrationsDirectory = path.join(__dirname,'/migrations');\nvar name = '0.1.0';\nvar options =  {\n\tconnectionString : conn,\n\tdirectory : migrationsDirectory\n}\n\nmassiveMigrate(options, function () {\n    migrations.hasUpMigration(name, function(err, result) {\n        if(!err) {\n        \tconsole.log('migration exists', result); // true or false\n        }\n    });\n});\n```\n\nIf you're trying to run a migration that has been already applied, you'll get receive an error:\n\n`'Migration has been applied already'`\n\nFor more details, please take a look at the tests.\n\n## Get all applied migrations\nIf you need details (`id`, `name`, `scriptname` and `dateapplied`) about all applied migrations, just call the `getAppliedMigrations` function:\n\n```js\nvar massiveMigrate = require(\"massive-migrate\");\nvar conn = \"postgresql://postgres:postgres@localhost:5432/postgres\";\nvar migrationsDirectory = path.join(__dirname,'/migrations');\nvar options =  {\n\tconnectionString : conn,\n\tdirectory : migrationsDirectory\n}\n\nmassiveMigrate(options, function () {\n    migrations.runUpMigration({ name : '0.1.0' }, function(err) {\n        if(err) {\n            console.log(\"Error running migration\", err);\n            return;\n        }\n        migrations.runUpMigration({ name : '0.2.0' }, function(err) {\n            if(err) {\n                console.log(\"Error running migration\", err);\n                return;\n            }\n            console.log('Migrations successfully applied!');\n        }\n    });\n});\n```\n\n## Running the tests\nYou can choose two variants to run the tests: against a local Postgres installation or using Postgres in a Docker container.\n\nWithout Docker, create a local Postgres database named `postgres` with username and password `postgres`, listening on `localhost:5432`.\n\nThen, run the tests:\n```bash\nnpm test\n```\n\nIf you want to use Docker with no local Postgres installation required, run your tests like this:\n\n```\nnpm run dockerpostgres\nnpm test\n```\n\n## Want to help?\nThis project is just getting off the ground and could use some help with cleaning things up and refactoring.\n\nIf you want to contribute - we'd love it! Just open an issue to work against so you get full credit for your fork. You can open the issue first so we can discuss and you can work your fork as we go along.\n\nIf you see a bug, please be so kind as to show how it's failing, and we'll do our best to get it fixed quickly.\n\n## License (BSD 3-Clause)\n\nCopyright (c) 2015, PDMLab e.K.\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n  list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice,\n  this list of conditions and the following disclaimer in the documentation\n  and/or other materials provided with the distribution.\n\n* Neither the name of massive-migrate nor the names of its\n  contributors may be used to endorse or promote products derived from\n  this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdmlab%2Fmassive-migrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdmlab%2Fmassive-migrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdmlab%2Fmassive-migrate/lists"}