Connecting to MongoDB

Description

Alpha Anywhere can connect directly to MongoDB. Creating a MongoDB connection string makes allows you to build Grid an UX Components against the NoSQL data source.

Discussion

Alpha Anywhere has an API for working directly with a Mongo database. This API is useful if you want to write your own server side code to query and update a Mongo database. However, if you want to use a Mongo database as the data source for a Grid, or UX component, you cannot use the API.

In order to use Mongo as the data source for a Grid or UX, it is necessary to impose a schema on the Mongo database, much like any SQL table has a schema.

Alpha Anywhere allows you to define a connection string to a Mongo database (much like you would define a connection string to any SQL database). Once you have defined a connection string, you can build Grid and UX components against the Mongo database in exactly the same way that you would build a Grid or UX against any SQL database. You can also use AlphaDAO in Xbasic to perform CRUD operations against the Mongo database.

When you define a connection string to a Mongo database, you define a schema for each table (i.e. collection) in the database. This schema defines the fields and data type of each field in each table.

When you define a connection string to a Mongo database, you define:

• URL of the Mongo service.
• Username and password, if required. If the Mongo service is launched with the -noauth parameter, the username and password are not required.
• Name of the Mongo database. This can either be an existing database or the name of a new Mongo database to create.
• The Certificate for the Mongo database. Set to "none" if no certificate is required.
• Manifest filename. This is the file where the database schema is defined; it is a JSON file.

The image below shows the connection string builder for a Mongo database.

Alpha Anywhere has a number of helper function that help you define the schema for the Mongo database.

• If you have an existing Mongo database, Alpha can infer a schema by examining existing data in the Mongo database. You can then tweak the schema that Alpha Anywhere suggests.
• You can start with a sample schema that shows the format required for the schema.
• You can build a schema from the schema of a SQL database. You give Alpha Anywhere a connection string to a SQL database and then select the list of tables you want in your Mongo schema. Alpha Anywhere will automatically create the schema for you. When you use this option, you also have the option of exporting data from the SQL database to your Mongo database.

Structure of the Schema JSON File

A sample schema JSON file is shown below. The JSON file defines two objects, 'schema' and 'collection', and an optional property, 'sourceconnection'.

The 'collection' object contains a property for each collection in the Mongo database and the name of the corresponding schema in the 'schema' object.

For example, the entry in the 'schema' object shown below specifies two schemas: one called 'Categories' and another called 'Employees'. For each schema, the primary key column is specified, and the list of columns and their corresponding data type are identified.

The optional 'sourceconnection' identifies if the schema was obtained from looking at the schema in some other SQL database. If so, the 'sourceconnection' property is the connection string to that database.

{
    "schema": {
        "Categories": {
            "primary": [
                "_id"
            ],
            "columns": {
                "_id": "String",
                "CategoryID": "Number",
                "CategoryName": "String",
                "Description": "String",
                "Picture": "String"
            }
        }
        "Employees": {
            "primary": [
                "_id"
            ],
            "columns": {
                "_id": "String",
                "EmployeeID": "Number",
                "LastName": "String",
                "FirstName": "String",
            }
        }
    },
    "collection": {
        "Categories": {
            "schema": "Categories"
        },
        "Employees": {
            "schema": "Employees"
        }
    },
    "sourceconnection": "::Name::AADemo-Northwind"
}

Creating the Schema

To define the Mongo database schema, click the More... button in the connection string builder.

This will open an intermediate dialog:

Next, click the Edit/create Schema definition... hyperlink. This opens a dialog when you can edit the schema definition.

At the bottom of the dialog you will see several hyperlinks:

Insert sample...

This inserts a sample schema definition. You can edit this definition. You would typically use this option if you are creating a new schema for a Mongo database that does not yet have any data in it.

Guess From Content...

This examines the data in an existing Mongo database and tries to infer the schema from the data. See below for more information.

Copy Schema from Connection...

This lets you to create a schema based on the schema of a SQL database. When you click this hyperlink, you will be prompted for the connection string to the SQL database with the schema you want to copy. You will then be able to select which tables in the SQL database you want to copy. NOTE: If you choose this option, the schema that is created will contain the optional 'sourceconnection' property (discussed above).

Export data from SQL database to Mongo

This hyperlink will only be present if the schema was created using the Copy Schema from Connection... button and the schema has a 'sourceconnection' property. You can use this button to populate a Mongo database with data from a SQL database.

More on the 'Guess From Content...' Option

When you click the Guess From Content... button, Alpha Anywhere will examine the data in the Mongo database specified at the 'Database' prompt on the connection string builder. This is the dialog that was displayed before you clicked the More... button to get to the dialogs when you define the schema.

Using a MongoDB Connection String

Once you have built the connection string to the MongoDB database, the named connection is used the same way that you use any other AlphaDAO connection string. You can build Grid and UX components against the Mongo database. You can also use Xbasic and AlphaDAO objects to work with the data in the Mongo database.

When you use a connection string that points to a Mongo database, you are essentially using SQL syntax to interact with the Mongo database. Behind the scenes Alpha Anywhere is automatically converting the SQL commands to the appropriate commands that then Mongo API understands.

