DevelopersDeployment GuideGet Help

Set up the DB

Form.io's data model is driven by MongoDB. Deployments to Azure may use MongoDB Atlas or the Azure-native CosmosDB.

Form.io requires a MongoDB-compatible database to run its platform. Refer to the process that matches the anticipate deployment stack:

  • MongoDB Atlas

  • Azure CosmosDB

MongoDB Atlas

Before deployment, create an account at MongoDB.com/atlas. Follow the steps provided by MongoDB to create the cluster while observing the guidelines described below.

Performance

When configuring the performance of the cluster, it may be necessary to review the advanced settings. The particular settings selected may depend on the planned deployment. The following baseline standard may be used when determining the application's needs:

  1. For production environments, the dedicated tier may be required.

  2. Consider enabling multi-region replication to create additional instances for greater availability.

  3. Choose a sufficient cluster tier based on the expected usage. M10 is typically sufficient for development. M20 is the recommended baseline for production.

Security

When configuring the security settings in MongoDB Atlas after clicking Create Cluster, refer to the following guidelines:

  1. Record the username and password for use in the connection string later.

  2. Ensure the IP address of the Azure VM is added to the whitelist.

If the deployment requires additional security that would mandate a private endpoint, refer to the MongoDB Documentation regarding connecting cloud services to a private endpoint.

Connection String

From the MongoDB Atlas Project Overview, open the Connect Menu and generate a legacy (standard) connection string. It will appear similar to the following:

mongodb://formio:<db_password>@<node1>,<node2>,<node3>/<dbName>?replicaSet=<replicaSetName>&ssl=true&authSource=admin&retryWrites=true&w=majority&appName=<appName>

Note the following placeholders:

  • <node1>... : These will correspond to the individual instances of the DB.

  • <replicaSetName>: The atlas-generated replica set name.

  • <appName>: Typically formio.

  • <dbName>: Typically formio (added by us).

Supplying the required info creates a connection string similar to the following, using the example password badPassword:

mongodb://formio:[email protected]:27017,formio-shard-00-01.qa5hm.mongodb.net:27017,formio-shard-00-02.qa5hm.mongodb.net:27017/formio?replicaSet=atlas-6fxuzs-shard-0&ssl=true&authSource=admin&retryWrites=true&w=majority&appName=formio

Note that the database name formio is added so that the Form.io deployment will initialize with this database instead of the default test database. Also observe that ?ssl=true indicates a database connection over SSL, &retryWrites=true indicates retryWrites is supported, and uses the admin database rather than IAM to authenticate.

Record this connection string for later.

Cosmos DB

Before continuing please review the Cosmos DB for MongoDB (vCore) compatibility doc.

Follow these instructions to setup a new database.

  1. Go to Cosmos DB in your Azure portal

  2. Create an Azure Cosmos DB for MongoDB (vCore)

We recommend (as does Azure) using a vCore-based DB since it has more comprehensive support for native MongoDB features and certain Form.io functionality may be impaired if using an RU-based DB. Here is documentation regarding migrating from RU to vCore.

  1. Once the DB is created, copy the connection string for use in your Form.io deployment. 

    mongodb+srv://formiodbusername:<password>@formio-cosmos-db.global.mongocluster.cosmos.azure.com/<db_name>?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=true&maxIdleTimeMS=120000

  2. After copying it, you'll need to add your Form.io database name (<db_name> above) and the password. This name (formio for example) is placed in-between formio-cosmos-db.global.mongocluster.cosmos.azure.com/ and ?tls=true. The filled-in connection string should look like this:

    mongodb+srv://formiodbusername:supersecretpassword@formio-cosmos-db.global.mongocluster.cosmos.azure.com/formio?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=true&maxIdleTimeMS=120000
Click here for RU-based documentation

Before continuing please review the feature matrix and compatibility docs below.

Currently, Form.io supports the latest version of Cosmos DB for Mongo DB (RU), which at the time of writing is 7.0.

If you run into any issues as it relates version compatibility please consult the Related Content section of the Azure Documentation (or here for version 7.0) as well as this doc regarding how to Upgrade the API version of your Azure Cosmos DB for MongoDB account.

If you an incompatibility is found, please provide details by contacting [email protected].

When creating the DB, ensure that you don't limit the total RU throughput that can be provisioned.

As with the vCore connection string, you'll need to provide a Form.io database name (i.e. formio), which is placed in-between formio-developer-cosmos-db.mongo.cosmos.azure.com:10255/ and ?ssl=true.

mongodb://formio-developer-cosmos-db:[PASSWORD]@formio-developer-cosmos-db.mongo.cosmos.azure.com:10255/formio?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@formio-developer-cosmos-db@

Cosmos DB for MongoDB (RU) Notes

Partial Support for $lookup

Cosmos DB supports basic $lookup operations for equality matches but does not support advanced features like uncorrelated subqueries. For complex join operations, consider restructuring your data model or using alternative methods.

The $lookup aggregation does not yet support the uncorrelated subqueries feature that's introduced in server version 3.6. If you attempt to use the $lookup operator with the let and pipeline fields, an error message that indicates that let is not supported appears. This still applies in version 7.0.

In order to do a sort on a property in version 3.6, there must be an index set. This is different from how MongoDB works as MongoDB allows sorting on any property regardless of an index being set.

To resolve this, a wildcard index can be added to the following collections:

