> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB Version Upgrade

> You can seamlessly update MongoDB Replicas from version 4.4 to version 8.0. Since it is not possible to go directly from version 4.4 to MongoDB 8.0, you can make a gradual transition between each major version, update secondary and primary nodes sequentially, and manage feature compatibility settings.

<Warning>
  **Very Important**

  MongoDB backup must be taken before performing the operation:

  ```bash theme={null}
  mongodump --host <IP_ADDRESS> --port=25080 --username=<USERNAME> --password=<PASSWORD> --authenticationDatabase=admin --gzip --archive=/<DIRECTORY>/apinizer-backup-v<CURRENT_VERSION>--<DATE>--1.archive
  ```
</Warning>

<Note>
  This example was performed on Ubuntu 22.04.
</Note>

## MongoDB 4.4 to 5.0 Upgrade

### 1) Updating Secondary Nodes from MongoDB 4.4 to 5.0

First, all MongoDB secondary nodes are updated to version 5.0 **one by one**.

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 5.0 repository">
    ```bash theme={null}
    # MongoDB 5.0 key is added
    wget -qO - https://www.mongodb.org/static/pgp/server-5.0.asc | sudo apt-key add -

    # MongoDB 5.0 Repository is added
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 5.0">
    <Warning>
      When installing the update, you must answer the config file update question with **N** to preserve your existing configuration file.
    </Warning>

    ```bash theme={null}
    sudo apt install -y mongodb-org=5.0.6 mongodb-org-server=5.0.6 mongodb-org-shell=5.0.6 mongodb-org-mongos=5.0.6 mongodb-org-tools=5.0.6
    ```
  </Step>
</Steps>

<Warning>
  **Very Important**

  During installation, the system asks whether to rewrite the config file. If the configuration file is accidentally overwritten here, it must be restored to the old setting.

  ```bash theme={null}
  # sudo vi /etc/mongod.conf
  # The old file is as follows by default
  ```

  ```yaml theme={null}
  storage:
    dbPath: /var/lib/mongodb
    wiredTiger:
      engineConfig:
        cacheSizeGB: 2

  systemLog:
    destination: file
    logAppend: true
    path: /var/log/mongodb/mongod.log

  net:
    port: 25080
    bindIp: 0.0.0.0

  replication:
    replSetName: apinizer-replicaset

  security:
    authorization: enabled
    keyFile: /etc/mongodb/keys/mongo-key

  setParameter:
    transactionLifetimeLimitSeconds: 300

  processManagement:
    timeZoneInfo: /usr/share/zoneinfo
  ```
</Warning>

<Steps>
  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Replica set status is checked by connecting to any node:

    ```bash theme={null}
    mongo mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set Status is Checked
    rs.status()
    ```
  </Step>
</Steps>

### 2) Stepping Down a Node in Primary Role to Secondary Role

Connect to the primary node and step down the primary node's role to secondary to allow a new primary node to be selected.

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongo mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
    ```
  </Step>

  <Step title="Step down Primary Node to Secondary Node">
    ```bash theme={null}
    # Primary Node is stepped down to Secondary Node
    rs.stepDown()
    ```
  </Step>

  <Step title="Check new Primary Node">
    After waiting a bit, it is checked that one of the Secondary Nodes has become Primary Node:

    ```bash theme={null}
    rs.status()
    ```
  </Step>
</Steps>

### 3) Updating Node That Left Primary Role from MongoDB 4.4 to 5.0

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 5.0 repository">
    ```bash theme={null}
    # Add MongoDB 5.0 key and update repository
    wget -qO - https://www.mongodb.org/static/pgp/server-5.0.asc | sudo apt-key add -
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 5.0">
    <Warning>
      When installing the update, you must answer the config file update question with **N** to preserve your existing configuration file.
    </Warning>

    ```bash theme={null}
    sudo apt install -y mongodb-org=5.0.6 mongodb-org-server=5.0.6 mongodb-org-shell=5.0.6 mongodb-org-mongos=5.0.6 mongodb-org-tools=5.0.6
    ```
  </Step>

  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Replica set status is checked by connecting to any node:

    ```bash theme={null}
    mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set status is checked
    rs.status()
    ```
  </Step>
</Steps>

### 4) MongoDB 5.0 Feature Compatibility Check

After all Nodes have transitioned to MongoDB 5.0, before transitioning to MongoDB 6.0, the feature compatibility setting is set to 5.0 **(on Primary Node)**.

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    use admin
    ```
  </Step>

  <Step title="Check feature compatibility">
    If the feature compatibility appears as 4 in the output of the following command, it should be updated to 5:

    ```bash theme={null}
    db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
    ```
  </Step>

  <Step title="Update feature compatibility">
    If the value is not 5.0, you can change it with the following command:

    ```bash theme={null}
    db.adminCommand({ setFeatureCompatibilityVersion: "5.0" })
    ```
  </Step>
