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:
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).
Select your environment
Choose Preview or Production from the environment switcher in the top bar.
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:
Open the terminal
In the VS Code workspace, press Ctrl+` (or Cmd+ on Mac) to open the integrated terminal.
Run mongodump
mongodump --uri="$MONGO_URL" --out=./dumpThis creates a ./dump folder with .bson files for each collection.
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.
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.
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:
mongodb+srv://username:password@cluster.provider.net/database_nameImport 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.
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.
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.
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.

