Switch from PostgreSQL to MongoDB
Create the collections and indexes in MongoDB, copy everything from PostgreSQL, check the result and switch the server over.
- Time
- About 20 min
- Who can do it
- Whoever operates the server
- Where
- A terminal in the server's folder, your two databases and your environment variables
- You finish with
- The same organization running on MongoDB, with the counts checked
What and why#
A FlagSwift server runs on PostgreSQL or MongoDB, chosen with DB_TYPE. Two scripts that ship with the server move an existing PostgreSQL install to MongoDB. db:init-mongo prepares the empty MongoDB database, and db:copy-postgres-to-mongo copies the data. The copy only reads from PostgreSQL, writes only into empty MongoDB collections, and can be run again if it stops part way.
What changes for people
Choose a route#
| Route | Description |
|---|---|
| Copy script (this guide) | Moves everything: people and roles, keys, flags with their history, segments, releases, audit log, metrics and analytics. Needs a short stop in writes. Pick this to keep the installation as it is. |
| Export and import | Moves projects, environments, segments, flags and custom roles only. People, keys, history and metrics stay behind, so you recreate keys and invite people again. Pick this when you only need the configuration. |
| Start fresh | Point a new server at an empty MongoDB, run init-mongo and set it up from scratch. Pick this for a test or when the old data is not worth keeping. |
The short version of the copy route, using the options described below:
npm run db:init-mongo # 1. collections and indexes
npm run db:copy-postgres-to-mongo # 2. dry run: counts and checks only
# stop writes to the old server
npm run db:copy-postgres-to-mongo -- --yes # 3. copy, then it verifies itself
# set DB_TYPE=mongodb and restartBefore you start#
| Have ready | Description |
|---|---|
| A MongoDB database | Empty, writable, with its connection string. Put the database name in the string (…mongodb.net/flagswift). On Atlas, add the IP address you run the scripts from to the cluster's network access list. A replica set is fine; transactions are not needed. |
| The PostgreSQL connection string | The one the server uses today (DATABASE_URL). A pooled address is fine, the copy only reads. |
| The same secrets | Keep JWT_SECRET and API_KEY_ENCRYPTION_KEY exactly as they are, so keys and encrypted values still work. Only DB_TYPE and the connection string change. |
| A short write freeze | A few minutes, sized by how much data you have (see How long it takes). Nobody should change flags on the old server between the last copy and the switch. |
| Node and the server folder | A terminal in the server's folder with its dependencies installed (npm install), the same one you run the app from. |
| A backup | Take a PostgreSQL backup first. The copy does not change it, but a backup is what makes going back painless. |
Passing --yes to an npm script
npm run, put -- before the script's own options: npm run db:copy-postgres-to-mongo -- --yes. Without it, npm keeps --yes for itself, the script never sees it and runs as a dry run again.Plan the cutover#
You can rehearse everything except the last two steps as often as you like, into a scratch MongoDB database, while the old server keeps serving. A real cutover then looks like this.
| When | Description |
|---|---|
| Days before | Back up PostgreSQL. Rehearse the whole copy into a scratch database and note how long it takes. Check the result with the steps below. |
| T minus 10 min | Create the production MongoDB database and run npm run db:init-mongo. Run the copy as a dry run. |
| T zero | Freeze writes: put the old server in read-only use, or stop it. If it keeps running, set SCHEDULER_ENABLED=false and restart it, so scheduled releases and alerts do not fire on it while you copy. |
| T plus 1 to 15 min | Run the copy with --yes. Read the check at the end. |
| Switch | Set DB_TYPE=mongodb and MONGODB_URI on the new server, start it, run the smoke tests. |
| Afterwards | Keep the old server stopped, and the PostgreSQL database untouched, for as long as you want a way back. |
Walk through it#
Point both connection strings at the scripts
Set the source and the target in the environment of the shell, or in
.envin the server folder. The scripts read both, whateverDB_TYPEsays.Environment export DATABASE_URL="postgresql://user:pass@host:5432/flagswift" # PostgreSQL, the source export MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/flagswift" # MongoDB, the targetYou should see. Both are set. The scripts print the MongoDB database name (Syncing on database "flagswift") so you can confirm it is the one you meant. Without a name in the string MongoDB usestest.Create the collections and indexes
Preview first if you like, then apply. This touches only indexes, never documents, and is safe to repeat. The server does not build MongoDB indexes by itself, and a missing unique index lets duplicates in, so this step is not optional.
Terminal npm run db:init-mongo -- --dry-run # lists what would be created or dropped npm run db:init-mongoWhat you should see Syncing on database "flagswift". user users created 2 organization organizations created 2 project projects created 2 … Done.You should see. One line per collection andDone.on the last line. A second run saysup to datefor each. If a line saysFAILED, see Troubleshooting and run it again.Rehearse with a dry run
Without
--yesthe copy writes nothing. It lists how many records each PostgreSQL table holds and how many each MongoDB collection holds, and refuses to go on if MongoDB already holds more records than PostgreSQL in any collection.Terminal npm run db:copy-postgres-to-mongoWhat you should see Dry run: Postgres -> MongoDB database "flagswift" user postgres 4 mongodb 0 organization postgres 2 mongodb 0 project postgres 6 mongodb 0 feature_flag postgres 30 mongodb 0 audit_log postgres 381 mongodb 0 … Dry run. Nothing was written. Run init-mongo.ts first, then add --yes.You should see. The MongoDB column is all zeros. Rate-limit counters do not appear because they are skipped by default.Freeze writes, then copy
Stop the old server or switch off its scheduler as described in the timeline, then run the copy for real.
Terminal npm run db:copy-postgres-to-mongo -- --yesWhat you should see Copying Postgres -> MongoDB database "flagswift" … user copied 4 of 4 organization copied 2 of 2 feature_flag copied 30 of 30 audit_log copied 381 of 381 … Checking... Done. Counts match and every reference resolves. Set DB_TYPE=mongodb and restart; everyone signs in again.Records are read in batches of 1,000, ordered by id, and written without stopping at the first problem. If the run stops (a dropped connection, say), run the same command again. Records that already arrived have the same ids, so they are recognised and skipped (
N already there), never duplicated.You should see. Every collection showscopied N of N, the check prints nothing butChecking…, and the exit code is 0. AnyCOUNTorORPHANSline means something did not arrive intact; do not switch over until it is resolved.Look at the data yourself (optional)
The script checks counts and references, but a quick look builds confidence. In
mongoshor Atlas's Data Explorer:mongosh use flagswift db.organizations.countDocuments() // same as SELECT count(*) FROM organizations db.flags.findOne() // _id is an ObjectId, projectId is a 24-hex string db.flags.countDocuments({ projectId: db.projects.findOne()._id.toString() }) // flags of one project db.apikeys.countDocuments({ revokedAt: null }) // active keys, compare with PostgresSwitch the server over
On the server that will run on MongoDB, change only these two settings. Leave every other variable as it is.
Environment DB_TYPE=mongodb MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/flagswift # DATABASE_URL and DIRECT_URL are no longer usedBuild and start as usual (
npm run build,npm start); there is noprisma migrateon MongoDB. Re-enableSCHEDULER_ENABLEDif you turned it off, on the new server only.You should see./health/readyanswers 200, and the server logs noenv.missinglines.Smoke test
- Sign in. You are asked for your password again, because tokens issued before the switch carry the old ids.
- Open Feature flags, Segments, API Keys, Audit logs and Releases and compare what you see with the old console.
- Evaluate with a key you already use, for example
curl -H "Authorization: Bearer fs_server_…" "$APP_URL/api/v1/evaluation/server?mode=config". Keys keep working because their hashes were copied and the secrets did not change. - Toggle a non-critical flag in a test environment and watch an SDK or the stream pick it up.
- Create a segment, then edit it: that exercises the unique indexes.
What the copy does#
- Ids. PostgreSQL uses UUIDs and the MongoDB side only accepts ObjectIds. Each UUID becomes a 24-character id derived from it, and every field that refers to another record (organization, project, flag, user, custom role, who created, invited, requested, reviewed or revoked something, the resource of an audit entry,
custom:<id>roles) is converted the same way. Values that are not UUIDs, such as an email in a created-by field or a request trace id, are left as they are. - Everything else is carried over unchanged. Dates, numbers, flag configuration, rules and variants, release steps, audit details and history keep their values.
- Never destructive. PostgreSQL is only read. MongoDB is only written to, and only into collections that do not already hold more records than their PostgreSQL table.
- Verified. At the end it compares the record count of every collection with its table, and confirms that every organization, project, flag, user and custom-role id used by another record exists.
- Rate-limit counters are short-lived and rebuild themselves, so they are skipped unless you ask for them.
| Option | Description |
|---|---|
| --yes | Write the data. Without it the script only counts and checks. |
| --only=a,b | Copy just these models, named as in the dry-run output (for example segment,release). |
| --skip=a,b | Leave these models out, for example --skip=exposure,evaluation_metric,ops_metric to move the large analytics tables later or not at all. |
| --include-rate-limits | Also copy rate-limit counters. |
| Option | Description |
|---|---|
| (none) | Create every collection and bring its indexes in line with the models. An index the models do not declare is dropped. |
| --dry-run | Print what would be created or dropped, and change nothing. |
How long it takes#
The time is roughly proportional to the rows, and most of them are history and analytics: the audit log, flag history, evaluation metrics and exposures. A few thousand rows take seconds. Tables with millions of rows are written in the same batches and take minutes. For a very large database, run a rehearsal first to time it, or copy in two passes: everything except the large analytics tables during the freeze, then the analytics tables afterwards with --only= (they are only used for reports).
Going back#
PostgreSQL is untouched, so going back is a configuration change: set DB_TYPE=postgres with DATABASE_URL and restart the old server. What you lose is only what was changed on MongoDB after the switch. To move those changes back, use the organization export and import for the configuration; history and audit entries made on MongoDB cannot be copied backwards. Keep the old server stopped, and its database as it was, until you are sure.
After the switch#
- Set up MongoDB backups (Atlas snapshots, or
mongodumpon a schedule) the way you did for PostgreSQL. - Check
/health/readyin your load balancer and your monitoring. - Open Settings, System and confirm it reports MongoDB as the database.
- Run
npm run db:init-mongoagain after upgrades whose notes mention a new or changed index. - When you are sure, archive the PostgreSQL database and remove
DATABASE_URLandDIRECT_URLfrom the server's settings.
If something goes wrong#
The copy printed a dry run again after I added --yes
Why: npm took --yes for itself.
Fix: Write npm run db:copy-postgres-to-mongo -- --yes, with the extra --. Or run npx tsx scripts/copy-postgres-to-mongo.ts --yes.
Could not connect to any servers in your MongoDB Atlas cluster
Why: Atlas only accepts connections from addresses on its network access list.
Fix: Add the IP address of the machine running the script to the list (or your office or VPN range), wait a minute and run it again.
init-mongo shows FAILED: SSL routines … alert internal error for one or two collections
Why: A dropped TLS connection to the cluster partway through, usually a network blip or a cluster that is scaling or restarting. The other collections finished.
Fix: Run npm run db:init-mongo again. It is safe to repeat and only does what is still missing. If it keeps failing, check the cluster status in Atlas and your network or VPN.
The data went into a database called test
Why: The connection string has no database name, and MongoDB then uses test.
Fix: Add the name to the string (…mongodb.net/fs-enterprise) or set MONGODB_DB=fs-enterprise, then run init-mongo and the copy again. The collections left in test are not used by the server and can be dropped in Atlas once you are happy.
Set DATABASE_URL (source) and MONGODB_URI (target)
Why: One of the two connection strings is not in the environment the script runs in.
Fix: Export both, or put them in .env in the server folder. DB_TYPE is not needed by the scripts.
MongoDB has more records than Postgres in …
Why: The target database already has data, so it is not the empty one the script expects, or it is the wrong database.
Fix: Check the database name in the connection string. Use a new empty database for the copy.
ORPHANS audit_log.projectId: 1 of N values point at a missing project
Why: A project was deleted in PostgreSQL. The audit log has no foreign key, so its older entries still name the deleted project. The copy brought them over as they were.
Fix: Nothing to fix. Newer copies of the script report this as a note when every record of the target arrived (the counts match). If you are on an older copy, the data is complete: update the script, or ignore that line.
A unique index could not be built because of duplicates
Why: Existing documents break a unique rule such as one segment key per organization.
Fix: Fix the duplicate named in the message, then run init-mongo again.