Appearance

Migrating MongoDB Data (5 -> 8.2) ​

racletteJS stores its data in MongoDB. MongoDB's feature compatibility version (FCV) is not backward compatible across major versions, so you must upgrade in intermediate steps.

Supported Upgrade Path ​

5.0 -> 6.0 -> 7.0 -> 8.0 -> 8.2

Each step updates FCV to the next major version, which unlocks the next upgrade step.

When This Is Required ​

This migration is usually relevant for projects created before March 2026 and typically for racletteJS versions v0.1.21 and below.

If your data volume already contains MongoDB 5 data, you cannot jump directly to MongoDB 8.x without migration.

Local Development vs Production ​

Local Development ​

For local development this migration is usually not required.

If you do not need to keep your local data, you can remove the MongoDB volume and start fresh with MongoDB 8.x:

bash
docker volume rm <projectName>-mongodb-data

WARNING

Deleting the volume removes all stored local MongoDB data.

Production or Long-Lived Environments ​

For production (or any environment where data must be preserved), you should run the migration steps below.

The MongoDB version is defined in your docker-compose.yml (image: mongo:<version>). While you could delete the volume, that would delete your data and is usually not acceptable for production systems.

Before You Start ​

WARNING

Make a full backup of your MongoDB data volume before changing FCV. If something goes wrong, the safe way to recover is restoring from that backup.

TIP

During the migration you should keep your MongoDB volume (data) unchanged. Only update the MongoDB Docker image for the migration step.

Prerequisites ​

  • Docker + Docker Compose
  • mongosh available in the MongoDB container
  • Access to the MongoDB admin commands (db.adminCommand(...))
  • You know which MongoDB database name racletteJS uses in your setup (default: raclette)

Migration Steps ​

You will repeat the following for each target version VER in:

6.0 7.0 8.0 8.2

For each VER:

  1. Update the MongoDB service image in docker-compose.yml

    Replace the image: line for your MongoDB service (for example mongodb:) with:

    yaml
    services:
  mongodb:
    image: mongo:$VER

  2. Recreate the MongoDB container with the new image

    bash
    docker compose up -d --build mongodb

    The service might have a different name in your docker-compose.yml (for example database), so use the correct one.

  3. Open a shell inside the MongoDB container

    bash
    docker exec -ti raclette-mongodb bash

    The container name can differ per deployment. If needed, list containers with docker ps and pick the MongoDB one.

  4. In mongosh, check the current FCV and then set it to the target VER

    bash
    mongosh raclette

    Inside the mongosh prompt:

    javascript
    > db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
// expected: featureCompatibilityVersion: { version: 'x.y' }

> db.adminCommand({
  setFeatureCompatibilityVersion: "<VER>",
  confirm: true,
})

    If you ever run the setFeatureCompatibilityVersion command while still connected to a MongoDB 5.0 server, omit confirm: true (older versions may reject it).

  5. Repeat for the next VER

Verify After the Final Step ​

After the 8.2 step, verify that the FCV is 8.2:

javascript
> db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })

You should see featureCompatibilityVersion: { version: '8.2' }.

Notes ​

Applications built with older racletteJS versions can be started with MongoDB 8.x after updating docker-compose.yml. The compatibility issue is about existing MongoDB 5 data volumes, not about starting a fresh container with no old data.

If you keep a 5 data volume and switch directly to MongoDB 8.x, you risk data loss or startup failure.

racletteJS does not enable MongoDB feature sets that would normally block migration or rollback across these intermediate FCV steps. For additional safety, perform a quick read/write sanity check after each step.