</Steps>

## MongoDB 5.0 to 6.0 Upgrade

### 5) Updating Secondary Nodes from MongoDB 5.0 to 6.0

After ensuring all MongoDB replicas have transitioned to version 5.0, you can transition to version 6.0. First, start by updating all secondary nodes **sequentially**.

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 6.0 repository">
    ```bash theme={null}
    # MongoDB 6.0 key is added and repository is updated
    wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 6.0">
    ```bash theme={null}
    # Update is installed
    sudo apt install -y mongodb-org=6.0.0 mongodb-org-server=6.0.0 mongodb-org-shell=6.0.0 mongodb-org-mongos=6.0.0 mongodb-org-tools=6.0.0
    ```
  </Step>

  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Check replica set status by connecting to any node:

    ```bash theme={null}
    mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set status is checked
    rs.status()
    ```
  </Step>
</Steps>

### 6) Stepping Down a Node in Primary Role to Secondary Role

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
    ```
  </Step>

  <Step title="Step down Primary Node to Secondary Node">
    ```bash theme={null}
    # Primary Node is stepped down to Secondary Node
    rs.stepDown()
    ```
  </Step>

  <Step title="Check new Primary Node">
    After waiting a bit, it is checked that one of the upgraded Secondary Nodes has become Primary:

    ```bash theme={null}
    rs.status()
    ```
  </Step>
</Steps>

### 7) Updating Node That Left Primary Role from MongoDB 5.0 to 6.0

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 6.0 repository">
    ```bash theme={null}
    # MongoDB 6.0 key is added and repository is updated
    wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 6.0">
    ```bash theme={null}
    # Update is installed
    sudo apt install -y mongodb-org=6.0.0 mongodb-org-server=6.0.0 mongodb-org-shell=6.0.0 mongodb-org-mongos=6.0.0 mongodb-org-tools=6.0.0
    ```
  </Step>

  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Check replica set status by connecting to any node:

    ```bash theme={null}
    mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set status is checked
    rs.status()
    ```
  </Step>
</Steps>

### 8) MongoDB 6.0 Feature Compatibility Check

After all Nodes have transitioned to MongoDB 6.0, the feature compatibility setting is set to 6.0 **(on Primary Node)**.

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    use admin
    ```
  </Step>

  <Step title="Check feature compatibility">
    If the feature compatibility appears as 5 in the output of the following command, it should be updated to 6:

    ```bash theme={null}
    db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
    ```
  </Step>

  <Step title="Update feature compatibility">
    If the value is not 6.0, you can change it with the following command:

    ```bash theme={null}
    db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
    ```
  </Step>
</Steps>

## MongoDB 6.0 to 7.0 Upgrade

### 9) Updating Secondary Nodes from MongoDB 6.0 to 7.0

After ensuring all MongoDB replicas have transitioned to version 6.0, you can transition to version 7.0. First, start by updating all secondary nodes **sequentially**.

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 7.0 repository">
    ```bash theme={null}
    # MongoDB 7.0 key is added and repository is updated
    wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 7.0">
    ```bash theme={null}
    # Update is installed
    sudo apt install -y mongodb-org=7.0.0 mongodb-org-server=7.0.0 mongodb-org-shell=7.0.0 mongodb-org-mongos=7.0.0 mongodb-org-tools=7.0.0
    ```
  </Step>

  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Check replica set status by connecting to any node:

    ```bash theme={null}
    mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set status is checked
    rs.status()
    ```
  </Step>
</Steps>

### 10) Stepping Down a Node in Primary Role to Secondary Role

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
    ```
  </Step>

  <Step title="Step down Primary Node to Secondary Node">
    ```bash theme={null}
    # Primary Node is stepped down to Secondary Node
    rs.stepDown()
    ```
  </Step>

  <Step title="Check new Primary Node">
    After waiting a bit, it is checked that one of the upgraded Secondary Nodes has become Primary:

    ```bash theme={null}
    rs.status()
    ```
  </Step>
</Steps>

