Maintenance modes

Neo4j supports two maintenance modes: online and offline, which you can use to perform different maintenance tasks.

Online Maintenance

Online maintenance does not require stopping the neo4j process. It is performed using the command kubectl exec.

To directly run tasks:

kubectl exec <release-name>-0 -- neo4j-admin database info --from-path=/var/lib/neo4j/data/databases --expand-commands

All neo4j-admin commands need the --expand-commands flag to run in the Neo4j container. This is because the Neo4j Helm chart defines the Neo4j configuration using command expansion to dynamically resolve some configuration parameters at runtime.

To run a series of commands, use an interactive shell:

kubectl exec -it <release-name>-0 -- bash

Processes executed using kubectl exec count towards the Neo4j container’s memory allocation. Therefore, running tasks that use a significant amount of memory or running Neo4j in an extremely memory-constrained configuration could cause the Neo4j container to be terminated by the underlying Operating System.

Offline Maintenance

You use the Neo4j offline maintenance mode to perform maintenance tasks that require Neo4j to be offline. In this mode, the neo4j process is not running. However, the Neo4j Pod does run, but it never reaches the status READY.

Put the Neo4j instance in offline mode

To put the Neo4j instance in offline maintenance mode, you set the offlineMaintenanceModeEnabled: true and upgrade the helm release.
- You can do that by using the values.yaml file:
  1. Open your values.yaml file and add offlineMaintenanceModeEnabled: true to the neo4j object:
    
    neo4j: offlineMaintenanceModeEnabled: true
  2. Run helm upgrade to apply the changes:
    
    helm upgrade <release-name> neo4j/neo4j -f values.yaml
- Alternatively, you can set neo4j.offlineMaintenanceModeEnabled to true as part of the helm upgrade command:
  helm upgrade neo4j/neo4j --version=2025.09.0 --reuse-values --set neo4j.offlineMaintenanceModeEnabled=true
Poll kubectl get pods until the pod has restarted (STATUS=Running).
```
kubectl get pod <release-name>-0
```
Connect to the pod with an interactive shell:
```
kubectl exec -it "<release-name>-0" -- bash
```
View running java processes:
```
jps
```
```
19 Jps
```
The result shows no running java process other than jps itself.

Run task in offline mode

Offline maintenance tasks are performed using the command kubectl exec.

To directly run tasks:

kubectl exec <release-name>-0 -- neo4j-admin database info --from-path=/var/lib/neo4j/data/databases --expand-commands

To run a series of commands, use an interactive shell:
```
kubectl exec -it <release-name>-0 -- bash
```

For long-running commands, use a shell and run tasks using nohup so they continue if the kubectl exec connection is lost:

kubectl exec -it <release-name>-0 -- bash
  $ nohup neo4j-admin database check neo4j --expand-commands &>job.out </dev/null &
  $ tail -f job.out

Put the Neo4j DBMS in online mode

When you finish with the maintenance tasks, return the Neo4j instance to normal operation:

You can do that by using the values.yaml file:
1. Open your values.yaml file and add offlineMaintenanceModeEnabled: false to the neo4j object:
  neo4j: offlineMaintenanceModeEnabled: false
2. Run helm upgrade to apply the changes:
  helm upgrade <release-name> neo4j/neo4j -f values.yaml

Alternatively, you can run helm upgrade with the flag set to false:

helm upgrade  neo4j/neo4j-standalone --version=2025.09.0 --reuse-values --set neo4j.offlineMaintenanceModeEnabled=false