MongoDB (Database service)

MongoDB is a cross-platform, document-oriented database.

For more information on using MongoDB, see MongoDB’s own documentation.

Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches.

Enterprise edition

Premium Service

MongoDB Enterprise isn’t included in any Upsun plan. You need to add it separately at an additional cost. To add MongoDB Enterprise, contact Sales.

Deprecated versions

The following versions are deprecated. They’re available, but they aren’t receiving security updates from upstream and aren’t guaranteed to work. They’ll be removed in the future, so migrate to one of the supported versions.

Legacy edition

Previous non-Enterprise versions are available in your projects (and are listed below), but they’re at their end of life and are no longer receiving security updates from upstream.

Warning

Downgrades of MongoDB aren’t supported. MongoDB updates its own data files to a new version automatically but can’t downgrade them. If you want to experiment with a later version without committing to it use a preview environment.

Deprecated versions

4.0.3
3.6
3.4
3.2
3.0

Relationship reference

Example information available through the PLATFORM_RELATIONSHIPS environment variable or by running upsun relationships.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the PLATFORM_RELATIONSHIPS environment variable directly rather than hard coding any values.

{
    "username": "main",
    "scheme": "mongodb",
    "service": "mongodb36",
    "ip": "169.254.150.147",
    "hostname": "blbczy5frqpkt2sfkj2w3zk72q.mongodb36.service._.eu-3.upsunapp.com",
    "cluster": "rjify4yjcwxaa-master-7rqtwti",
    "host": "mongodb.internal",
    "rel": "mongodb",
    "query": {
        "is_master": true
    },
    "path": "main",
    "password": null,
    "type": "mongodb:6.0",
    "port": 27017
}

Usage example

Enterprise edition example

1. Configure the service

To define the service, use the mongodb-enterprise type:

.upsun/config.yaml

services:
    # The name of the service container. Must be unique within a project.
    <SERVICE_NAME>:
        type: mongodb-enterprise:<VERSION>

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

2. Add the relationship

To define the relationship, use the mongodb endpoint :

.upsun/config.yaml

applications:
    # The name of the app container. Must be unique within a project.
    <APP_NAME>:
        # Relationships enable access from this app to a given service.
        relationships:
            <RELATIONSHIP_NAME>: "<SERVICE_NAME>:mongodb"

services:
    # The name of the service container. Must be unique within a project.
    <SERVICE_NAME>:
        type: mongodb-enterprise:<VERSION>

You can define <SERVICE_NAME> and <RELATIONSHIP_NAME> as you like, but it’s best if they’re distinct. With this definition, the application container (<APP_NAME>) now has access to the service via the relationship <RELATIONSHIP_NAME>.

For PHP, enable the extension for the service:

.upsun/config.yaml

applications:
    # The name of the app container. Must be unique within a project.
    <APP_NAME>:
        # PHP extensions.
        runtime:
            extensions:
                - mongodb
        # Relationships enable access from this app to a given service.
        relationships:
            <RELATIONSHIP_NAME>: "<SERVICE_NAME>:mongodb"

services:
    # The name of the service container. Must be unique within a project.
    <SERVICE_NAME>:
        type: mongodb-enterprise:<VERSION>

Example Configuration

App and Service configuration

.upsun/config.yaml

applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # Relationships enable access from this app to a given service.
        relationships:
            mongodatabase: "dbmongo:mongodb"

services:
    # The name of the service container. Must be unique within a project.
    dbmongo:
        type: mongodb-enterprise:6.0

Legacy edition example

1. Configure the service

To define the service, use the mongodb type:

.upsun/config.yaml

services:
    # The name of the service container. Must be unique within a project.
    <SERVICE_NAME>:
        type: mongodb:<VERSION>

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

2. Add the relationship

To define the relationship, use the mongodb endpoint :

.upsun/config.yaml

applications:
    # The name of the app container. Must be unique within a project.
    <APP_NAME>:
        # Relationships enable access from this app to a given service.
        relationships:
            <RELATIONSHIP_NAME>: "<SERVICE_NAME>:mongodb"

services:
    # The name of the service container. Must be unique within a project.
    <SERVICE_NAME>:
        type: mongodb:<VERSION>

For PHP, enable the extension for the service:

.upsun/config.yaml

applications:
    # The name of the app container. Must be unique within a project.
    <APP_NAME>:
        # PHP extensions.
        runtime:
            extensions:
                - mongodb
        # Relationships enable access from this app to a given service.
        relationships:
            <RELATIONSHIP_NAME>: "<SERVICE_NAME>:mongodb"

services:
    # The name of the service container. Must be unique within a project.
    <SERVICE_NAME>:
        type: mongodb:<VERSION>

