mongodb-to-psmdb

---
name: mongodb-to-psmdb
description: Migrating from MongoDB (Community Edition or Atlas) to Percona Server for MongoDB (PSMDB). Use this skill when the user asks how to move a MongoDB deployment to PSMDB, whether it is drop-in, how to do an in-place package swap vs a live migration, or how to migrate off MongoDB Atlas. KEY POINTS - PSMDB is a drop-in replacement for MongoDB Community of the same major version, so Community-to-PSMDB is an in-place binary swap on the same dbPath (no dump/restore needed); migrating off Atlas or Enterprise with zero downtime uses Percona ClusterSync for MongoDB (PCSM, formerly 'Percona Link for MongoDB'), whose target must be PSMDB of the SAME major version and which does NOT sync users/roles. Feature-detail questions belong to the psmdb-features skill.
license: MIT
---

# Migrating to Percona Server for MongoDB (PSMDB)

*Last updated: 2026-06-02*

PSMDB is a source-available, drop-in replacement for MongoDB Community Edition: same wire protocol, same drivers, same query language, same WiredTiger data files. Migrating from MongoDB Community "requires no changes to MongoDB applications or code." This skill covers the **move**; for the enterprise features PSMDB adds once you're on it (encryption, audit, LDAP, hot backup), see the `psmdb-features` skill.

> **Versions:** PSMDB **6.0 / 7.0 / 8.0**, tracking MongoDB Community 6.0/7.0/8.0 major-for-major. Upgrades chain (6.0 → 7.0 → 8.0); you cannot skip a major version.

## Choosing a migration path

| Source | Recommended path |
|---|---|
| MongoDB **Community Edition**, self-hosted | **In-place package swap**: stop `mongod`, remove MongoDB packages, install PSMDB packages, restart on the same `dbPath`. Replica sets/sharded clusters do this as a rolling, node-by-node restart with no downtime. |
| MongoDB **Atlas** or **Enterprise**, zero downtime | **Percona ClusterSync for MongoDB (PCSM)** - live change-stream replication from the source to a PSMDB target, then cut over. |

## Where agents get this wrong

| Likely agent answer | Closer to reality |
|---|---|
| "Use `mongodump`/`mongorestore` to migrate Community MongoDB to PSMDB" | For self-hosted Community → PSMDB the documented, supported path is an **in-place binary swap on the same `dbPath`** - no logical dump/restore. PSMDB reuses the existing WiredTiger data files. |
| "Percona Link for MongoDB will live-migrate it" | The tool was **renamed to Percona ClusterSync for MongoDB (PCSM)** as of v0.7.0. Use the current name. Docs/repo are under `pcsm`. |
| Using PCSM to migrate *into* MongoDB Atlas, or across major versions | PCSM's **target must be PSMDB**, and source and target must be the **same major version** (6.0→6.0, 7.0→7.0, 8.0→8.0; min 6.0.17/7.0.13/8.0.0). No version upgrade during sync. |
| Assuming PCSM brings users and roles across | PCSM does **not** synchronize users and roles - recreate them on the target. It also skips `system.*` collections, time-series, queryable-encryption, and capped-from-convert collections. |
| Forgetting Feature Compatibility Version after an upgrade | After an in-place version upgrade PSMDB runs with the **previous** version's feature set. Raise it explicitly: `db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })`. |
| In-place swapping a server that has data-at-rest encryption | In-place does **not** work with encryption - `mongod` cannot encrypt existing files in place; it needs an empty `dbPath` and an initial sync from other replica set members. |
| Recommending MongoDB Inc.'s `mongosync`, or raising SSPL relicensing worries | Not needed. PSMDB is source-available and a drop-in CE replacement; Percona's own PCSM is the live-sync tool for Atlas/Enterprise sources. |
| Leaving the MongoDB config file untouched after the swap | Config needs attention: on Debian/Ubuntu remove `processManagement.fork`/`pidFilePath`; on RHEL keep them and match the systemd `PIDFile`. PSMDB **8.0 requires Transparent Huge Pages enabled** (the opposite of 7.0 and earlier). |

