MongoDB API — Easy to enable and use

6 min readJan 3, 2025

Photo by Glenn Carstens-Peters on Unsplash

The Oracle Autonomous Database includes a powerful MongoDB API, enabling seamless integration with MongoDB clients while benefiting from the advanced features of Oracle’s secure and automated cloud platform.

While the MongoDB API is preconfigured and ready to go, we realized that there is a set of common questions about enabling it. This post aims to address the most common questions.

Why are Access Control Rules important?

Security measures do not allow enabling and operating the MongoDB API without proper Access Control Rules. These rules guarantee that you know exactly which clients or systems have access to this interface. These measures protect your data and ensure secure access. It’s not a nuisance, it’s for your safety: do you want to become the next prominent name in the data breach headlines? We don’t think so.

PS: If you happen to run your Autonomous Database in a private network, you know who has access, based on your tenancy’s Virtual Cloud Network (VCN). If that’s your setup, then you might be interested in the following blog, which discusses how to configure the Mongo DB API for private endpoints.

Step-by-Step: Enabling and using the MongoDB API

Set up Access Control Rules

You can do this at provisioning time, as seen in the following little snippet. You can choose a specific IP address, like your client, a CIDR block, or, for databases running in a private network in the Cloud, a virtual cloud network.

Set Access Control Rules at provisioning time

As you can see in the screenshot, there’s an easy way to grab the IP address of your client accessing the OCI console. If the client you want to enable is a different computer, you need to use that client’s IP address. The console does not know that, it only can get the IP address of the computer you’re running your browser on. Depending on the OS it should be easy to get the IP address either through the network setup or on the command line, like with the following OS command on Linux:

hbaer@phoenixXXXXX> curl ifconfig.me
148.x.x.x

After provisioning you can check and manage the setup on the console or through any Cloud API.

Check the status of the MongoDB API

Depending on the workload type, your MongoDB API might already be enabled, but it’s better to check it quickly. Go to the Console and choose the Tools tab to see the current status.

Are the Access Control Rules set? Check. Is the MongoDB API enabled? Check. Now it’s time to use it.

Validate the connectivity to the MongoDB API

The connection string is shown on the Console and can be copied straight from there.

It will look as follows:

mongodb://[user:password@]P6J9Y7KH8ABCDEF-MORETHANMONGO.adb.ap-tokyo-1.oraclecloudapps.com:27017/[user]?authMechanism=PLAIN&authSource=$external&ssl=true&retryWrites=false&loadBalanced=true

Let’s test this connect string using your user ADMIN. This is just to rule out that we have a database privilege issue. (More to this later.)

We need to replace the user and password with your settings and remove the square brackets. Pay attention—there are two places to specify the user! Also, as documented here, don’t forget to use the percent-encoding for any special characters in your password. So with my password @least1/2#?4Me, the connect string for ADMIN would look as follows:

mongodb://admin:%40least1%2F2%23%3F4Me@P6J9Y7KH8ABCDEF-MORETHANMONGO.adb.ap-tokyo-1.oraclecloudapps.com:27017/admin?authMechanism=PLAIN&authSource=$external&ssl=true&retryWrites=false&loadBalanced=true

The easiest way to connect with the MongoDB API is to use mongosh. You can download that from Mongo’s page or install it through other means, like brew on a Mac.

It did not work for me. What now?

As with a lot of things in life, sometimes you need more than one attempt. You have read this blog more than once, and it still does not work. You have checked all the settings

Wrong or incomplete Access Control Rules

To ensure that your client is actually able to reach the database and you are sure that the setup is correct, you should be able to connect with any SQL tool as well. The Access Control Rules are common for all connections. If you happen to get an error with sqlcl or sqlplus, something is wrong with your Access Control Rules.

A common error message with wrong Access Control rules for MongoDB API is

MongoNetworkError: Client network socket disconnected before secure TLS connection was established

At this point in time, the SQL*Net error message is (admittedly) better:

ORA-12506: TNS:listener rejected connection based on service ACL filtering

OK, you ruled out problems with Access Control Rules, but still cannot connect with your own user or use the MongoDB API successfully. Let’s check your user’s privileges then.

Insufficient database privileges

So it all works with ADMIN, but my newly created user just does not want to connect. Or you can connect but struggle with using MongoDB commands.

You might see an error message like the following when trying to connect:

MongoServerError: Database connection unavailable.  Ensure that the user exists and the schema is enabled for use with Oracle REST Data Services. A schema can be enabled by calling the PL/SQL procedure ORDS.ENABLE_SCHEMA.

Or you can connect successfully, but cannot create a new collection:

beth> db.foo.insertOne({"a":"c"})
Uncaught:
MongoServerError: ORA-06550: line 2, column 3:
PLS-00201: identifier 'DBMS_SODA_ADMIN' must be declared
ORA-06550: line 2, column 3:
PL/SQL: Statement ignored

Both of these errors give you an indication of what’s missing, so it’s time to check the privileges you have given to that user. The minimum privileges a user needs are:

GRANT CREATE SESSION
GRANT SODA_APP
Enable ORDS (Web) usage with ORDS_ADMIN

You cannot do anything with the database, though, so you’d need to add at least CREATE TABLE and some tablespace quota—or better yet, the DB_DEVELOPER_ROLE that was predefined for, well, developers.

For a new user BETH, the following commands executed as ADMIN would do the trick to connect and to work with collections (create, modify, delete, etc). The role DB_DEVELOPER_ROLE also includes SODA_APP, so that’s not listed here. There are also variants for the privileges being granted; you commonly see roles CONNECT and RESOURCE being granted, which is fine, too. Just check what you ultimately want to grant to your user.

grant create session to beth;
grant db_developer_role to beth;
alter user beth quota 1G on data;
begin
    ords_admin.enable_schema(true,'BETH');
end;
/

You can do all of this through the UI as well, as documented here.

That was not too hard, was it?

Well done. Now it’s time to explore what you can do with the MongoDB API, besides using it like a Mongo database. There are cool things you can do with this API in any Mongo program that you cannot even do with Mongo, such as:

Try it yourself with our do-it-yourself Livelab Unify the worlds of SQL, JSON, and MongoDB API. All you need is a computer and a web browser. You don’t even need a Cloud tenancy, although there’s no reason for anyone not to have an always-free Cloud account with Oracle.

We hope this blog was helpful to you. Don’t be shy and let us know what else we can do for you. Which MongoDB API feature excites you the most? What challenges have you faced using the MongoDB API?

Just leave us feedback and watch out for more to come in the future.

Oracle Developers