Database

How to connect your experiment to a MongoDB Atlas database where data to run your experiment as well as participant data will be held.

How do I connect my app to MongoDB Atlas?

First, create an account on MongoDB Atlas.

Then you should set up a project. A project can contain multiple clusters, which can contain multiple databases, which can contain multiple collections. You can share access to your project with collaborators if you wish.

Clusters

In your project, got to clusters and click on Create a New Cluster. You can select the provider, region, and tier of your cluster. It takes a few minutes for the cluster to become operational.

The sandbox tier allows you to test out a free cluster with a limited storage space. This is perfect for development. However, you want to have more power, space, and guaranties when you deploy your app and start collecting data. Unless you plan on collecting a lot of data, an M10 tier is a good place to start. Please take note of the fees involved in cluster tiers other than sandbox.

Users

In Database Access, click add new database user. You want to create a Read&Write user by creating a user an that has a username, a password, and Read and write to any database privileges.

It is also useful to create an OPLOG user. You can create one the same way as the Read&Write user, with a username and a password, but for the privileges select Grant specific privileges and have the specific privileges be read @ local (leave the Collection blank).

Network Access

In Network Access, click add ip addresses to set the IP addresses that are allowed to access your databases. Technically, someone using your app 'needs to access your databases' (through your app, not directly), so if you want any player to be able to play your game, you should set the IP address to any IP address (whitelist): 0.0.0.0/0

Databases

In your cluster, click collections and then create database where you will set the name of your database and its first collection. The name of the collection isn't very important, because most of the collections of interest will be generated by your Empirica app once it is connected to the database.

Connecting to your app

In your cluster, click connect, then click connect your application. It will open a window where you should select Node.js as the driver. It also presents a URI that you will need to copy to connect your app to your database.

You need the ?retryWrites=true&w=majority part for the resilience of your app.

The important part that this URI provides you is the part between the @ and the <dbname>, it is the connection.

In your settings file, you will have to add this JSON object:

    "galaxy.meteor.com": {
        "env": {
            "MONGO_URL": "mongodb+srv://<read&write username>:<read&write password>@<connection>/<database name>?retryWrites=true&w=majority",
            "MONGO_OPLOG_URL": "mongodb+srv://<oplog username>:<oplog password>@<connection>/local"
        }
    },

Fill in the <> parts with the appropriate elements from when you created the users and the database. The connection is mentioned above.

Now, when you deploy your app with the settings file or when you launch it locally with the settings file, you will be connected to the database. Once you start using your app connected to the database, your should be able to verify that everything worked by refreshing your page on your cluster's database: You will see all the collections relevant to an Empirica app appear (games, players, treatments, etc.).

MongoDB Atlas sent me an email about Query Targeting, should I be worried?

If you regularly receive emails about Query Targeting: Scanned Objects / Returned has gone above 1000, and you haven't been making custom queries to the database, then it is likely NOT a problem. Verify that your data is complete as it should. If it is, then this is probably because the long running query to the oplog does end up reading over 1000 records, but that’s normal, and Atlas does not know it’s a normal behavior that does not impact performance. It should be safe to disable this notification in the Atlas admin.