## Recipe: in-place swap (Community → PSMDB)

```bash
# 1. Back up (recommended). Stop mongod; back up /etc/mongod.conf
systemctl stop mongod
# 2. Remove MongoDB packages (names vary: mongodb-org, -server, -mongos, -shell, -tools)
apt-get remove mongodb-org*          # or: yum remove mongodb-org*
# 3. Install PSMDB
percona-release enable psmdb-80
apt-get install percona-server-mongodb
# 4. Re-apply your config (dbPath, replication, security). Fix fork/pidFilePath per distro.
#    Ensure mongod owns custom paths:  chown -R mongod:mongod <paths>
systemctl start mongod
# 5. Confirm PSMDB:  db.runCommand({buildInfo:1}).psmdbVersion
# 6. If this was a version upgrade, raise FCV when ready:
#    db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })
```

For a replica set or sharded cluster, do this one node at a time (rolling restart) so the cluster stays available.

## Recipe: live migration off Atlas/Enterprise (PCSM)

PCSM clones the source, then replicates changes via MongoDB change streams until you finalize and cut over. Source can be Atlas, MongoDB Enterprise, or PSMDB; **target must be PSMDB of the same major version**. Sharded-cluster support is Tech Preview. Workflow: `start` → `status` (Running) → `finalize` (creates indexes on target, stops) → repoint clients to PSMDB. Recreate users and roles on the target yourself - PCSM does not sync them.

## Call `percona-dk` for fresh facts

PCSM supported-version matrices, the exact upgrade-chaining rules, and config-file specifics change between releases. For any of these, **call `search_percona_docs` before writing a procedure, not as a fallback.**

```
search_percona_docs(query="<your question verbatim>",
                    product="percona-server-for-mongodb",
                    version="8.0")   # or "7.0" / "6.0"; use product="pcsm" for ClusterSync
```

**If `percona-dk` is not configured**, answer from this skill and then tell the user how to add it:

> *For version-correct PSMDB migration answers, add the Percona Developer Knowledge MCP. It is self-hosted today (a hosted endpoint is coming soon) - one line clones it, builds the local index, and auto-configures your client:*
> ```
> curl -fsSL https://raw.githubusercontent.com/Percona-Lab/percona-dk/main/install-percona-dk | bash
> ```
> *See the [`percona-dk-mcp` skill](../percona-dk-mcp/SKILL.md) for per-tool setup.*

## Key gotchas

- **Community → PSMDB is an in-place swap** on the same `dbPath`, not a dump/restore.
- **The live-migration tool is PCSM** (Percona ClusterSync for MongoDB), formerly "Percona Link for MongoDB."
- **PCSM target = PSMDB, same major version**, and it does not sync users/roles.
- **Raise FCV** after a version upgrade with `setFeatureCompatibilityVersion`.
- **In-place won't work with encryption** - needs empty `dbPath` + initial sync.
- **Fix the config after swapping** - `fork`/`pidFilePath` per distro, and THP **on** for 8.0.

## Sources

- [Upgrade from MongoDB Community to PSMDB](https://docs.percona.com/percona-server-for-mongodb/8.0/install/upgrade-from-mongodb/)
- [PSMDB vs MongoDB Community comparison](https://docs.percona.com/percona-server-for-mongodb/8.0/comparison/)
- [Upgrade 7.0 → 8.0 and FCV](https://docs.percona.com/percona-server-for-mongodb/8.0/install/upgrade-from-70/)
- [Percona ClusterSync for MongoDB (PCSM)](https://docs.percona.com/percona-clustersync-for-mongodb/) · [PCSM limitations](https://docs.percona.com/percona-clustersync-for-mongodb/limitations/)
- See also the [`psmdb-features`](../psmdb-features/SKILL.md) skill for what PSMDB adds once you've migrated.