{"id":25566514,"url":"https://github.com/pdmlab/migrate-semver-mongoose","last_synced_at":"2025-10-16T19:58:06.281Z","repository":{"id":57296978,"uuid":"66394932","full_name":"PDMLab/migrate-semver-mongoose","owner":"PDMLab","description":null,"archived":false,"fork":false,"pushed_at":"2020-02-21T13:52:45.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-26T17:08:13.704Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","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":"2016-08-23T19:00:38.000Z","updated_at":"2023-06-02T14:21:49.000Z","dependencies_parsed_at":"2022-09-01T08:40:47.264Z","dependency_job_id":null,"html_url":"https://github.com/PDMLab/migrate-semver-mongoose","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/PDMLab/migrate-semver-mongoose","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmigrate-semver-mongoose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmigrate-semver-mongoose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmigrate-semver-mongoose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmigrate-semver-mongoose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PDMLab","download_url":"https://codeload.github.com/PDMLab/migrate-semver-mongoose/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDMLab%2Fmigrate-semver-mongoose/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266413496,"owners_count":23924743,"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","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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:59.734Z","updated_at":"2025-10-16T19:58:01.245Z","avatar_url":"https://github.com/PDMLab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MongoDb migrations using mongoose and migrate-semver\n\n`migrate-semver-mongoose` is a plugin for [migrate-semver](https://github.com/PDMLab/migrate-semver) allowing you to do migrations based on [SemVer](http://semver.org/) and [mongoose](http://mongoosejs.com).\n\n## Installation\n\n```\nnpm install --save migrate-semver\nnpm install --save migrate-semver-mongoose\n```\n\n## Usage\n\n`migrate-semver` just handles the heavy lifting of finding the viable migrations to run based on a SemVer compliant version string passed into it.\nThe parts specific to MongoDb / Mongoose are handled by `migrate-semver-mongoose`.\n\nThe following example runs a migration for version `0.3.0`.\n\n```js\nconst SemVerMigration = require('migrate-semver');\nconst mongoosePlugin = require('migrate-semver-mongoose');\n\nconst migrationsDirectory = path.join(__dirname, 'migrations');\nconst migrateSemVer = new SemVerMigration({ migrationsDirectory }, mongoosePlugin());\nconst version = '0.3.0';\n\nmigrateSemVer.connect({ mongoServer: 'mongodb://localhost:27017/test' }, err =\u003e { \n  migrateSemVer.canMigrate({ version }, (err, canMigrate) =\u003e {\n    if (canMigrate) {\n      migrateSemVer.up({ version }, err =\u003e {\n        console.log('done');\n      });\n    }\n  })\n});\n```\n\n`migrate-semver-mongoose` handles several scenarios for you based on the example above: \n\n* If your current database has no migrations at all (so it might be empty at all), `migrate-semver` runs all available migrations until `0.3.0` (including `0.3.0`).\n* If your current database has version `0.2.0` applied and `0.3.0` is the next available migration, `0.3.0` is just applied.\n* If your current database has version `0.1.0` applied and `0.2.0` is also available, both `0.2.0` and `0.3.0` wil be applied.\n\nThe scenarios described above can be found in the tests.\n\n`migrate-semver-mongoose` allows you to specify the base directory which contains all your migration folders and files.\nJust pass the `migrationsDirectory` option to the `SemVerMigration` ctor function as shown above.\n\nThe file and folder structure has to follow this convention (the `index-up.js` can be renamed if you implement your own plugin):\n\n\u003cpre\u003e\n- \u0026lt;migrationsDirectory\u003e    \n  - 0.1.0\n    - index-up.js\n  - 0.2.0\n    - index-up.js\n  - 0.2.1\n    - index-up.js\n  - 0.3.0 \n    - index-up.js\n\u003c/pre\u003e\n\nThe `index-up.js` could look like this:\n\n```js\n'use strict';\nconst CustomerSchema = require('./schemas/customer');\n\n/**\n * @param {Object} options\n * @param {Object} options.conn\n * @param {Object} options.model\n * @param {Object} options.customOptions\n * @param continueWith\n */\nconst up = function (options, callback) {\n  const conn = options.conn;\n  const Customer = conn.model('Customer', CustomerSchema);\n  const customer = new Customer({\n    name: 'PDMLab'\n  });\n\n  customer.save(err =\u003e {\n    callback(err);\n  });\n};\n\nmodule.exports = {\n  up\n};\n```\n\nAs you can see, you get passed a `mongoose` connection instance so you don't mess with the `mongoose` default instance.\n\n### customCollectionName\n\nThe default name of the collection where the applied migrations are stored is `migrations`. You can change it by passing a different name into the plugin ctor function:\n\n```js\nconst customCollectionName = 'custom.migrations';\nmongoosePlugin({ migrationsCollectionName: customCollectionName })\n```\n\n### customOptions\n\nYou can pass custom options to the `up` function as child object of the `options` parameter.\nThese `customOptions` will be passed into `migrate-semver-mongoose` which handles them appropriately and they'll be passed into every migration as a child object of the `up` functions `options`.\n\nPassing the options to `migrate-semver`:\n \n```js\nconst customOptions =  { customName: 'Google' };\nmigrateSemVer.up({ version, customOptions }, err =\u003e {\n  const Customer = conn.model('Customer', CustomerSchema);\n  \n  Customer.findOne({ name: 'Google' }, (err, customer) =\u003e { \n    assert.notEqual(null, customer);\n    done();\n  });\n});\n```\n\nThe migration itself:\n\n```js\n/**\n * @param {Object} options\n * @param {Object} options.conn\n * @param {Object} options.model\n * @param {Object} [options.customOptions]\n * @param continueWith\n */\nconst up = function (options, continueWith) {\n  let name = 'PDMLab';\n\n  if (options.customOptions) {\n    name = options.customOptions.customName;\n  }\n  const conn = options.conn;\n  const Customer = conn.model('Customer', CustomerSchema);\n  const customer = new Customer({ name });\n\n  customer.save(err =\u003e {\n    continueWith(err);\n  });\n};\n\nmodule.exports = {\n  up\n};\n```\n \n## Running the tests\n\nThe tests require Docker (version 1.10+) and Docker Compose (version 1.6.0+). Make sure you have installed both.\n\n```\ndocker pull mongo:4.2\nnpm test\n```\n\n## Want to help?\n\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\nBefore sending a PR, please [create an issue](https://github.com/PDMLab/migrate-semver-mongoose/issues/new) to introduce your idea and have a reference for your PR.\n\nAlso please add tests and make sure to run `npm run eslint`.\n\n## License\n\nMIT License\n\nCopyright (c) 2016 PDMLab\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdmlab%2Fmigrate-semver-mongoose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdmlab%2Fmigrate-semver-mongoose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdmlab%2Fmigrate-semver-mongoose/lists"}