{"id":19122857,"url":"https://github.com/digitalbazaar/bedrock-mongodb","last_synced_at":"2025-05-05T18:26:24.667Z","repository":{"id":25257014,"uuid":"28682127","full_name":"digitalbazaar/bedrock-mongodb","owner":"digitalbazaar","description":"Bedrock mongodb module","archived":false,"fork":false,"pushed_at":"2025-03-07T22:34:18.000Z","size":365,"stargazers_count":2,"open_issues_count":4,"forks_count":3,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-05T18:26:17.406Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalbazaar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2015-01-01T06:57:01.000Z","updated_at":"2025-03-07T22:34:22.000Z","dependencies_parsed_at":"2023-12-06T22:22:48.773Z","dependency_job_id":"9992bc70-754f-4651-8d14-9ad19baf839f","html_url":"https://github.com/digitalbazaar/bedrock-mongodb","commit_stats":{"total_commits":517,"total_committers":10,"mean_commits":51.7,"dds":0.6808510638297872,"last_synced_commit":"b4c1c104934a0806e74fce491ca3e68b084cb101"},"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbedrock-mongodb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbedrock-mongodb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbedrock-mongodb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbedrock-mongodb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalbazaar","download_url":"https://codeload.github.com/digitalbazaar/bedrock-mongodb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252552039,"owners_count":21766625,"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-11-09T05:23:18.012Z","updated_at":"2025-05-05T18:26:24.640Z","avatar_url":"https://github.com/digitalbazaar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bedrock-mongodb\n\nA [bedrock][] module that creates a simple MongoDB database and provides an\neasy API for creating and working with its collections.\n\n## Requirements\n\n- npm v9+\n\n## Quick Examples\n\n```\nnpm install @bedrock/mongodb\n```\n\nBelow is an example that simply opens a collection when the database is ready\nand then runs a query and prints the result. A more common use case for a\nmodule that uses `@bedrock/mongodb` would be to expose its own API that hides\nthe details of using whatever collections it has opened.\n\n```js\nimport * as bedrock from '@bedrock/core';\nimport * as database from '@bedrock/mongodb';\n\n// custom configuration\nbedrock.config.mongodb.name = 'my_project_dev'; // default: bedrock_dev\nbedrock.config.mongodb.host = 'localhost';      // default: localhost\nbedrock.config.mongodb.protocol = 'mongodb';    // default: mongodb\nbedrock.config.mongodb.port = 27017;            // default: 27017\nbedrock.config.mongodb.username = 'my_project'; // default: bedrock\nbedrock.config.mongodb.password = 'password';   // default: password\n\n// the mongodb database 'my_project_dev' and the 'my_project' user will\n// be created on start up following a prompt for the admin user credentials\n\n// alternatively, use `mongodb` URL format (preferred for deployments):\nbedrock.config.mongodb.url = 'mongodb://localhost:27017/my_project_dev';\n\n// open some collections once the database is ready\nbedrock.events.on('bedrock-mongodb.ready', async function() {\n  await database.openCollections(['collection1', 'collection2']);\n\n  // do something with the open collection(s)\n  const result = await database.collections.collection1.findOne({id: 'foo'});\n  console.log('result', result);\n});\n\nbedrock.start();\n```\n\n## Configuration\n\nFor documentation on database configuration, see [config.js](./lib/config.js).\n\n### Connecting and Authenticating\nMongoDB's documentation provides examples on how to authenticate using a myriad\nnumber of connection strings.\n\n[Mongo Node Driver connect docs](https://www.mongodb.com/docs/drivers/node/current/fundamentals/connection/connect/)\n\nYou can connect using a url by setting:\n```js\nconfig.mongodb.url = 'mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/?authSource=admin';\n```\n\nYou can also connect to access-enabled mongo servers using some small changes to the\n`config.mongodb.connectOptions`, however, the `config.mongodb.url` option is highly\npreferable and should cover most use cases:\n\n```js\nimport {config} from '@bedrock/core';\n\nconfig.mongodb.username = 'me';\nconfig.mongodb.password = 'password';\nconfig.mongodb.protocol = 'mongodb+srv';\nconst {connectOptions} = config.mongodb;\n// optional, only required if connecting to a replicaSet\nconnectOptions.replicaSet = 'my_provider_replica_set';\n// optional, but required in production by many providers\nconnectOptions.ssl = true;\n// optional, only required if your provider requires tls\nconnectOptions.tls = true;\n// the `authSource` option replaces the older `authDB` option\n// it should be specified or else it will be the `mongodb.name`\nconnectOptions.authSource = 'my_provider_auth_db';\n```\nMongoDB provides [excellent docs on their connection strings](https://docs.mongodb.com/manual/reference/connection-string/)\n\n## Requirements\n\n* Linux or Mac OS X (also works on Windows with some coaxing)\n* node.js \u003e= 20.x\n* npm \u003e= 10.x\n* mongodb \u003e= 6.x\n* libkrb5-dev \u003e= 1.x.x\n\n## Setup\n\n1. Ensure an admin user is set up on mongodb. To do so, follow the instructions\n   at [mongodb.org](http://docs.mongodb.org/manual/tutorial/add-user-administrator/)\n   for your version of MongoDB. Version 6.x is currently supported.\n2. [optional] Tweak your project's configuration settings; see\n   [Configuration](#configuration) or [Quick Examples](#quick-examples).\n\n## API\n\n### collections\n\nAn object whose keys are the names of the collections that have been\nopened via `openCollections`.\n\n### openCollections(collections)\n\nOpens a set of collections (creating them if necessary), if they aren't already\nopen. Once all of the collections are open the returned promise resolves. If\nan error occurs, the returned promise rejects. If no error occurs, then once\nthe promise resolves, the `collections` object will have keys that match the\ncollection names and values that are instances of\n[mongodb-native][]\n[Collection](https://mongodb.github.io/node-mongodb-native/6.14/classes/Collection.html).\n\n### createGridFSBucket(options)\n\nCreates and returns a new `GridFSBucket` from the native driver. Options are\nthe same as for `GridFSBucket`. The current client is used and the\n`writeConcern` option defaults to the `writeOptions` config value.\n\n## Test Mode\n### Drop Collections on Initialization\nWhen doing testing, it is often desirable to have empty collections at the\nbeginning of test operations.  This may be accomplished by the following\nconfiguration parameters **IN ADDITION** to specifying the test parameter on\nthe command line.  The test configuration in a project should **ALWAYS**\nspecify a **UNIQUE** mongodb database.\n```\n// Always specify a unique mongodb database for testing\nbedrock.config.mongodb.name = 'my_project_test';\nbedrock.config.mongodb.host = 'localhost';\nbedrock.config.mongodb.port = 27017;\nbedrock.config.mongodb.username = 'test'; // default: bedrock\nbedrock.config.mongodb.password = 'password';\n// drop collections on initialization\nbedrock.config.mongodb.dropCollections.onInit = true;\n// if 'onInit' is specified, 'collections' must also be specified\n// if collections is an empty array, ALL collections will be dropped\nbedrock.config.mongodb.dropCollections.collections = [];\n```\n\n## License\n\n[Apache License, Version 2.0](LICENSE) Copyright 2011-2024 Digital Bazaar, Inc.\n\nOther Bedrock libraries are available under a non-commercial license for uses\nsuch as self-study, research, personal projects, or for evaluation purposes.\nSee the\n[Bedrock Non-Commercial License v1.0](https://github.com/digitalbazaar/bedrock/blob/main/LICENSES/LicenseRef-Bedrock-NC-1.0.txt)\nfor details.\n\nCommercial licensing and support are available by contacting\n[Digital Bazaar](https://digitalbazaar.com/) \u003csupport@digitalbazaar.com\u003e.\n\n[bedrock]: https://github.com/digitalbazaar/bedrock\n[mongodb-native]: https://www.mongodb.com/docs/drivers/node/current/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fbedrock-mongodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalbazaar%2Fbedrock-mongodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fbedrock-mongodb/lists"}