{"id":13565381,"url":"https://github.com/mongobee/mongobee","last_synced_at":"2025-04-03T22:31:14.982Z","repository":{"id":19055128,"uuid":"22281482","full_name":"mongobee/mongobee","owner":"mongobee","description":"MongoDB data migration tool for Java","archived":false,"fork":false,"pushed_at":"2022-12-16T01:14:55.000Z","size":470,"stargazers_count":500,"open_issues_count":58,"forks_count":164,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-11-04T18:46:45.757Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mongobee.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":"CODEOWNERS","security":null,"support":null}},"created_at":"2014-07-26T08:05:45.000Z","updated_at":"2024-10-26T21:28:02.000Z","dependencies_parsed_at":"2023-01-13T20:09:10.053Z","dependency_job_id":null,"html_url":"https://github.com/mongobee/mongobee","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongobee%2Fmongobee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongobee%2Fmongobee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongobee%2Fmongobee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongobee%2Fmongobee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mongobee","download_url":"https://codeload.github.com/mongobee/mongobee/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247090118,"owners_count":20881919,"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":"2024-08-01T13:01:45.849Z","updated_at":"2025-04-03T22:31:13.655Z","avatar_url":"https://github.com/mongobee.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"![mongobee](https://raw.githubusercontent.com/mongobee/mongobee/master/misc/mongobee_min.png)\n\n[![Build Status](https://travis-ci.org/mongobee/mongobee.svg?branch=master)](https://travis-ci.org/mongobee/mongobee) [![Coverity Scan Build Status](https://scan.coverity.com/projects/2721/badge.svg)](https://scan.coverity.com/projects/2721) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.mongobee/mongobee/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.mongobee/mongobee) [![Licence](https://img.shields.io/hexpm/l/plug.svg)](https://github.com/mongobee/mongobee/blob/master/LICENSE)\n---\n\n\n**mongobee** is a Java tool which helps you to *manage changes* in your MongoDB and *synchronize* them with your application.\nThe concept is very similar to other db migration tools such as [Liquibase](http://www.liquibase.org) or [Flyway](http://flywaydb.org) but *without using XML/JSON/YML files*.\n\nThe goal is to keep this tool simple and comfortable to use.\n\n\n**mongobee** provides new approach for adding changes (change sets) based on Java classes and methods with appropriate annotations.\n\n## Getting started\n\n### Add a dependency\n\nWith Maven\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.github.mongobee\u003c/groupId\u003e\n  \u003cartifactId\u003emongobee\u003c/artifactId\u003e\n  \u003cversion\u003e0.13\u003c/version\u003e\n\u003c/dependency\u003e\n```\nWith Gradle\n```groovy\ncompile 'org.javassist:javassist:3.18.2-GA' // workaround for ${javassist.version} placeholder issue*\ncompile 'com.github.mongobee:mongobee:0.13'\n```\n\n### Usage with Spring\n\nYou need to instantiate Mongobee object and provide some configuration.\nIf you use Spring can be instantiated as a singleton bean in the Spring context. \nIn this case the migration process will be executed automatically on startup.\n\n```java\n@Bean\npublic Mongobee mongobee(){\n  Mongobee runner = new Mongobee(\"mongodb://YOUR_DB_HOST:27017/DB_NAME\");\n  runner.setDbName(\"yourDbName\");         // host must be set if not set in URI\n  runner.setChangeLogsScanPackage(\n       \"com.example.yourapp.changelogs\"); // the package to be scanned for changesets\n  \n  return runner;\n}\n```\n\n\n### Usage without Spring\nUsing mongobee without a spring context has similar configuration but you have to remember to run `execute()` method to start a migration process.\n\n```java\nMongobee runner = new Mongobee(\"mongodb://YOUR_DB_HOST:27017/DB_NAME\");\nrunner.setDbName(\"yourDbName\");         // host must be set if not set in URI\nrunner.setChangeLogsScanPackage(\n     \"com.example.yourapp.changelogs\"); // package to scan for changesets\n\nrunner.execute();         //  ------\u003e starts migration changesets\n```\n\nAbove examples provide minimal configuration. `Mongobee` object provides some other possibilities (setters) to make the tool more flexible:\n\n```java\nrunner.setChangelogCollectionName(logColName);   // default is dbchangelog, collection with applied change sets\nrunner.setLockCollectionName(lockColName);       // default is mongobeelock, collection used during migration process\nrunner.setEnabled(shouldBeEnabled);              // default is true, migration won't start if set to false\n```\n\nMongoDB URI format:\n```\nmongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database[.collection]][?options]]\n```\n[More about URI](http://mongodb.github.io/mongo-java-driver/3.5/javadoc/)\n\n\n### Creating change logs\n\n`ChangeLog` contains bunch of `ChangeSet`s. `ChangeSet` is a single task (set of instructions made on a database). In other words `ChangeLog` is a class annotated with `@ChangeLog` and containing methods annotated with `@ChangeSet`.\n\n```java \npackage com.example.yourapp.changelogs;\n\n@ChangeLog\npublic class DatabaseChangelog {\n  \n  @ChangeSet(order = \"001\", id = \"someChangeId\", author = \"testAuthor\")\n  public void importantWorkToDo(DB db){\n     // task implementation\n  }\n\n\n}\n```\n#### @ChangeLog\n\nClass with change sets must be annotated by `@ChangeLog`. There can be more than one change log class but in that case `order` argument should be provided:\n\n```java\n@ChangeLog(order = \"001\")\npublic class DatabaseChangelog {\n  //...\n}\n```\nChangeLogs are sorted alphabetically by `order` argument and changesets are applied due to this order.\n\n#### @ChangeSet\n\nMethod annotated by @ChangeSet is taken and applied to the database. History of applied change sets is stored in a collection called `dbchangelog` (by default) in your MongoDB\n\n##### Annotation parameters:\n\n`order` - string for sorting change sets in one changelog. Sorting in alphabetical order, ascending. It can be a number, a date etc.\n\n`id` - name of a change set, **must be unique** for all change logs in a database\n\n`author` - author of a change set\n\n`runAlways` - _[optional, default: false]_ changeset will always be executed but only first execution event will be stored in dbchangelog collection\n\n##### Defining ChangeSet methods\nMethod annotated by `@ChangeSet` can have one of the following definition:\n\n```java\n@ChangeSet(order = \"001\", id = \"someChangeWithoutArgs\", author = \"testAuthor\")\npublic void someChange1() {\n   // method without arguments can do some non-db changes\n}\n\n@ChangeSet(order = \"002\", id = \"someChangeWithMongoDatabase\", author = \"testAuthor\")\npublic void someChange2(MongoDatabase db) {\n  // type: com.mongodb.client.MongoDatabase : original MongoDB driver v. 3.x, operations allowed by driver are possible\n  // example: \n  MongoCollection\u003cDocument\u003e mycollection = db.getCollection(\"mycollection\");\n  Document doc = new Document(\"testName\", \"example\").append(\"test\", \"1\");\n  mycollection.insertOne(doc);\n}\n\n@ChangeSet(order = \"003\", id = \"someChangeWithDb\", author = \"testAuthor\")\npublic void someChange3(DB db) {\n  // This is deprecated in mongo-java-driver 3.x, use MongoDatabase instead\n  // type: com.mongodb.DB : original MongoDB driver v. 2.x, operations allowed by driver are possible\n  // example: \n  DBCollection mycollection = db.getCollection(\"mycollection\");\n  BasicDBObject doc = new BasicDBObject().append(\"test\", \"1\");\n  mycollection .insert(doc);\n}\n\n@ChangeSet(order = \"004\", id = \"someChangeWithJongo\", author = \"testAuthor\")\npublic void someChange4(Jongo jongo) {\n  // type: org.jongo.Jongo : Jongo driver can be used, used for simpler notation\n  // example:\n  MongoCollection mycollection = jongo.getCollection(\"mycollection\");\n  mycollection.insert(\"{test : 1}\");\n}\n\n@ChangeSet(order = \"005\", id = \"someChangeWithSpringDataTemplate\", author = \"testAuthor\")\npublic void someChange5(MongoTemplate mongoTemplate) {\n  // type: org.springframework.data.mongodb.core.MongoTemplate\n  // Spring Data integration allows using MongoTemplate in the ChangeSet\n  // example:\n  mongoTemplate.save(myEntity);\n}\n\n@ChangeSet(order = \"006\", id = \"someChangeWithSpringDataTemplate\", author = \"testAuthor\")\npublic void someChange5(MongoTemplate mongoTemplate, Environment environment) {\n  // type: org.springframework.data.mongodb.core.MongoTemplate\n  // type: org.springframework.core.env.Environment\n  // Spring Data integration allows using MongoTemplate and Environment in the ChangeSet\n}\n```\n\n### Using Spring profiles\n     \n**mongobee** accepts Spring's `org.springframework.context.annotation.Profile` annotation. If a change log or change set class is annotated  with `@Profile`, \nthen it is activated for current application profiles.\n\n_Example 1_: annotated change set will be invoked for a `dev` profile\n```java\n@Profile(\"dev\")\n@ChangeSet(author = \"testuser\", id = \"myDevChangest\", order = \"01\")\npublic void devEnvOnly(DB db){\n  // ...\n}\n```\n_Example 2_: all change sets in a changelog will be invoked for a `test` profile\n```java\n@ChangeLog(order = \"1\")\n@Profile(\"test\")\npublic class ChangelogForTestEnv{\n  @ChangeSet(author = \"testuser\", id = \"myTestChangest\", order = \"01\")\n  public void testingEnvOnly(DB db){\n    // ...\n  } \n}\n```\n\n#### Enabling @Profile annotation (option)\n      \nTo enable the `@Profile` integration, please inject `org.springframework.core.env.Environment` to you runner.\n\n```java      \n@Bean @Autowired\npublic Mongobee mongobee(Environment environment) {\n  Mongobee runner = new Mongobee(uri);\n  runner.setSpringEnvironment(environment)\n  //... etc\n}\n```\n\n## Known issues\n\n##### Mongo java driver conflicts\n\n**mongobee** depends on `mongo-java-driver`. If your application has mongo-java-driver dependency too, there could be a library conflicts in some cases.\n\n**Exception**:\n```\ncom.mongodb.WriteConcernException: { \"serverUsed\" : \"localhost\" , \n\"err\" : \"invalid ns to index\" , \"code\" : 10096 , \"n\" : 0 , \n\"connectionId\" : 955 , \"ok\" : 1.0}\n```\n\n**Workaround**:\n\nYou can exclude mongo-java-driver from **mongobee**  and use your dependency only. Maven example (pom.xml) below:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.mongodb\u003c/groupId\u003e\n    \u003cartifactId\u003emongo-java-driver\u003c/artifactId\u003e\n    \u003cversion\u003e3.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.github.mongobee\u003c/groupId\u003e\n  \u003cartifactId\u003emongobee\u003c/artifactId\u003e\n  \u003cversion\u003e0.9\u003c/version\u003e\n  \u003cexclusions\u003e\n    \u003cexclusion\u003e\n      \u003cgroupId\u003eorg.mongodb\u003c/groupId\u003e\n      \u003cartifactId\u003emongo-java-driver\u003c/artifactId\u003e\n    \u003c/exclusion\u003e\n  \u003c/exclusions\u003e\n\u003c/dependency\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongobee%2Fmongobee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmongobee%2Fmongobee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongobee%2Fmongobee/lists"}