Skip to main content

​
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.

​
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.

​
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.

​
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.

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.

​
Relationship reference

For each service defined via a relationship to your application, Upsun automatically generates corresponding environment variables within your application container, in the $<RELATIONSHIP-NAME>_<SERVICE-PROPERTY> format. Here is example information available through the service environment variables themselves, or through the PLATFORM_RELATIONSHIPS environment variable.
You can obtain the complete list of available service environment variables in your app container by running upsun ssh env.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 service environment variables directly rather than hard coding any values.

​
Usage example

​
Enterprise edition example

​
1. Configure the service

To define the service, use the mongodb-enterprise type: 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. Define the relationship

To define the relationship, use the following configuration:
You can define SERVICE_NAME as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.The example above leverages default endpoint configuration for relationships. That is, it uses default endpoints behind the scenes, providing a relationship (the network address a service is accessible from) that is identical to the name of that service.Depending on your needs, instead of default endpoint configuration, you can use explicit endpoint configuration.With the above definition, the application container (APP_NAME) now has access to the service via the relationship SERVICE_NAME and its corresponding service environment variables.
For PHP, enable the extension for the service:

​
Example configuration

​
Legacy edition example

​
1. Configure the service

To define the service, use the mongodb type: 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. Define the relationship

To define the relationship, use the following configuration:
You can define SERVICE_NAME as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.The example above leverages default endpoint configuration for relationships. That is, it uses default endpoints behind the scenes, providing a relationship (the network address a service is accessible from) that is identical to the name of that service.Depending on your needs, instead of default endpoint configuration, you can use explicit endpoint configuration.With the above definition, the application container (APP_NAME) now has access to the service via the relationship SERVICE_NAME and its corresponding service environment variables.
For PHP, enable the extension for the service:

​
Example configuration

​
Use in app

To use the configured service in your app, add a configuration file similar to the following to your project. This configuration defines a single application (myapp), whose source code exists in the <PROJECT_ROOT>/myapp directory.
myapp has access to the mongodb service, via a relationship whose name is identical to the service name (as per default endpoint configuration for relationships). From this, myapp can retrieve access credentials to the service through the relationship environment variables.
myapp/.environment
# Set environment variables for individual credentials.
# For more information, please visit https://docs.upsun.com/development/variables.html#service-environment-variables.
export DB_CONNECTION=="${MONGODB_SCHEME}"
export DB_USERNAME="${MONGODB_USERNAME}"
export DB_PASSWORD="${MONGODB_PASSWORD}"
export DB_HOST="${MONGODB_HOST}"
export DB_PORT="${MONGODB_PORT}"
export DB_DATABASE="${MONGODB_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 service environment variables like MONGODB_HOST, 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: 
mongosh <VariableBlock name="MONGODB_HOST" />
With the example value, that would be the following: 
mongosh mongodb.internal
You can obtain the complete list of available service environment variables in your app container by running upsun ssh env. 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 service environment variables directly rather than hard coding any values.

​
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: mongodb
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.
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.
Last modified on March 11, 2026