### 11) Updating Node That Left Primary Role from MongoDB 6.0 to 7.0

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 7.0 repository">
    ```bash theme={null}
    # MongoDB 7.0 key is added and repository is updated
    wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 7.0">
    ```bash theme={null}
    # Update is installed
    sudo apt install -y mongodb-org=7.0.0 mongodb-org-server=7.0.0 mongodb-org-shell=7.0.0 mongodb-org-mongos=7.0.0 mongodb-org-tools=7.0.0
    ```
  </Step>

  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Check replica set status by connecting to any node:

    ```bash theme={null}
    mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set status is checked
    rs.status()
    ```
  </Step>
</Steps>

### 12) MongoDB 7.0 Feature Compatibility Check

After all Nodes have transitioned to MongoDB 7.0, the feature compatibility setting is set to 7.0 **(on Primary Node)**.

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    use admin
    ```
  </Step>

  <Step title="Check feature compatibility">
    If the feature compatibility appears as 6 in the output of the following command, it should be updated to 7:

    ```bash theme={null}
    db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
    ```
  </Step>

  <Step title="Update feature compatibility">
    If the value is not 7.0, you can change it with the following command:

    ```bash theme={null}
    db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } )
    ```
  </Step>
</Steps>

## MongoDB 7.0 to 8.0 Upgrade

### 13) Updating Secondary Nodes from MongoDB 7.0 to 8.0

After ensuring all MongoDB replicas have transitioned to version 7.0, you can transition to version 8.0. First, start by updating all secondary nodes **sequentially**.

<Note>
  If you are upgrading on RHEL servers, since the package manager is `dnf` instead of `apt`, the upgrade commands change as follows:

  ```bash theme={null}
  dnf clean all
  dnf makecache

  # To update to the latest version
  dnf upgrade mongodb-org\*
  ```
</Note>

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 8.0 repository">
    ```bash theme={null}
    # MongoDB 8.0 key is added and repository is updated
    wget -qO - https://www.mongodb.org/static/pgp/server-8.0.asc | sudo apt-key add -
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 8.0">
    ```bash theme={null}
    # Update is installed
    sudo apt install -y mongodb-org=8.0.0 mongodb-org-server=8.0.0 mongodb-org-shell=8.0.0 mongodb-org-mongos=8.0.0 mongodb-org-tools=8.0.0
    ```
  </Step>

  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Check replica set status by connecting to any node:

    ```bash theme={null}
    mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set status is checked
    rs.status()
    ```
  </Step>
</Steps>

### 14) Stepping Down a Node in Primary Role to Secondary Role

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
    ```
  </Step>

  <Step title="Step down Primary Node to Secondary Node">
    ```bash theme={null}
    # Primary Node is stepped down to Secondary Node
    rs.stepDown()
    ```
  </Step>

  <Step title="Check new Primary Node">
    After waiting a bit, it is checked that one of the upgraded Secondary Nodes has become Primary:

    ```bash theme={null}
    rs.status()
    ```
  </Step>
</Steps>

### 15) Updating Node That Left Primary Role from MongoDB 7.0 to 8.0

<Steps>
  <Step title="Stop MongoDB service">
    ```bash theme={null}
    sudo apt-mark unhold mongo*
    sudo systemctl stop mongod
    ```
  </Step>

  <Step title="Add MongoDB 8.0 repository">
    ```bash theme={null}
    # MongoDB 8.0 key is added and repository is updated
    wget -qO - https://www.mongodb.org/static/pgp/server-8.0.asc | sudo apt-key add -
    echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

    sudo apt update
    ```
  </Step>

  <Step title="Install MongoDB 8.0">
    ```bash theme={null}
    # Update is installed
    sudo apt install -y mongodb-org=8.0.0 mongodb-org-server=8.0.0 mongodb-org-shell=8.0.0 mongodb-org-mongos=8.0.0 mongodb-org-tools=8.0.0
    ```
  </Step>

  <Step title="Start MongoDB service">
    ```bash theme={null}
    sudo apt-mark hold mongo*
    sudo systemctl start mongod
    sudo systemctl status mongod
    ```
  </Step>

  <Step title="Check replica set status">
    Check replica set status by connecting to any node:

    ```bash theme={null}
    mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    # Replica Set status is checked
    rs.status()
    ```
  </Step>
</Steps>

### 16) MongoDB 8.0 Feature Compatibility Check

After all Nodes have transitioned to MongoDB 8.0, the feature compatibility setting is set to 8.0 **(on Primary Node)**.

<Steps>
  <Step title="Connect to Primary Node">
    ```bash theme={null}
    mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p

    use admin
    ```
  </Step>

  <Step title="Check feature compatibility">
    If the feature compatibility appears as 7 in the output of the following command, it should be updated to 8:

    ```bash theme={null}
    db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
    ```
  </Step>

  <Step title="Update feature compatibility">
    If the value is not 8.0, you can change it with the following command:

    ```bash theme={null}
    db.adminCommand( { setFeatureCompatibilityVersion: "8.0", confirm: true } )
    ```
  </Step>
</Steps>