You can see how Alpha Anywhere makes this translation but turning on the Trace SQL option in the connection string builder (shown below). Once you do this, the trace information will be shown in the Trace window (View > Trace window) in the Alpha Anywhere Development environment or found in the Trace logs on the Application Server.

Here is some sample output from the Trace window showing the SQL statement and how that statement was translated to Mongo commands.

SQL Statement: SELECT FIRST 11 [_id], CustomerID, CompanyName, ContactName, ContactTitle, City, Country FROM Customers ORDER BY ContactTitle, [_id]
Time to prepare URL: 0.001
Time to execute REST call: 0.041
Mongo Commands:
{
    "verb": "GET",
    "collection": "Customers",
    "select": "_id , CustomerID , CompanyName , ContactName , ContactTitle , City , Country",
    "groupby": "",
    "where": {},
    "orderby": "ContactTitle, _id",
    "limit": "TOP 11 "
}

Because Mongo is not a SQL database, there are limitations as to what SQL commands you can send to Mongo. For example, you cannot execute a SQL statement that performs a JOIN since the concept is meaningless to Mongo. You also cannot perform CRUD operations that affect more than a single record. For example, the following SQL statement will update multiple records

UPDATE customers set Status = 'B' where Balance > 100

This will not work if you are connected to a Mongo database if there is more than one record with a Balance that is > 100.

Connecting to MongoDB Atlas

Before you can connect to MongoDB Atlas, you need to configure the server to allow access. This includes the following:

• The IP address of the machine running Alpha Anywhere must be whitelisted
• A Database Access user must be configured to access the MongoDB database

Once you have whitelisted your IP address and created a database user, you are ready to create your connection.

The MongoDB Connection Dialog

For the connection, you will need the URL for accessing your MongoDB Atlas database and your Database User credentials. You will also need to specify the database to connect to and configure the Certificate to ensure connection success. Each setting is described below.

URL

The URL to access the MongoDB Atlas database. For example:

mongodb+srv://cluster0.6hygf.mongodb.net

If you need to include parameters in the URL, include a database name. For example:

mongodb+srv://cluster0.6hygf.mongodb.net/myFirstDatabase?retryWrites=true&w=majority

Note that the URL includes a database name. This database does not need to exist. You can change the database later with the Database setting below.

The URL can also include your username and password credentials rather than specifying in the Username and Password properties below.

Username

The MongoDB Atlas Database User name. See https://docs.atlas.mongodb.com/security-add-mongodb-users/

Password

The password for your MongoDB Atlas Database User.

Database

The name of the MongoDB Database to connect to. This can be different from the database specified in the URL.

Certificate

To connect to MongoDB Atlas, set the Certificate to "none".

Manifest

After you have verified your credentials are correct, generate the schema for the database. The schema is required to perform SQL query operations against MongoDB. Use the Guess from content option in the Edit/create Schema dialog to generate a schema for the MongoDB Atlas database.

Click the Test Database button to verify that your credentials are correct. You will receive a Connection Success message stating "MongoDB connection test results returned". If you get a Connection Failed message, double check that your URL, database user credentials, and certificate are correct. Also make sure your IP address is properly whitelisted.

Connection Succeeded

Troubleshooting

The common error messages returned when doing a Test Connection for MongoDB and possible causes are described below.

• Authorization failure - Incorrect Username or Password

  The username or password is incorrect or not specified. Make sure your database username and password are correct.

• Make sure that the MongoDB service is running

  A connection could not be established to the MongoDB database. This may be for one of the following reasons:

  • The server cannot be reached, either because the server is offline or you have no internet connection. Check your connectivity.
  • The MongoDB service is not running. Make sure it is running.
  • The URL is incorrect. Make sure you are using the correct URL. This error can occur if you are using the wrong protocol. For example, using mongodb:// when mongodb+svr:// is required.
  • Your user credentials do not have permissions to access the specified database. Make sure your database user is configured to access the desired database.
  • Your are trying to connect from an IP address that has not been whitelisted. Make sure your IP address is whitelisted on the MongoDB server.
  • The Certificate is not configured. Make sure the Certificate has been configured. If your MongoDB database does not require a certificate, set to "none".

• Base URL is not defined

  The URL is not set. Specify the URL for connecting to your MongoDB database in the URL property.

• Database not defined

  The Database is not set. Specify the name of the database to connect to in the Database property.

Videos

Working with MongoDB using AlphaDAO

Alpha Anywhere allows you to connect to a vast array of SQL databases and then build Grid and UX components against the SQL data. You can also use Xbasic (specifically the AlphaDAO object) to write code that executes SQL commands.

You can work with a Mongo database in the same way.

In this video we show how you can create an AlphaDAO connection string that points to a Mongo instance - how you can export data from a SQL database to a Mongo database - and how you can build a Grid component against a Mongo database.

NOTE: These videos show how the Mongo database is accesses using standard AlphaDAO objects. Alpha Anywhere also provides an API to access Mongo directly.

• Watch Video

See Also

• MongoDB API