Migrate from MongoDB 3 to MongoDB 8

Overview

Prior to IPLM Cache 2025.4, MongoDB was provided by the iplm-backend-mongodb package. This contains a repackaged version of MongoDB 3.2.20 for use with IPLM. However, this version of MongoDB has not been supported for a long time. With the upgrade of IPLM Cache to Python 3, MongoDB 3.2 can no longer be used, so it is necessary to migrate to a more up to date version of Mongo DB.

PiCache 25.4 and later have been tested against MongoDB 8, so this is the recommended version to use. We no longer provide a pre-packaged version of MongoDB, so it will be necessary to download MongoDB 8 from the Mongo Community site and install that. Instructions on how to do that follow below.

MongoDB 8 requires up to date versions of operating systems, such as Redhat 8+ or Debian 11+, so you may need to also upgrade the operating system, or move IPLM Cache to a new host.

Considerations

  • Two new scripts are included with IPLM Cache 2025.4. These scripts support exporting the existing MongoDB database and then importing the database to the updated MongoDB installation:

    • /usr/share/mdx/products/picache/bin/picache-export.sh

    • /usr/share/mdx/products/picache/bin/picache-import.sh

  • If you need to move IPLM Cache to a new host, you will also need to move the exported database file to the new host. Once you install MongoDB 8 and IPLM Cache you can run the import script on the new machine.

Preparation

Backup the existing database

Back up the database first.

You can use mongodump to backup the database:

Copy 
/usr/share/mdx/mongodb/mongodb-linux-x86_64-3.2.20/bin/mongodump

The migration process can be slow. If you have a large number of log files stored in the database, then it may be worthwhile removing them before starting the process. This can be done by forcing an expiry of old log messages.

Run the following command:

Copy 
/usr/share/mdx/products/picache/bin/picache-db-admin --prune --age 2025-10-01T00:00:00

By default, the cache will remove anything older than 30 days. You may want to reduce your logs to the last day or week. Set the --age parameter to a suitable value.

If you need to move to a new machine due to Operating System requirements, you will need to consider how to move the NFS share. There are many ways of doing this, and what is the best option depends a lot on your specific situation. Therefore, how to do this is not documented here. Contact Perforce support if you need help or advice.

If you have an HA configuration of MongoDB, then please contact Perforce support for details on how best to migrate such an environment.

Step 1: Install MongoDB 8

RHEL/CentOS/Rocky

Configure the package repository

Configure the repository where the packages are downloaded from:

Copy 
[mongodb-org-8.2]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/8.2/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://pgp.mongodb.com/server-8.0.asc

Install MongoDB 8

Run the following command to install MongoDB:

Copy 
sudo yum install mongodb-org

Debian

Configure the package repository

Configure the repository where the packages are downloaded from:

Copy 
sudo apt-get install gnupg curl
curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg \
   --dearmor
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] http://repo.mongodb.org/apt/debian bookworm/mongodb-org/8.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
sudo apt update

Install MongoDB 8

Run the following command to install MongoDB:

Copy 
sudo apt install mongodb-org

More detailed installation instructions can be found here for RHEL/CentOS/Rocky and here for Debian.

Step 2: Shut down IPLM Cache 2025.3 and earlier

Run the following command to stop IPLM Cache:

Copy 
sudo systemctl stop picache

Step 3: Upgrade to IPLM Cache 2025.4

RHEL/CentOS/Rocky

Copy 
sudo yum install iplm-cache

Debian

Copy 
sudo apt install iplm-cache

Step 4: Export MongoDB 3 database

Copy 
sudo /usr/share/mdx/products/picache/bin/picache-export.sh

This will export data from the currently running mdx-backend-mongodb version of the database, and write the data to /var/log/mdx-picache/export. For a large database, this can take a while to run.

By default, the script will read picache.conf to pick up any MongoDB specific configuration. If you have passwords or ports set, this will be read from the configuration file.

If you need to change the default settings, run:

Copy 
sudo /usr/share/mdx/products/picache/bin/picache-export.sh -h

Step 5: Shut down and disable MongoDB 3

Copy 
sudo systemctl stop mdx-backend-mongodb
sudo systemctl disable mdx-backend-mongodb

Step 6: Enable and start MongoDB 8

Copy 
sudo systemctl enable mongod
sudo systemctl start mongod

Step 7: Import MongoDB 3 database to MongoDB 8

Copy 
sudo /usr/share/mdx/products/picache/bin/picache-import

The import assumes that the exported files are in /var/log/mdx-picache/export and that the database is either on the standard port, or that it is configured in /etc/mdx/picache.conf.

If you need to change settings from the default, run:

Copy 
sudo /usr/share/mdx/products/picache/bin/picache-import -h

Step 8 : Start IPLM Cache

Copy 
sudo systemctl start picache
sudo systemctl enable picache

Step 9: Remove MongoDB 3

RHEL/CentOS/Rocky

Copy 
sudo yum remove iplm-backend-mongodb

Debian

Copy 
sudo apt remove iplm-backend-mongodb