Perform the following steps to get started to use the Oracle Database API for MongoDB:

1. Install and configure ORDS:

   From a command prompt, install and configure ORDS using the following commands:

   Note:

   • If you are installing ORDS against the Autonomous Database, then use the command ords install adb.
   • Oracle API for MongoDB is only supported for installations in a non-CDB database or PDB.

   See Also:

   • Installing Oracle REST Data Services
   • Installing and Configuring Customer Managed ORDS on Autonomous Database
   1. Install ORDS in a standalone mode in a non-CDB Database or in a PDB.

      Note:

      Oracle API for MongoDB is only supported for installations in a non-CDB database or PDB.

      ords install

   2. By default, the Oracle API for MongoDB is not enabled. To enable the API, in your configuration, include the following:

      ords config set mongo.enabled true

   3. Start ORDS

      ords serve

   When the MongoDB API is enabled, you will get a notification and you get the connect string when ORDS is started.

   Log showing that the Oracle API for MongoDB is enabled:
   After starting ORDS using the ords serve command, the log shows a message similar to the following to verify if the Oracle API for MongoDB is enabled:

   Disabling document root because the specified folder does not exist: ./config/global/doc_root
   2022-08-17T15:23:04.043Z INFO        Oracle API for MongoDB listening on port: 27017
   2022-08-17T15:23:04.050Z INFO        The Oracle API for MongoDB connection string is:
   mongodb://[{user}:{password}@]localhost:27017/{user}?authMechanism=PLAIN&authSource=$external&ssl=true&retryWrites=false&loadBalanced=true
   

2. Create an ORDS-enabled user:
   Leave the server running and from SQLcl, create an ORDS-enabled user.

   See Also:

   Creation of Users, Authentication, and Authorization

   create user foo identified by "<Password>";    
   grant soda_app, create session, create table, create view, create sequence, create procedure, create job, unlimited tablespace to foo;    
   connect foo/<Password>   
   exec ords.enable_schema;

3. Connect to ORDS using the MongoDB shell:

   By default, ORDS uses a self-signed certificate for secure communication. The Mongo API does not allow self-signed certificates, so you cannot directly connect with any Mongo tool or driver to the Mongo API.

   The alternatives are as follows:

   • Disabling TLS option is specifically for local environments that are not dealing with sensitive data. To disable TLS, you must invoke the following command before starting ORDS:

     ords config set mongo.tls false
     ords serve

     Note:

     Mongo API connect string changes to reflect that mongo.tls is not enabled. For example: ...ssl=false....

   • Use the mongo tools and drivers to explicitly disable the requirement for TLS to require a valid signed certificate.

     The settings change depending on the tools and the APIs. For example, the mongosh has a ar--tlsAllowInvalidCertificates command line argument, whereas mongoimport has --tlsInsecure command line argument.

     See Also:

     Support for MongoDB APIs, Operations, and Data Types — Reference

   • Configure the properties standalone.https.cert and standalone.https.cert.key to aquire a valid signed cerfificate.

   Example using mongosh without a valid signed certificate:

    mongosh  --tlsAllowInvalidCertificates 'mongodb://foo:<Password>@localhost:27017/foo?authMechanism=PLAIN&authSource=$external&tls=
   true&retryWrites=false&loadBalanced=true'foo> db.createCollection('emp');
       { ok: 1 }
       foo> db.emp.insertOne({"name":"Blake","job": "Intern","salary":30000});
       ...
       foo> db.emp.insertOne({"name":"Smith","job": "Programmer","salary": 60000,"email" : "smith@oracle.com"});
       ...
       foo> db.emp.insertOne({"name":"Miller","job": "Programmer","salary": 70000});
       ...
       foo> db.emp.find({"name":"Miller"});
       [
         {
           _id: ObjectId("6320bfc40dd73b60ef5641b9"),
           name: 'Miller',
           job: 'Programmer',
           salary: 70000
         }
       ]
    
    
       foo> db.emp.updateOne({"name":"Miller"}, {$set: {"email":"miller@oracle.com"}})
       {
         acknowledged: true,
         insertedId: null,
         matchedCount: 1,
         modifiedCount: 1,
         upsertedCount: 0
       }

4. The data inserted from the MongoDB client can be accessed from SQL:

   SQL> select json_serialize(e.data)
        from emp e;
    
   JSON_SERIALIZE(E.DATA)
   --------------------------------------------------------------------------------
   {"_id":"6320bfa30dd73b60ef5641b7","name":"Blake","job":"Intern","salary":30000}
   {"_id":"6320bfb30dd73b60ef5641b8","name":"Smith","job":"Programmer","salary":60000,"email":"smith@oracle.com"}
   {"_id":"6320bfc40dd73b60ef5641b9","name":"Miller","job":"Programmer","salary":70000,"email":"miller@oracle.com"}
    
   SQL> select e.data."name".string() n,
              e.data."job".string() j
        from emp e
        where e.data."email".string() = 'miller@oracle.com';
    
   N                    J
   -------------------- -----------------------
   Miller               Programmer

By default, when you are connecting to the MongoDB API, all database requests are directed to the default connection pool. Optionally, you can route MongoDB API requests to other connection pools using the hostnames file. For example, assume that the database pool named mydb1 has a configuration directory at ords_config/databases/mydb1.

www.example.com
example.com

Then, the following connection strings routes to mydb1 conection pool instead of the default connection pool:

"mongodb://www.example.com:27017/scott?authMechanism=PLAIN&authSource=$external&ssl=true&retryWrites=false&loadBalanced=true"
 
"mongodb://example.com:27017/scott?authMechanism=PLAIN&authSource=$external&ssl=true&retryWrites=false&loadBalanced=true"