Example Configuration

App and Service configuration

.upsun/config.yaml

applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # Relationships enable access from this app to a given service.
        relationships:
            mongodatabase: "dbmongo:mongodb"

services:
    # The name of the service container. Must be unique within a project.
    dbmongo:
        type: mongodb:3.6

Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

.upsun/config.yaml

applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # The location of the application's code.
        source:
            root: "myapp"
        # Other options...
        
        # Relationships enable an app container's access to a service.
        relationships:
            mongodatabase: "dbmongo:mongodb"
services:
    # The name of the service container. Must be unique within a project.
    dbmongo:
        type: mongodb-enterprise:6.0

This configuration defines a single application myapp, whose source code exists in the directory <PROJECT_ROOT>/myapp, and has been provided access to the service (dbmongo) via the relationship mongodatabase.

From this, myapp can retrieve access credentials to the service through the environment variable PLATFORM_RELATIONSHIPS. That variable is a base64-encoded JSON object, but can be decoded at runtime (using the built-in tool jq) to provide more accessible environment variables to use within the application itself:

myapp/.environment

# Decode the built-in credentials object variable.
export RELATIONSHIPS_JSON=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode)

# Set environment variables for individual credentials.
export DB_CONNECTION=="$(echo $RELATIONSHIPS_JSON | jq -r '.mongodatabase[0].scheme')"
export DB_USERNAME="$(echo $RELATIONSHIPS_JSON | jq -r '.mongodatabase[0].username')"
export DB_PASSWORD="$(echo $RELATIONSHIPS_JSON | jq -r '.mongodatabase[0].password')"
export DB_HOST="$(echo $RELATIONSHIPS_JSON | jq -r '.mongodatabase[0].host')"
export DB_PORT="$(echo $RELATIONSHIPS_JSON | jq -r '.mongodatabase[0].port')"
export DB_DATABASE="$(echo $RELATIONSHIPS_JSON | jq -r '.mongodatabase[0].path')"

# Surface connection string variable for use in app.
export DATABASE_URL="${DB_CONNECTION}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}"

The above file — .environment in the myapp directory — is automatically sourced by Upsun into the runtime environment, so that the variable DATABASE_URL can be used within the application to connect to the service.

Note that DATABASE_URL, and all Upsun-provided environment variables like PLATFORM_RELATIONSHIPS, are environment-dependent. Unlike the build produced for a given commit, they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the upsun ify command to migrate a codebase to Upsun.

Access the service directly

You can access MongoDB from you app container via SSH. Get the host from your relationship. Then run the following command:

mongo HOST

With the example value, that would be the following:

mongo mongodb.internal

Exporting data

The most straightforward way to export data from a MongoDB database is to open an SSH tunnel to it and export the data directly using MongoDB’s tools.

First, open an SSH tunnel with the Upsun CLI:

upsun tunnel:open

That opens an SSH tunnel to all services on your current environment and produce output like the following:

SSH tunnel opened on port 30000 to relationship: database
SSH tunnel opened on port 30001 to relationship: redis

The port may vary in your case. You also need to obtain the user, password, and database name from the relationships array, as above.

Then, connect to that port locally using mongodump (or your favorite MongoDB tools) to export all data in that server:

mongodump --port 30000 -u main -p main --authenticationDatabase main --db main

(If necessary, vary the -u, -p, --authenticationDatabase and --db flags.)

As with any other shell command it can be piped to another command to compress the output or redirect it to a specific file.

For further references, see the official mongodump documentation.

Upgrading

To upgrade to 6.0 from a version earlier than 5.0, you must successively upgrade major releases until you have upgraded to 5.0. For example, if you are running a 4.2 image, you must upgrade first to 4.4 and then upgrade to 5.0 before you can upgrade to 6.0.

For more details on upgrading and how to handle potential application backward compatibility issues, see the MongoDB release notes.

Note

Make sure you first test your migration on a separate branch.

Also, be sure to take a backup of your production environment before you merge this change.

Downgrading isn’t supported. If you want, for whatever reason, to downgrade you should create a mongodump, remove the service, recreate the service, and import your dump.

Bonus

Integrated environments

Supported environments

MongoDB (Database service)

Back to home

On this page

Is this page helpful?

Upsun Beta access

Supported versions

Enterprise edition

Premium Service

Deprecated versions

Legacy edition

Warning

Deprecated versions

Relationship reference

Usage example

Enterprise edition example

1. Configure the service

2. Add the relationship

Example Configuration

App and Service configuration

Legacy edition example

1. Configure the service

2. Add the relationship

Example Configuration

App and Service configuration

Use in app

Access the service directly

Exporting data

Upgrading

Note

Is this page helpful?