{"id":14956431,"url":"https://github.com/mongodb/mongo-jdbc-driver","last_synced_at":"2025-11-11T20:58:22.892Z","repository":{"id":37583744,"uuid":"210842288","full_name":"mongodb/mongo-jdbc-driver","owner":"mongodb","description":"JDBC Driver for MongoDB Atlas SQL interface","archived":false,"fork":false,"pushed_at":"2025-03-27T22:10:36.000Z","size":6099,"stargazers_count":40,"open_issues_count":6,"forks_count":38,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-29T23:08:11.209Z","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/mongodb.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}},"created_at":"2019-09-25T12:42:36.000Z","updated_at":"2025-03-27T22:10:39.000Z","dependencies_parsed_at":"2024-02-09T21:23:05.081Z","dependency_job_id":"5e70ae27-5539-4628-847b-cb89155e9025","html_url":"https://github.com/mongodb/mongo-jdbc-driver","commit_stats":{"total_commits":201,"total_committers":18,"mean_commits":"11.166666666666666","dds":0.7960199004975125,"last_synced_commit":"c2ba3081209cce95b0090a31c4007be7490d65f2"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb%2Fmongo-jdbc-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb%2Fmongo-jdbc-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb%2Fmongo-jdbc-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb%2Fmongo-jdbc-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mongodb","download_url":"https://codeload.github.com/mongodb/mongo-jdbc-driver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415969,"owners_count":20935388,"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-09-24T13:13:03.750Z","updated_at":"2025-11-11T20:58:22.887Z","avatar_url":"https://github.com/mongodb.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg height=\"90\" alt=\"MongoDB Atlas JDBC Driver\" align=\"right\" src=\"resources/media/MongoDBAtlasJDBC.png\" /\u003e\n\n# MongoDB Atlas SQL JDBC Driver\n\nThe MongoDB Atlas SQL JDBC Driver provides SQL connectivity to [MongoDB Atlas](https://www.mongodb.com/atlas) for client applications developed in Java.  \nSee the [Atlas SQL Documentation](https://www.mongodb.com/docs/datalake/admin/query-with-sql/) for more information.\n\nMongoDB Atlas SQL JDBC is a JDBC Type 4 driver compatible with the JDBC 4.2 specification.\n\n## Usage\n\n### Prerequisites\nMongoDB Atlas SQL JDBC driver requires Java 1.8 or higher.\n\n### Download and Install\nYou can download the precompiled driver (jars) from [Maven Central](https://search.maven.org/artifact/org.mongodb/mongodb-jdbc).  \nChoose `jar` in the Download dropdown for the lean jar (dependencies not included) or `all.jar` for the fat jar (dependencies bundled inside the jar). The name of the driver class is `com.mongodb.jdbc.MongoDriver`.\n\n### Verify Integrity of MongoDB JDBC Driver Packages\nTo verify the integrity of the JDBC Driver packages, follow the steps below:\n1. Import the Public Key:  \n- The public key ID is `BDDC8671F1BE6F4D5464096624A4A8409351E954`.\n- To import the key, run the following command: `gpg --keyserver \u003cserver url\u003e --recv-keys BDDC8671F1BE6F4D5464096624A4A8409351E954`.  \n- Replace `\u003cserver url\u003e` with one of the current GPG Keyservers supported by Maven Central Servers:  \n  - `keyserver.ubuntu.com`\n  - `keys.openpgp.org`\n  - `pgp.mit.edu`\n2. Verify Artifact:  \n- Download the artifact you want to verify along with the matching detached signature (`.asc`) file from [Maven Central](https://search.maven.org/artifact/org.mongodb/mongodb-jdbc).\n  - For example, `mongodb-jdbc-2.2.2.jar` and `mongodb-jdbc-2.2.2.jar.asc`.\n- To verify the signature, run the following command `gpg --verify \u003cdetached_signature_file\u003e \u003cartifact_to_verify\u003e`.\n  - For example, `gpg --verify mongodb-jdbc-2.2.2.jar.asc mongodb-jdbc-2.2.2.jar`.\n\n### Connection URL and properties\n\n#### Connection URL\nThe connection URL is based on MongoDB connection string and has the `jdbc:` prefix.\nThe general format for the connection URL is as follows, with items in square brackets ([ ]) being optional:\n```\njdbc:mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?option1=value1[\u0026option2=value2]...]\n```\n\nFor more details :\n- URI format: [https://www.mongodb.com/docs/manual/reference/connection-string/](https://www.mongodb.com/docs/manual/reference/connection-string/)\n- Supported options: [https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-connection-options](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-connection-options)\n\n##### Notes\n- Special characters in the JDBC url have to be URL encoded.\n- The driver can not connect to a mongod instance, only to MongoDB Atlas.\n\n#### Connection Properties\nAll connection options can also be specified through a Properties object parameter instead of the being directly in the URL.\nHowever, if an option is in both the URL and the Properties object, the connection will fail.\n\nIn addition to the standard MongoDB connection options there are a number of additional properties specific to the JDBC driver.  \nThese properties can only be specified using an additional Properties object parameter and not in the URL.\n\n| Property                      | Type    | Required | Default | Description   |\n| ----------------------------- | ------- | -------- | :-----: | ------------- |\n| database                      | String  | Yes      | Null    | The name of the database used when querying |\n| loglevel                      | String  | No       | OFF     | The log level used for logging. Supported levels by increasing verbosity are 'OFF', 'SEVERE', 'WARNING', 'INFO', 'FINE' and 'FINER' |\n| logdir                        | String  | No       | Null    | The directory to use for log files. If no logging directory is specified, the logs are sent to the console |\n\nThe following example demonstrates how to open a connection specifying :\n- The standard options `user` and `password` via a Properties object and ssl and authSource via the URL.\n- The JDBC specific options `database` (mandatory) and `loglevel` via a Properties object.\n```\n         java.util.Properties p = new java.util.Properties();\n         p.setProperty(\"user\", \"user\");\n         p.setProperty(\"password\", \"foo\");\n         p.setProperty(\"database\", \"test\");\n         p.setProperty(\"loglevel\", Level.SEVERE.getName());\n         System.out.println(\"Connecting to database test...\");\n         Connection conn = DriverManager.getConnection(\"mongodb://mydatalake-xxxx.a.query.mongodb.net/?ssl=true\u0026authSource=admin\", p);\n```\n\n## Development\n\n### Build From Source\nTo build and test the driver run the following commands from root dir.\n\n#### To build the lean jar which does not include the dependencies\n```\n./gradlew clean build\n```\n#### To run demo locally\n```\n./gradlew clean :demo:run\n```\n#### To generate the source Jar\n```\n./gradlew clean :sourceJar\n```\nYou can find the generated jar in build/libs/  \n\n#### To generate the fat Jar which includes all the dependencies\n```\n./gradlew clean :shadowJar\n```\nYou can find the generated jar in build/libs/  \n\n#### To generate the test Jar\n```\n./gradlew clean :testJar\n```\nYou can find the generated jar in build/libs/  \n\n\n#### To run the unit tests\n```\n./gradlew clean test\n```\n#### To fix lint problems\n```\n./gradlew spotlessApply\n```\n### Downloading mongosqltranslate Library\nThe driver requires the `mongosqltranslate` library for direct cluster SQL translation.  For initial gradle builds the\nlibrary files will be automatically downloaded to the cache directory `${project.rootDir}/.library_cache/`.\nIf a specific version of the library already exists in the cache, it will be used. \n#### Specifying library version:\nBy default, the `snapshot` version will be downloaded.  To use a specific version, use the libmongosqltranslateVersion \nproperty:\n```bash\n./gradlew clean build -PlibmongosqltranslateVersion=1.0.0-beta-1\n```\n#### Force Re-download:\nUnless the updateLibs property is set to true, cached versions will be used to avoid repeated downloads.  \n```bash\n# Override cached versions\n./gradlew clean build -PupdateLibs=true\n```\n#### Run download task only\n```bash\n./gradlew downloadLibMongosqlTranslate\n```\n\n## Integration Testing\nIntegration testing requires a local MongoDB and Atlas Data Federation instance to be running\n#### Environment Variables\n**ADF_TEST_LOCAL_USER**: Local ADF username  \n**ADF_TEST_LOCAL_PWD**: Local ADF password  \n**ADF_TEST_LOCAL_AUTH_DB**: Local ADF authentication database  \n**HAVE_LOCAL_MONGOHOUSE**: \"1\" if using local mongohouse source  \n**LOCAL_MONGOHOUSE_DIR**: Path to local mongohouse source\n\n**MDB_TEST_LOCAL_PORT** (Optional): Local MongoDB port\n\n#### To load integration test data\n```\n./gradlew runDataLoader\n```\n#### To generate integration test baseline configuration files\n```\n./gradlew runTestGenerator\n```\n\n### Running Local mongod and Atlas Data Federation\n`run_adf.sh` is a helper script that will start a local mongod and Atlas Data Federation instance, used for integration testing.\n#### Start \n```\n./resources/run_adf.sh start\n```\n#### Stop\n```\n./resources/run_adf.sh stop\n```\n#### Skip\nUse the `SKIP_RUN_ADF` option to skip the start and stop operations for those managing their own local instances.\n```\nexport SKIP_RUN_ADF=1\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongodb%2Fmongo-jdbc-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmongodb%2Fmongo-jdbc-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongodb%2Fmongo-jdbc-driver/lists"}