{"id":13529688,"url":"https://github.com/ballerina-platform/module-ballerinax-mongodb","last_synced_at":"2025-06-19T05:17:16.786Z","repository":{"id":37867396,"uuid":"108358462","full_name":"ballerina-platform/module-ballerinax-mongodb","owner":"ballerina-platform","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-15T08:43:06.000Z","size":1703,"stargazers_count":126,"open_issues_count":0,"forks_count":44,"subscribers_count":95,"default_branch":"master","last_synced_at":"2024-04-18T02:38:38.233Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ballerina","has_issues":false,"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/ballerina-platform.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-10-26T03:45:59.000Z","updated_at":"2024-04-26T05:36:25.533Z","dependencies_parsed_at":"2023-01-20T23:04:09.131Z","dependency_job_id":"966813a1-5ad5-470f-8e69-6eb68ff9667b","html_url":"https://github.com/ballerina-platform/module-ballerinax-mongodb","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/ballerina-platform/module-ballerinax-mongodb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerinax-mongodb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerinax-mongodb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerinax-mongodb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerinax-mongodb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ballerina-platform","download_url":"https://codeload.github.com/ballerina-platform/module-ballerinax-mongodb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerinax-mongodb/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260691057,"owners_count":23047109,"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-01T07:00:38.549Z","updated_at":"2025-06-19T05:17:11.770Z","avatar_url":"https://github.com/ballerina-platform.png","language":"Ballerina","funding_links":[],"categories":["Libraries"],"sub_categories":["Ballerina"],"readme":"# Ballerina MongoDB Connector\n\n[![Build Status](https://github.com/ballerina-platform/module-ballerinax-mongodb/workflows/CI/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-mongodb/actions?query=workflow%3ACI)\n[![Trivy](https://github.com/ballerina-platform/module-ballerinax-mongodb/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-mongodb/actions/workflows/trivy-scan.yml)\n[![codecov](https://codecov.io/gh/ballerina-platform/module-ballerinax-mongodb/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerinax-mongodb)\n[![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerinax-mongodb.svg)](https://github.com/ballerina-platform/module-ballerinax-mongodb/commits/master)\n[![GraalVM Check](https://github.com/ballerina-platform/module-ballerinax-mongodb/actions/workflows/build-with-bal-test-graalvm.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-mongodb/actions/workflows/build-with-bal-test-graalvm.yml)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n## Overview\n\n[MongoDB](https://docs.mongodb.com/v4.2/) is a general purpose, document-based, distributed database built for modern application developers and for the cloud era. MongoDB offers both a Community and an Enterprise version of the database.\n\nThe `ballerinax/mongodb` package offers APIs to connect to MongoDB servers and to perform various operations including CRUD operations, indexing, and aggregation.\n\nThe Ballerina MongoDB connector is compatible with MongoDB 3.6 and later versions.\n\n## Setup guide\n\nTo use the MongoDB connector, you need to have a MongoDB server running and accessible. For that, you can either install MongoDB locally or use the [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register), the cloud offering of the MongoDB.\n\n### Setup a MongoDB server locally\n\n1. Download and install the MongoDB server from the [MongoDB download center](https://www.mongodb.com/try/download/community).\n\n2. Follow the installation instructions provided in the download center.\n\n3. Follow the [instructions](https://www.mongodb.com/docs/manual/administration/install-community/#std-label-install-mdb-community-edition) for each operating system to start the MongoDB server.\n\n\u003e **Note:** This guide uses the MongoDB community edition for the setup. Alternatively, the enterprise edition can also be used.\n\n### Setup a MongoDB server using MongoDB Atlas\n\n1. Sign up for a free account in [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register).\n\n2. Follow the instructions provided in the [MongoDB Atlas documentation](https://docs.atlas.mongodb.com/getting-started/) to create a new cluster.\n\n3. Navigate to your MongoDB Atlas cluster.\n\n4. Select \"Database\" from the left navigation pane under the \"Deployment\" section and click \"connect\" button to open connection instructions.\n\n    ![MongoDB Atlas Connect](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-mongodb/master/docs/setup/resources/mongodb-atlas-database-page.png)\n\n5. Add your IP address to the IP access list or select \"Allow access from anywhere\" to allow all IP addresses to access the cluster.\n\n    ![MongoDB Atlas IP Access List](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-mongodb/master/docs/setup/resources/mongodb-atlas-ip-access-list.png)\n\n6. Click \"Choose a connection method\" and select \"Drivers\" under the \"Connect your application\". There you can find the connection string to connect to the MongoDB Atlas cluster.\n\n    ![MongoDB Atlas Connection Method](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-mongodb/master/docs/setup/resources/mongodb-atlas-connection-method.png)\n\n## Quickstart\n\n### Step 1: Import the module\n\nImport the `mongodb` module into the Ballerina project.\n\n```ballerina\nimport ballerinax/mongodb;\n```\n\n### Step 2: Initialize the MongoDB client\n\n#### Initialize the MongoDB client using the connection parameters\n\n```ballerina\nmongodb:Client mongoDb = check new ({\n    connection: {\n        serverAddress: {\n            host: \"localhost\",\n            port: 27017\n        },\n        auth: \u003cmongodb:ScramSha256AuthCredential\u003e{\n            username: \u003cusername\u003e,\n            password: \u003cpassword\u003e,\n            database: \u003cadmin-database\u003e\n        }\n    }\n});\n```\n\n#### Initialize the MongoDB client using the connection string\n\n```ballerina\nmongodb:Client mongoDb = check new ({\n    connection: \u003cconnection string obtained from the MongoDB server\u003e\n});\n```\n\n### Step 3: Invoke the connector operation\n\nNow, you can use the available connector operations to interact with MongoDB server.\n\n#### Retrieve a Database\n\n```ballerina\nmongodb:Database moviesDb = check mongoDb-\u003egetDatabase(\"movies\");\n```\n\n#### Retrieve a Collection\n\n```ballerina\nmongodb:Collection moviesCollection = check moviesDb-\u003egetCollection(\"movies\");\n```\n\n#### Insert a Document\n\n```ballerina\nMovie movie = {title: \"Inception\", year: 2010};\ncheck moviesCollection-\u003einsert(movie);\n```\n\n### Step 4: Run the Ballerina application\n\nSave the changes and run the Ballerina application using the following command.\n\n```bash\nbal run\n```\n\n## Examples\n\nThe MongoDB connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-mongodb/tree/master/examples/) covering common MongoDB operations.\n\n1. [Movie database](https://github.com/ballerina-platform/module-ballerinax-mongodb/tree/master/examples/movie-database) - Implement a movie database using MongoDB.\n2. [Order management system](https://github.com/ballerina-platform/module-ballerinax-mongodb/tree/master/examples/order-management-system) - Implement an order management system using MongoDB.\n\n## Issues and projects\n\nThe **Issues** and **Projects** tabs are disabled for this repository as this is part of the Ballerina library. To report bugs, request new features, start new discussions, view project boards, etc., visit the Ballerina library [parent repository](https://github.com/ballerina-platform/ballerina-library).\n\n## Building from the source\n\n### Setting up the prerequisites\n\n1. Download and install Java SE Development Kit (JDK) version 21. You can download it from either of the following sources:\n\n    * [Oracle JDK](https://www.oracle.com/java/technologies/downloads/)\n    * [OpenJDK](https://adoptium.net/)\n\n   \u003e **Note:** After installation, remember to set the `JAVA_HOME` environment variable to the directory where JDK was installed.\n\n2. Download and install [Ballerina Swan Lake](https://ballerina.io/).\n\n3. Download and install [Docker](https://www.docker.com/get-started).\n\n   \u003e **Note**: Ensure that the Docker daemon is running before executing any tests.\n\n4. Export Github Personal access token with read package permissions as follows,\n\n    ```bash\n    export packageUser=\u003cUsername\u003e\n    export packagePAT=\u003cPersonal access token\u003e\n    ```\n\n### Building the source\n\nExecute the commands below to build from the source.\n\n1. To build the package:\n\n    ```bash\n        ./gradlew clean build\n    ```\n\n2. To run the tests:\n\n   ```bash\n   ./gradlew clean test\n   ```\n\n3. To build the without the tests:\n\n   ```bash\n   ./gradlew clean build -x test\n   ```\n\n4. To run selected test groups:\n\n   ```bash\n   ./gradlew clean test -P groups=\u003cComma separated groups/test cases\u003e\n   ```\n\n5. To debug package with a remote debugger:\n\n   ```bash\n   ./gradlew clean build -P debug=\u003cport\u003e\n   ```\n\n6. To debug with the Ballerina language:\n\n   ```bash\n   ./gradlew clean build -P balJavaDebug=\u003cport\u003e\n   ```\n\n7. Publish the generated artifacts to the local Ballerina Central repository:\n\n    ```bash\n    ./gradlew clean build -P publishToLocalCentral=true\n    ```\n\n## Contribute to Ballerina\n\nAs an open-source project, Ballerina welcomes contributions from the community.\n\nFor more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).\n\n## Code of conduct\n\nAll the contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).\n\n## Useful links\n\n* For more information go to the [`mongodb` package](https://lib.ballerina.io/ballerinax/mongodb/latest).\n* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/).\n* Chat live with us via our [Discord server](https://discord.gg/ballerinalang).\n* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerinax-mongodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fballerina-platform%2Fmodule-ballerinax-mongodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerinax-mongodb/lists"}