{"id":17980750,"url":"https://github.com/tepinly/mongogrator","last_synced_at":"2025-07-08T03:41:31.148Z","repository":{"id":257158954,"uuid":"857478346","full_name":"tepinly/mongogrator","owner":"tepinly","description":"A MongoDB migration CLI tool for Typescript \u0026 Javascript","archived":false,"fork":false,"pushed_at":"2024-10-30T16:15:58.000Z","size":94,"stargazers_count":11,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-07T16:08:26.321Z","etag":null,"topics":["bun","database","executable","hacktoberfest","migration","mongodb","nodejs","nosql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/tepinly.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-14T19:07:48.000Z","updated_at":"2025-03-25T12:50:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"bf77c011-560a-448a-b0ad-3f03ac4553ff","html_url":"https://github.com/tepinly/mongogrator","commit_stats":null,"previous_names":["tepinly/mongogrator"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tepinly/mongogrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tepinly%2Fmongogrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tepinly%2Fmongogrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tepinly%2Fmongogrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tepinly%2Fmongogrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tepinly","download_url":"https://codeload.github.com/tepinly/mongogrator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tepinly%2Fmongogrator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262151861,"owners_count":23266929,"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":["bun","database","executable","hacktoberfest","migration","mongodb","nodejs","nosql"],"created_at":"2024-10-29T18:06:11.758Z","updated_at":"2025-06-26T22:35:25.934Z","avatar_url":"https://github.com/tepinly.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/103be6a4-d02c-473a-b95b-39fd6a84d8a8\" alt=\"Mongogrator\" /\u003e\n\u003c/p\u003e\n\nMongogrator is a very fast database migration CLI for MongoDB. Its purpose is to easily create and run migrations for development and production stages\n\n## Installing\n\nUsing the following command, it will automatically download, install and add Mongogrator to `PATH`\n\n### MacOS/Linux\n\n```bash\ncurl -fsSL git.new/mongogrator-installer.sh | bash\n```\n\n### Windows\n\n```powershell\ncmd /c \"curl -L https://git.new/mongogrator-installer.ps1 | powershell -c -\"\n```\n\n## List of commands\n\n```sh\nMongogrator CLI\nUsage: mongogrator \u003ccommand\u003e [options]\n\nCommands:\n   init [--js]               Initialize a new configuration file\n   add                       Creates a new migration file with the provided name\n   list                      List all migrations and their status\n   migrate [config_path]     Run all migrations that have not been applied yet\n   version, -v, --version    Prints the current version of Mongogrator\n\nFlags:\n   --help, -h                Prints the detailed description of the command\n```\n\n## Usage guide\n\nA basic guide on how to use the CLI\n\n### Adding new migrations\n\nStart by initializing the config file\n\n```sh\nmongogrator init\n```\n\nThis initializes a `mongogrator.config.ts` file in the location of the command. You can optionally pass a `--js` flag at the end of the command to initialize in a js file\n\nSetup the `url` to the desired mongo cluster, and make sure it's running\n\n```sh\nmongogrator add insert_user\n```\n\nThis will create the migration file under the directory key assigned in the config `migrationsPath`\n\nThe following is an example of a newly created ts migration file\n\n```ts\nimport type { Db } from 'mongodb'\n\n/**\n * This function is called when the migration is run.\n * @param _db The mongodb database object that's passed to the migration\n */\nexport const migrate = async (_db: Db): Promise\u003cvoid\u003e =\u003e {\n  // Migration code here\n}\n```\n\nThe migrations are executed through the native MongoDB Node.js driver\n\n### Migration query example\n\n```ts\nimport type { Db } from 'mongodb'\n\n/**\n * This function is called when the migration is run.\n * @param _db The mongodb database object that's passed to the migration\n */\nexport const migrate = async (_db: Db): Promise\u003cvoid\u003e =\u003e {\n  // Migration code here\n  _db.collection('users').insertOne({ name: 'Alex' })\n}\n```\n\n### Migrations list\n\nYou can add as many migrations as you want and then call the `list` command to display the status of each\n\n```sh\nmongogrator list\n```\n\nThis will print out a list of all the migrations, each has a status of either `NOT MIGRATED` or `MIGRATED`\n\n```sh\n┌───┬───────────────────────────────┬──────────────┐\n│   │ migration                     │ status       │\n├───┼───────────────────────────────┼──────────────┤\n│ 0 │ 20240923150201806_insert_user │ NOT MIGRATED │\n└───┴───────────────────────────────┴──────────────┘\n```\n\nNaturally, the status will be `NOT MIGRATED` as we haven't run the migration yet\n\n### Running the migrations\n\nRun the migrations simply by calling\n\n```sh\nmongogrator migrate\n```\n\nThis will run all the migrations and log them to the database under the specified collection name in the config `logsCollectionName`\n\nFor production purposes, you can pass the config path to the `migrate` command directly if it's not accessible under the same path\n\n```sh\nmongogrator migrate /dist\n```\n\nNow if you run the `list` command again, it will reveal that the migration file has been successfully executed\n\n```sh\n┌───┬───────────────────────────────┬──────────────┐\n│   │ migration                     │ status       │\n├───┼───────────────────────────────┼──────────────┤\n│ 0 │ 20240923150201806_insert_user │ MIGRATED     │\n└───┴───────────────────────────────┴──────────────┘\n```\n\n### Logs collection schema\n\n```ts\n{\n  _id: objectId(),\n  name: string,\n  createdAt: Date(),\n}\n```\n\n## Configuration\n\n```ts\n{\n  url: 'mongodb://localhost:27017', // Cluster url\n  database: 'test', // Database name for which the migrations will be executed\n  migrationsPath: './migrations', // Migrations directory relative to the location of the commands\n  logsCollectionName: 'migrations', // Name of the logs collection that will be stored in the database\n  format: 'ts', // Format type of the migration files ['ts', 'js']\n}\n```\n\n\u003e [!IMPORTANT]\n\u003e all the config keys with path values are relative to the location of the config file itself\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftepinly%2Fmongogrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftepinly%2Fmongogrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftepinly%2Fmongogrator/lists"}