Upgrading MongoDB for Graylog 7: when the database step comes first
Graylog 7.0 needs at least MongoDB 7.0, and the Graylog compatibility matrix supports MongoDB 7.x up to 8.2.x for Graylog 7.0 to 7.2. If your deployment still runs an older MongoDB, the database step comes before any Graylog package change. Graylog's upgrade guidance is explicit that system dependencies such as MongoDB must reach the version the target Graylog release needs before Graylog itself is upgraded. Teams that treat MongoDB as an afterthought often find the Graylog server refusing to start, with the cluster partly upgraded and inputs backing up behind it.
The Graylog 7.0 upgrade notes also cover the skip_preflight_checks setting, which can bypass the startup check that compares your MongoDB version against the minimum. The notes do not recommend using it. The check exists because a Graylog server that starts against an unsupported database can fail in less visible ways later. Before you change anything, confirm the MongoDB version on every node that holds configuration data, record the current replica set status, and confirm which 8.x release, if any, you intend to target. Ask your MongoDB operator or partner to state the upgrade path from your current version in writing, since the path depends on your starting release and feature compatibility settings.
Plan the database work as its own change with its own backup and rollback point. Take a verified backup of the Graylog configuration database before the first MongoDB step, and confirm that a restore has been tested on a non-production copy. Then decide who signs off that the MongoDB version and the Graylog 7 target match the compatibility matrix on the day you change the Graylog packages. That decision, and the record of the preflight check result, is the evidence most reviewers will ask for later.
Which MongoDB changes affect the Graylog 7 upgrade
This table lists the MongoDB requirements that change how you plan the Graylog 7 upgrade, from the 7.0 minimum to the 8.2.x ceiling. Read each row as a gate: confirm the MongoDB version and the preflight behavior before you touch the Graylog packages.
| Change | Impact | Action needed |
|---|---|---|
| Graylog 7.0 minimum MongoDB version | Graylog 7.0 needs at least MongoDB 7.0, so a cluster still on an older MongoDB release cannot run the new Graylog server. | Confirm the running MongoDB version on every replica set member and step the cluster up to 7.0 before installing Graylog 7. |
| Supported range for Graylog 7.0 to 7.2 | Graylog 7.0 through 7.2 support MongoDB 7.x up to 8.2.x, so a MongoDB 8.x release above 8.2.x is outside the matrix. | Check the Graylog compatibility matrix for your exact target Graylog release and choose a MongoDB version inside that range. |
| skip_preflight_checks setting | This setting bypasses the startup check that compares MongoDB against the Graylog requirement, which hides a mismatch until queries or migrations fail. | Leave the setting unset, fix the version gap instead, and record any exception in your change ticket with a named owner. |
| MongoDB before Graylog order | Graylog documents that system dependencies such as MongoDB must reach the version the target release needs before Graylog is upgraded. | Schedule the MongoDB step first in every change window, and only start Graylog package upgrades after MongoDB is healthy. |
| Replica set members upgraded one at a time | A rolling MongoDB upgrade keeps a primary available, but a failed member left in a mixed state can block the next step. | Upgrade secondaries first, confirm each rejoins and reports healthy, then step down and upgrade the former primary. |
| Backups before the first step | Configuration and metadata live in MongoDB, so a failed upgrade without a verified backup leaves no clean rollback point. | Take and test a restorable backup of every database Graylog uses before the first MongoDB binary changes. |
| Feature compatibility version | Raising the feature compatibility setting after binaries are upgraded can make rollback to the older release impossible. | Hold the feature compatibility change until Graylog runs cleanly on the new release, and confirm the rollback plan covers it. |
What to back up and inventory before touching MongoDB
MongoDB holds Graylog's configuration and metadata, so an upgrade mistake there affects every node at once. The four items below establish a recovery point, a clear picture of the current state and a place to rehearse the steps before production.
Full MongoDB backup before any change
Take a full backup of every database Graylog uses, including the configuration and metadata that define streams, pipelines, users and event definitions. Confirm the backup can be restored by running a test restore, not just by checking that the file exists. Record where it is stored and who can restore it, because a failed upgrade step often needs a restore within the same change window. Graylog's own upgrade notes say system dependencies must be moved to the required version before Graylog itself is upgraded, so this backup is the rollback point for that sequence.
Graylog version on every node
List the exact Graylog version running on each server node, including any node that was taken out of rotation or left stopped after an earlier attempt. Mixed versions across nodes are a common source of confusion when a MongoDB step is applied. Check the Graylog compatibility matrix against the current MongoDB version so you know which target MongoDB release each Graylog version needs. Write the results down in the change record.
MongoDB version on every member
Record the MongoDB version on each member of the replica set, not only on the one that hosts your admin session. Members can drift when someone upgraded one host by hand, and that drift changes the order and the target for each step. Confirm the feature compatibility version as well, since it controls which features the cluster accepts. Compare the results with the 7.x to 8.2.x range Graylog 7.0 to 7.2 requires.
Replica set members and their roles
Capture the output of the replica set status for the cluster, listing each member, its host, whether it is primary or secondary, and its health. This tells you which member to upgrade first and which one will fail over when the primary restarts. Note any arbiter or hidden member, because those change the quorum math during the rolling restart. Keep this list with the backup record so the order of changes can be checked against it.
Staging copy for rehearsal
Build a staging copy of the Graylog and MongoDB setup from the production backup and run every planned step there first. Use the same Graylog version, the same MongoDB starting version and a similar replica set layout. The rehearsal shows which startup checks fail, how long a member takes to rejoin and whether Graylog reconnects cleanly afterward. Staging does not need production hardware, but it does need the same configuration so that the rehearsal tests the real steps.
How to order the MongoDB upgrade across a replica set
The sequence moves a Graylog MongoDB replica set from its current version to a 7.x release that the target Graylog version supports, with a verified rollback point and health check before each change. The result is a cluster that Graylog can start against without skipping the startup preflight check.
Back up the configuration database first
Before any change, the team takes a full backup of the MongoDB data that Graylog uses for configuration and metadata, and stores it outside the cluster. Someone on the team confirms the backup can be read by restoring it to a separate test instance, and records the backup time and the Graylog version in the change record. This backup is the rollback point for the whole sequence. The step is done when a restore test has succeeded and the change record names the backup location.
Confirm current MongoDB and Graylog versions
The operator records the MongoDB version on each replica set member, the replica set name, the current primary, and the Graylog version running on every server node. They then compare these against the compatibility matrix entry for the target Graylog release. Graylog 7.0 requires at least MongoDB 7.0, and the matrix lists the supported range for Graylog 7.0 to 7.2. The step is done when the team has a written version path, including any intermediate MongoDB releases the vendor documentation requires, and has confirmed it against the MongoDB and Graylog documentation for the target release.
Stop Graylog write traffic and check the journal
Before MongoDB changes, the team pauses or drains Graylog's processing so that no configuration writes happen during member restarts. They confirm that inputs are buffering to the message journal and that the journal is not near its limit. The operator should confirm with Graylog's operations guidance how to pause nodes cleanly for the version in use. The step is done when every Graylog node reports its expected state and the journal is holding data rather than backing up.
Upgrade secondary members one at a time
The engineer upgrades one secondary member, restarts it, and lets it rejoin the replica set before touching the next. Each member is upgraded to the intermediate or target 7.x version the path calls for, using the same packaging method as the rest of the cluster. After each restart, the engineer checks that the member reports as a secondary, has caught up on replication, and shows no errors in its log. The step is done when every secondary runs the new version and replication lag has cleared.
Verify replica set health after each member
After every member restart, the operator checks replica set status, election state, oplog window and replication lag from the current primary. The check also confirms that a write made on the primary appears on the upgraded member. If any member fails to rejoin or lag keeps growing, the team stops the sequence and uses the backup or the earlier member state as the rollback point. The step is done when the check passes for each member and the results are logged with the member name and version.
Step down and upgrade the primary
Once all secondaries run the new version, the operator steps the primary down so that an upgraded secondary takes over. The former primary is then upgraded and restarted and rejoins as a secondary. The team checks that a clean election occurred, that the cluster has one primary, and that the replica set status matches the earlier baseline. The step is done when every member runs the same version and the replica set reports healthy with a single primary.
Set compatibility and confirm the MongoDB version
After all members run the target version, the team sets the feature compatibility version as the MongoDB documentation for that release describes, and only after confirming that the Graylog version still needs it. They record the final version of each member and confirm that no member is still on an older release. The step is done when the version record matches the compatibility matrix for the target Graylog release.
Start Graylog and confirm the startup check passes
Only now does the team upgrade Graylog, one node at a time, following the Graylog upgrade documentation for the target release. Each node is started without the skip_preflight_checks setting, which bypasses the startup check and is not recommended in the upgrade notes. The operator watches each node start cleanly, confirms the journal drains, and records the rollback point for the Graylog step separately. The step is done when every Graylog node is running the target version, passes its startup check, and the journal returns to normal levels.
Why skipping preflight checks turns a small fix into an outage
The startup check exists to stop Graylog from running against a MongoDB version it does not support. Graylog 7.0 needs at least MongoDB 7.0, and the compatibility matrix limits Graylog 7.0 to 7.2 to MongoDB 7.x up to 8.2.x. When the Graylog server starts, the preflight check compares the database version it finds against that requirement. If the check fails, the node refuses to proceed, which is the cheapest moment to learn that the MongoDB tier is behind. The skip_preflight_checks setting bypasses that comparison. Teams usually reach for it during an upgrade because a node will not start, so the setting feels like a way to get the service back up quickly.
The problem is that a skipped check does not make the version mismatch go away. It only moves the discovery to later, when Graylog reads or writes configuration, users, streams, pipelines or index metadata through a MongoDB release it was not built to expect. The symptoms can be intermittent or appear only under specific operations, so an upgrade that seemed to succeed can fail days later, on a different node, or during a routine change. Before you touch the setting, confirm the MongoDB version on every member of the replica set, not only the primary, and compare it with the range in the compatibility matrix for your target Graylog release. Then fix the database tier and let the check pass.
The Graylog 7.0 upgrade notes do not recommend skip_preflight_checks, and that guidance is the one to follow. Graylog states that dependencies such as MongoDB must be brought to the version the target release needs before Graylog itself is upgraded, so the setting works against the documented order rather than with it. If a node will not start, treat the failed check as a finding: record the reported version, review the Graylog 7.0 upgrade notes, and ask your vendor or internal platform owner to confirm the rollback path for the database tier before you change anything else.
Testing and rollback for each stage
Each MongoDB step should pass through a staging rehearsal, a Graylog startup and configuration check, a confirmation that inputs keep flowing, and a defined rollback point. The backup taken before the change is what makes every stage reversible, so the checks below treat it as a gate rather than a formality.
Rehearse on a staging copy
Run the full sequence on a staging cluster built from a recent production backup, with the same MongoDB topology, replica set size and Graylog version. Record the exact order of commands, the time each member took to rejoin and any warnings. The rehearsal output becomes the runbook for production, so a step that surprised the team in staging should be written down and fixed before the production window.
Check Graylog startup after each change
After each MongoDB member is upgraded and the replica set reports healthy, confirm that every Graylog node starts without the preflight failure and that the server logs show no complaints about the database version. Do not use skip_preflight_checks to get past a failing check. The upgrade notes do not recommend it, and a bypassed check hides the mismatch until something breaks later.
Confirm Graylog reads its configuration
Log in to the web interface and open streams, inputs, index sets, pipelines and users, since these are all stored in MongoDB. Confirm that counts match the pre-change inventory and that a saved search and a dashboard still load. A node that starts but shows empty or stale configuration points to a connection or replica set problem that must be fixed before moving on.
Verify inputs keep flowing
Watch the message journal and the input states on each Graylog node during and after the change. Send a known test message through a syslog or GELF input and confirm it appears in search within the expected time. Because the journal buffers incoming messages while Graylog is busy, check that it drains after the window closes rather than growing without limit.
Define rollback points from the backup
Name a rollback point before each stage, not only one at the start. Before the first member changes, the backup must be restorable and its restore procedure tested in staging. If a member fails to rejoin or Graylog cannot read its configuration, the team should know whether it can roll back that single member or must restore the whole replica set from the backup, and who has authority to decide.
Hold the next stage until checks pass
Set written exit criteria for each stage, covering replica set health, Graylog startup, configuration counts, input flow and search results. Do not start the next MongoDB member or the Graylog upgrade until every criterion is met and signed off by the person owning the change. Gating each stage this way keeps a single failure from spreading across the whole cluster.
What makes the MongoDB step take longer
This table lists the factors that stretch a MongoDB upgrade for Graylog 7 and what to confirm for each one. Read each row against your own environment before estimating the window, because the same version jump can take very different effort in a small single-node lab and in a three-node replica set serving production.
| Driver | Why it matters | What to confirm |
|---|---|---|
| Replica set size and topology | Each member is upgraded and must rejoin and catch up before the next one, so more members means more sequential steps and more chances to stall. | How many members and arbiters exist, which member is primary, and whether any member is remote or lags behind. |
| Starting MongoDB version distance from 7.0 | Graylog 7.0 needs at least MongoDB 7.0, so an older cluster may need intermediate major steps, each with its own compatibility checks. | The exact current MongoDB version and feature compatibility version on every member, and whether the upgrade path is documented by MongoDB. |
| Graylog nodes that must agree | Graylog server nodes read shared configuration from MongoDB, so mixed Graylog and database states during the window complicate rollback and troubleshooting. | How many Graylog server nodes connect to this cluster, which one is the leader, and whether any node runs a different Graylog version. |
| Data volume to back up and restore | A backup is only useful if restoring it is tested, and restore time grows with the size of configuration and metadata stored in MongoDB. | Database size on disk, backup method, expected restore time measured in a rehearsal, and where backup copies are stored. |
| Number of environments to rehearse | Each environment such as test, staging and production can differ in versions, hardware and data, so a successful rehearsal in one does not prove the others will pass. | Which environments exist, whether they match production topology, and who signs off on each rehearsal result. |
| Packaging and hosting model | Packages, containers and managed services change how binaries are replaced, where data volumes sit and whether the provider controls the upgrade timing. | Whether MongoDB comes from OS packages, container images or a managed service, and which steps the provider performs versus your team. |
| Preflight checks and startup behavior | Graylog runs a startup check against MongoDB, and bypassing it with skip_preflight_checks hides version problems until later. | Whether the check passes on each node before traffic resumes, and who records the result in the change ticket. |
Questions teams ask before upgrading MongoDB for Graylog 7
What does the MongoDB step cost, and who pays for what?
The cost is the effort to plan, rehearse and run the MongoDB upgrade, plus any change to the hosts or managed service it runs on. Internal staff time is always part of it, whether or not a partner is involved. A partner's cost follows from a written scope that covers inventory, the replica set plan, backups, the upgrade runbook, verification and any support after the change. Most of the spend is one-time. Recurring costs appear only if the MongoDB version or hosting changes ongoing operating work. Ask any quote to separate the preflight review, the rehearsal, the production window and the rollback plan, so you can see which parts your team already covers.
How long does upgrading MongoDB for Graylog 7 take?
No duration figure is supplied for this work, and the time depends on your environment. The main drivers are the current MongoDB version and how many major steps separate it from the 7.0 minimum, the number of replica set members, the data volume that must sync between members, how many Graylog nodes depend on the cluster, and whether you have a tested rollback. A single-node lab moves much faster than a three-member production replica set with change windows and sign-off. Ask the partner or your own team to estimate from your inventory, and confirm the estimate against a rehearsal on a copy of production data.
What does the work need from our internal team?
Your team needs to provide access and decisions that only you can make. Expect to supply the current MongoDB and Graylog versions, host and network details, the replica set topology, backup locations, maintenance windows and the people who can approve a rollback. Someone who owns the Graylog cluster must confirm which Graylog release is the target, since that release sets the MongoDB range you must reach. Plan for named staff to be available during the rehearsal and the production window, and make sure they can read MongoDB logs and Graylog startup output.
Can our own team upgrade MongoDB for Graylog 7 without a partner?
Yes, if your team has MongoDB administration skills, a tested backup and restore procedure, and a staging environment that mirrors production. The work is a sequence of documented steps, not a single command. Before you start, confirm the MongoDB versions your Graylog release supports using the Graylog compatibility matrix, then work through the upgrade order for your replica set. Teams without a dedicated database administrator often bring in outside help for the rehearsal and the first production window, then run the remaining work internally.
What happens if the MongoDB upgrade step fails?
The outcome depends on where the failure occurs and whether the plan covered it. Common failures include a member that does not rejoin the replica set, a feature compatibility setting that blocks the next step, or a Graylog node that refuses to start because the database version is below the minimum. Graylog's upgrade notes say that the skip_preflight_checks setting can bypass the startup check, but the notes do not recommend using it. A bypass hides the problem rather than fixing it and can leave Graylog running against an unsupported database. Your recovery path should include a verified backup, a documented restore procedure and a decision point that names who can roll back.
Why should we not skip the preflight checks?
The preflight check exists to stop Graylog from starting against a database version it does not support. Graylog 7.0 requires at least MongoDB 7.0, and the compatibility matrix lists MongoDB 7.x up to 8.2.x for Graylog 7.0 to 7.2. Setting skip_preflight_checks removes that guard, so a mismatch surfaces later as data errors, failed migrations or intermittent faults that are harder to trace. Treat a failing preflight check as a finding to resolve before the change. If a check fails, confirm the cause with the Graylog upgrade notes and the MongoDB release notes, then fix the version or the configuration.
Does Graylog Open licensing affect this upgrade?
The MongoDB step does not depend on the Graylog license, but the broader Graylog project does. Starting with Graylog 4.0, Graylog Open is licensed under the Server Side Public License version 1 (SSPL-1.0), which is not an OSI-approved open source license. This matters when you decide how much you can modify or redistribute Graylog itself, not for the MongoDB version you run. Check the license terms with your legal team before you plan custom builds or changes to Graylog code. Graylog Enterprise and Graylog Security each have their own terms, and their pricing page lists the starting costs.
Reading the compatibility matrix before you choose a target
Choose the target Graylog release first, then find the MongoDB release that its row in the compatibility matrix allows. For Graylog 7.0 to 7.2, the matrix lists MongoDB 7.x up to 8.2.x as supported, and the Graylog 7.0 upgrade notes say Graylog 7.0 needs at least MongoDB 7.0. A cluster still on an older MongoDB release therefore has to be stepped up before the Graylog upgrade, and each intermediate version must also be one the matrix accepts. Read the row for your exact target, including the minor releases it covers, and write down the MongoDB version you will reach at each stage. Check the version on every replica set member, because a mixed-version replica set is a state to pass through quickly, not a place to stop.
The 8.2.x ceiling matters most when you plan beyond Graylog 7.2. Because the supplied matrix ends at 8.2.x for Graylog 7.0 through 7.2, moving MongoDB to 8.3 or later is not supported by those rows, and it may complicate a later Graylog move. Treat 8.2.x as the upper bound of the current plan. Before you move the database past it, ask for the matrix entry for each later Graylog release and confirm that it accepts the newer MongoDB version. Record the MongoDB version in your runbook at the end of this upgrade so the next Graylog upgrade starts from a known position.
Confirm the matrix on the day you upgrade, not only during planning. Documentation changes between releases, so the page you read weeks earlier may describe an older target or a different patch. Open the Graylog compatibility matrix for the exact Graylog version in your change ticket, confirm the MongoDB range for that version, and note the date and the page version you used. If the matrix and the Graylog upgrade notes disagree, stop and resolve the difference with Graylog before the first MongoDB change. If a partner runs the work, put this check in the written scope so the evidence sits in your change record.
How DeployOpen scopes and delivers the MongoDB step
DeployOpen treats the MongoDB step as its own piece of work with a written scope, a rehearsed sequence and a handover your team can run again. The work happens inside your infrastructure, so the replica set, backups and change records stay under your control.
How we scope
- Confirm the current MongoDB version, replica set topology and the Graylog version you are moving to before quoting.
- Record the target MongoDB range that the Graylog compatibility matrix lists for your release, in writing.
- Agree in writing which nodes, backups, maintenance windows and verification steps are in scope and out of scope.
How we build
- Run the preflight checks in a staging copy of the cluster and document every warning before production work begins.
- Upgrade secondaries first, then step the primary through the replica set order your environment supports, checking health after each node.
- Test a restore from the pre-upgrade backup so rollback is proven, not assumed, before Graylog itself is touched.
How we hand over
- Deliver a runbook with the exact node order, commands, health checks and rollback steps used during the upgrade.
- Provide a change record showing versions before and after, backup identifiers and any deviations from the plan.
- Walk your operations team through the runbook so they can repeat the procedure for later MongoDB or Graylog upgrades.
How we support
- Engagements are fixed-scope, so the scope, deliverables and timeline are agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer if your team wants help with later steps.
- Ask any provider to confirm which MongoDB and Graylog versions their runbook has been checked against for your release.
