Database & data on mobile
Shared fundamentals
Mobile apps built on Emergent use the same MongoDB backend as web apps. The database URL model, storage limits, and core behavior are identical across platforms.
For a complete explanation of how database URLs work, connection strings, storage quotas, and data persistence, see the Database (MongoDB) page.
Key points for mobile:
- Each Emergent app gets its own database on a shared Atlas cluster with a unique connection string (Dedicated Database is a paid upgrade)
- The database is hosted remotely and accessed over HTTPS - your mobile app talks to the same cloud database as the web version
- All CRUD operations, indexes, and collections work identically on iOS, Android, and web
Note
Mobile apps do not bundle a local database. All data lives in the cloud MongoDB instance provisioned for your app. Note that preview and production databases are separate.
Re-publish as an update
When you modify your mobile app's backend, database schema, or business logic and want to push that change to users, you must re-publish the app.
Unlike web apps (which update instantly on the next page load), mobile apps are distributed as signed binaries with fixed bundle IDs. Backend changes (such as database migrations or API endpoint tweaks) ship by re-publishing, no store review is required for those. For changes to the app itself, including JS-only changes, you need to re-publish and generate a new build - Emergent does not support over-the-air (OTA) updates.
Rebuild the mobile app
Trigger a new build in Emergent. The agent will increment the version number and compile fresh iOS/Android binaries.
Submit to the stores
Upload the new build to App Store Connect (iOS) and Google Play Console (Android). Both stores will review the update.
Users receive the update
Once approved, existing users receive the updated app.
Store review applies to app changes
Store review times (hours to days) and user adoption lag (days to weeks) apply to store submissions. Backend-only updates do not require store resubmission.
Database implications: The database itself does not re-publish. The same MongoDB database persists across versions. When you re-publish:
- Existing user data remains intact
- Schema changes (new collections, fields, indexes) take effect immediately on the backend
- Old app versions still in the wild will continue querying the updated database - ensure backward compatibility or force a minimum version
Fork to experiment safely
Instead of changing your live app directly, you can fork it. Think of a fork like a branch: your main app keeps running untouched while you try out a feature, a redesign or a major refactor on a parallel copy.
A fork gives you:
- The same codebase, cloned at the fork point
- The same bundle ID / package name: your app's identity carries over automatically - there is no option to change it during the fork (the agent can change it later if you ask, but see the warning below)
- Independent builds: the fork generates its own build artifacts, separate from the original
- A database decision later, not now: forking doesn't touch your data. If the original app was published, you'll be asked to choose between databases when you publish the fork
When to fork:
- You're testing a major feature or refactor and don't want to touch the app your users have
- You want to experiment on a parallel copy without any risk to the original
How to fork:
Open the + menu in the chat box
In the chat box, click the + button.
Select Fork this chat
Choose Fork this chat. Emergent clones your app into a new forked chat; the original keeps running untouched.
Choose the database when you publish
There is no database option at fork time. When you publish the forked app - if the original app was already published - you'll be asked at that point to choose which database it should use.
Don't fork to launch a second app in the stores
A fork is for experimenting, not for shipping a separate app. Your store listing is tied to your Apple Developer team, and a forked build - even with a changed bundle ID - can conflict with the existing listing. If you want to publish a genuinely separate app to the App Store or Play Store, contact support first to set it up the right way.
What carries over
How your database and user data are affected depends on whether you update (re-publish) or fork.
| Action | Database | User data | Bundle ID | Store listing |
|---|---|---|---|---|
| Re-publish (update) | Same database, schema changes apply | Persists; all users keep their data | Unchanged | Same app, new version number |
| Fork | Unchanged at fork time; you choose which database the fork uses when you publish it (the option appears if the original app was published) | Depends on the database you choose at publish time | Same ID carries over (agent can change it on request) | Same team and listing - do not submit a fork as a new app |
Re-publish:
- Database connection string stays the same
- Existing collections and documents remain
- Schema migrations (new fields, indexes) affect all app versions immediately
- Users who haven't updated yet will query the new schema - plan for backward compatibility
Fork:
- Forking itself doesn't touch any data - the database decision comes later, when you publish the forked app
- If the original app was published, publishing the fork asks you to choose between databases
- Your bundle ID / package name carries over automatically
Tip
If you need to selectively migrate or transform data after a fork, you can export collections and import them as needed. See the Database (MongoDB) page for connection details.
