Common

Database (MongoDB)

Where your database lives

Emergent apps use MongoDB to store your data. The basics:

  • Your database lives on a shared cluster managed by Emergent: you don't need to provision or configure anything.
  • If you need isolation, you can opt for a Dedicated Database (a paid upgrade).
  • To check and validate your data, use the Database Viewer tool.

Info

MongoDB runs on Emergent's managed cloud by default. You can also bring your own database (MongoDB Atlas, self-hosted, etc.): see Migrating to your own database below.


Preview vs Production database

Separate databases - data does not auto-sync

Preview (the workspace) and Production (the published app at yourapp.emergent.host) use separate MongoDB databases. Changes you make in preview - new collections, documents, schema updates - do not automatically flow to production.

This is a common gotcha: you might add test data in preview, then publish and wonder where it went. On first publish, Emergent migrates your preview data to the production Atlas instance. After that, the two databases are managed independently.

For more context on the preview/production split, see Preview vs Published.


Database behavior on re-publish vs replace

When you push a new published app, Emergent offers two options:

Re-publish

Updates code and dependencies but keeps the existing production database unchanged. Use this for most updates.

Replace

Performs a blue-green swap across two jobs: a new job is forked, traffic switches over to it, and the old job is then torn down. You choose whether to:

  • Keep the existing production DB, or
  • Start with a fresh copy of the preview database (useful for schema changes or resetting data).

Tip

If you've made schema changes or want to seed production with preview data, use Replace and select "Copy preview database to production."


Inspecting & exporting your database

Emergent provides two ways to browse and export your data:

Database Manager (web UI)

The built-in Database Manager lets you browse collections and documents in both preview and production databases:

1

Open the Database Manager

Open the Database Manager from inside Emergent (direct URL access to mongoview.emergent.host does not work, it must be launched from within the platform).

2

Select your environment

Choose Preview or Production from the environment switcher in the top bar.

3

Browse collections

Click any collection to view documents. You can filter, sort, and inspect individual records.

Note

The Database Manager allows you to view, edit, and delete live data in production databases. Use caution, edits to production data are immediate and cannot be undone.

Exporting the preview database (mongodump)

You can export your preview database as a .bson dump file using mongodump directly in the workspace VS Code terminal:

1

Open the terminal

In the VS Code workspace, press Ctrl+` (or Cmd+ on Mac) to open the integrated terminal.

2

Run mongodump

Bash
mongodump --uri="$MONGO_URL" --out=./dump

This creates a ./dump folder with .bson files for each collection.

3

Download the dump

Right-click the dump folder in the VS Code file explorer and select Download. The folder will be zipped and saved to your local machine.

Tip

Use mongorestore locally to import the dump into your own MongoDB instance for offline development or backup.


Migrating to your own database

Most apps run successfully on the Emergent-managed database indefinitely: it is included in your subscription and scales automatically. Migrating to your own external MongoDB is optional, available for published apps only, and typically reserved for apps that need:

  • Advanced control over backups, retention policies, or access patterns
  • Production scale with dedicated resources or performance SLAs
  • Compliance with a specific cloud region or provider
  • Data consolidation across multiple services in your own infrastructure
  • Full ownership of the database layer, for example if you plan to take your app outside Emergent

Warning

Migration is a manual runbook. There is no automatic copy, sync, or zero-downtime cutover - you perform each step yourself, then re-publish to switch over. There is also no guaranteed rollback to the managed database afterwards, so test your external database thoroughly and keep a verified export of your data on hand.

1

Export your data

Export your existing data using the methods in Inspecting & exporting your database above. Note that the managed production cluster does not accept direct external connections - use the Database Manager, or contact support at support@emergent.sh for help with a production export.

2

Provision your own MongoDB

Set up a MongoDB instance with your preferred provider (MongoDB Atlas is recommended), reachable from the internet with appropriate network rules. You'll need a connection string in the standard format:

Text
mongodb+srv://username:password@cluster.provider.net/database_name
3

Import your data

Import the export from Step 1 into your new instance using mongorestore or your provider's import tooling. Verify the import is complete before proceeding.

4

Allowlist Emergent's egress IPs

Add Emergent's egress IP addresses to your database's network access list so your app can connect. The current list is at app.emergent.sh/ip-addresses.

5

Update MONGO_URL in your System keys

Go to Preview → Manage → Secrets, find MONGO_URL under System keys, and update its value to your new connection string. Update DB_NAME too if your new database uses a different name.

Note

The platform key is MONGO_URL, not DATABASE_URL or MONGODB_URI. Using the wrong key name will not be auto-detected by the platform.

6

Re-publish your app

Re-publish your app. Re-publishing is free of charge (beyond the monthly tier fee).

After the re-publish completes, your app connects to your external database.

After migration:

  • You are responsible for backups, monitoring, and scaling - the Emergent-managed database scales automatically; your own database does not, so ensure it has sufficient resources and connection limits for your app's workload.
  • Emergent continues to publish, build, and serve your app normally.
  • The Emergent-managed database is no longer actively used by your app.

For help at any step, contact support at support@emergent.sh or use the in-app live chat.


Was this page helpful?

Related pages