db.submissions.createIndex( {"$**": 1 } );
db.forms.createIndex( {"$**": 1 } );
db.projects.createIndex( {"$**": 1 } );
db.actions.createIndex( {"$**": 1 } );
db.roles.createIndex( {"$**": 1 } );
db.tags.createIndex( {"$**": 1 } );

To do a sort on multiple properties, you must create a compound index. While wildcard indexes are a good starting place to enable sorting, documents with many fields may have a high Request Unit (RU) charge for writes and updates. Therefore, if you have a write-heavy workload, you should opt to individually index paths as opposed to using wildcard indexes.

Cosmos Feature Support Matrix

Refer to the primary Microsoft documentation for a complete list of Database Commands.

Feature
Context
3.6
4.2
5.0
6.0
7.0

find

Query and Write Operation

Yes

Yes

Yes

Yes

Yes

insert

Query and Write Operation

Yes

Yes

Yes

Yes

Yes

update

Query and Write Operation

Yes

Yes

Yes

Yes

Yes

delete

Query and Write Operation

Yes

Yes

Yes

Yes

Yes

aggregate

Aggregation Command

Yes

Yes

Yes

Yes

Yes

count

Aggregation Command

Yes

Yes

Yes

Yes

Yes

addFields

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

count

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

group

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

limit

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

lookup

Aggregation Stage

Partial

Partial

Partial

Partial

Partial

match

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

project

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

skip

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

sort

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

unwind

Aggregation Stage

Yes

Yes

Yes

Yes

Yes

and

Boolean Expression

Yes

Yes

Yes

Yes

Yes

or

Boolean Expression

Yes

Yes

Yes

Yes

Yes

setIntersection

Set Expression

Yes

Yes

Yes

Yes

Yes

eq

Comparison Expression

Yes

Yes

Yes

Yes

Yes

gt

Comparison Expression

Yes

Yes

Yes

Yes

Yes

gte

Comparison Expression

Yes

Yes

Yes

Yes

Yes

lt

Comparison Expression

Yes

Yes

Yes

Yes

Yes

lte

Comparison Expression

Yes

Yes

Yes

Yes

Yes

ne

Comparison Expression

Yes

Yes

Yes

Yes

Yes

in

Comparison Expression

Yes

Yes

Yes

Yes

Yes

nin

Comparison Expression

Yes

Yes

Yes

Yes

Yes

concatArrays

Array Expression

Yes

Yes

Yes

Yes

Yes

filter

Array Expression

Yes

Yes

Yes

Yes

Yes

reduce

Array Expression

Yes

Yes

Yes

Yes

Yes

size

Array Expression

Yes

Yes

Yes

Yes

Yes

in

Array Expression

Yes

Yes

Yes

Yes

Yes

sum

Accumulator Expression

Yes

Yes

Yes

Yes

Yes

push

Accumulator Expression

Yes

Yes

Yes

Yes

Yes

addToSet

Accumulator Expression

Yes

Yes

Yes

Yes

Yes

String

Type

Yes

Yes

Yes

Yes

Yes

Object

Type

Yes

Yes

Yes

Yes

Yes

Array

Type

Yes

Yes

Yes

Yes

Yes

ObjectId

Type

Yes

Yes

Yes

Yes

Yes

Boolean

Type

Yes

Yes

Yes

Yes

Yes

and

Logical Operator

Yes

Yes

Yes

Yes

Yes

or

Logical Operator

Yes

Yes

Yes

Yes

Yes

exists

Element Operator

Yes

Yes

Yes

Yes

Yes

regex

Evaluation Query Operator

Yes

Yes

Yes

Yes

Yes

all

Array Operator

Yes

Yes

Yes

Yes

Yes

elemMatch

Array Operator

Yes

Yes

Yes

Yes

Yes

size

Array Operator

Yes

Yes

Yes

Yes

Yes

set

Update Operator

Yes

Yes

Yes

Yes

Yes

rename

Update Operator

Yes

Yes

Yes

Yes

Yes

unset

Update Operator

Yes

Yes

Yes

Yes

Yes

addToSet

Array Update Operator

Yes

Yes

Yes

Yes

Yes

pull

Array Update Operator

Yes

Yes

Yes

Yes

Yes

push

Array Update Operator

Yes

Yes

Yes

Yes

Yes

sort

Update Modifier

Yes

Yes

Yes

Yes

Yes

Single Field Index

Indexes

Yes

Yes

Yes

Yes

Yes

Compound Index

Indexes

Yes

Yes

Yes

Yes

Yes

Multikey Index

Indexes

Yes

Yes

Yes

Yes

Yes

Text Index

Indexes

No

No

No

No

No

2dsphere

Indexes

Yes

Yes

Yes

Yes

Yes

2d Index

Indexes

No

No

No

No

No

Hashed Index

Indexes

No

No

No

No

No

TTL

Index Properties

Yes

Yes

Yes

Yes

Yes

Unique

Index Properties

Yes

Yes

Yes

Yes

Yes

Partial

Index Properties

No

Only unique indexes

Only unique indexes

Only unique indexes

Only unique indexes

Case Insensitive

Index Properties

No

No

No

No

No

Sparse

Index Properties

No

No

No

No

No

Background

Index Properties

Yes

Yes

Yes

Yes

Yes

PreviousAzure Virtual MachineNextGCP Deployment

Last updated

Was this helpful?