Skip to content
FlagSwiftDocs

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

PostgreSQL ids are UUIDs, and MongoDB uses ObjectIds. The copy converts every id, and every reference to one (organization, project, flag, member, who created or approved something), in the same way, so everything still points at the right record. Sessions issued before the switch carry the old ids, so people sign in again.

Choose a route#

Three ways to end up on MongoDB
RouteDescription
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 importMoves 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 freshPoint 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:

Terminal
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 restart

Before you start#

Checklist
Have readyDescription
A MongoDB databaseEmpty, 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 stringThe one the server uses today (DATABASE_URL). A pooled address is fine, the copy only reads.
The same secretsKeep 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 freezeA 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 folderA terminal in the server's folder with its dependencies installed (npm install), the same one you run the app from.
A backupTake 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

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

Timeline
WhenDescription
Days beforeBack 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 minCreate the production MongoDB database and run npm run db:init-mongo. Run the copy as a dry run.
T zeroFreeze 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 minRun the copy with --yes. Read the check at the end.
SwitchSet DB_TYPE=mongodb and MONGODB_URI on the new server, start it, run the smoke tests.
AfterwardsKeep the old server stopped, and the PostgreSQL database untouched, for as long as you want a way back.

Walk through it#

  1. Point both connection strings at the scripts

    Set the source and the target in the environment of the shell, or in .env in the server folder. The scripts read both, whatever DB_TYPE says.

    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 target
    You 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 uses test.
  2. 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-mongo
    What 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 and Done. on the last line. A second run says up to date for each. If a line says FAILED, see Troubleshooting and run it again.
  3. Rehearse with a dry run

    Without --yes the 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-mongo
    What 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.
  4. 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 -- --yes
    What 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 shows copied N of N, the check prints nothing but Checking…, and the exit code is 0. Any COUNT or ORPHANS line means something did not arrive intact; do not switch over until it is resolved.
  5. Look at the data yourself (optional)

    The script checks counts and references, but a quick look builds confidence. In mongosh or 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 Postgres
  6. Switch 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 used

    Build and start as usual (npm run build, npm start); there is no prisma migrate on MongoDB. Re-enable SCHEDULER_ENABLED if you turned it off, on the new server only.

    You should see. /health/ready answers 200, and the server logs no env.missing lines.
  7. 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.
Options of the copy script
OptionDescription
--yesWrite the data. Without it the script only counts and checks.
--only=a,bCopy just these models, named as in the dry-run output (for example segment,release).
--skip=a,bLeave these models out, for example --skip=exposure,evaluation_metric,ops_metric to move the large analytics tables later or not at all.
--include-rate-limitsAlso copy rate-limit counters.
Options of init-mongo
OptionDescription
(none)Create every collection and bring its indexes in line with the models. An index the models do not declare is dropped.
--dry-runPrint 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 mongodump on a schedule) the way you did for PostgreSQL.
  • Check /health/ready in your load balancer and your monitoring.
  • Open Settings, System and confirm it reports MongoDB as the database.
  • Run npm run db:init-mongo again after upgrades whose notes mention a new or changed index.
  • When you are sure, archive the PostgreSQL database and remove DATABASE_URL and DIRECT_URL from 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.

Questions#

Can I keep using the old server while I copy?
Only for a dry run. Changes made on PostgreSQL after the final copy are not in MongoDB, so stop writes before the copy you intend to keep. You can repeat the copy into a fresh empty database whenever you like to practise.
Can I go from MongoDB to PostgreSQL?
Yes, with the mirror-image script. See Switch from MongoDB to PostgreSQL.
Will my SDKs and API keys keep working?
Yes. Key records, including their hashes, are copied and the secrets do not change, so the same keys evaluate against the new server. Only console sessions are reset.
Can I run the copy again into a database that already has data?
Into the same target, yes: records that already arrived are skipped. Into a database that holds other data, no: the script refuses when a collection holds more records than its table.
Do I need to run init-mongo again later?
On a new database, yes, once. After that, only after an upgrade whose notes mention a changed or new index.