---
title: Charmhub | Deploy MongoDB using Charmhub - The Open Operator Collection
description: Deploy the latest version of MongoDB on any cloud.
url: https://charmhub.io/mongodb/libraries/upgrade_helpers
---

# MongoDB

[Canonical](https://charmhub.io/publisher/data-platform "View all packages from Canonical")

* [Canonical](https://charmhub.io/publisher/data-platform "View all packages from Canonical")
* [Databases](https://charmhub.io/?filter=databases)

Platform:

24.04

22.04

6/stable 265

```
juju deploy mongodb --channel 6/stable
```

[Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications)

[Toggle side navigation](https://charmhub.io/mongodb/libraries/upgrade_helpers#drawer)

## charms.mongodb.v0.upgrade\_helpers

* [*Docstrings*Docstrings](https://charmhub.io/mongodb/libraries/upgrade_helpers)
  [*Code*Source code](https://charmhub.io/mongodb/libraries/upgrade_helpers/source-code)
* + Download

    Fetch library

    ```
    charmcraft fetch-lib charms.mongodb.v0.upgrade_helpers
    ```

    [Download upgrade\_helpers.py](https://charmhub.io/mongodb/libraries/upgrade_helpers/download)
  + *Last updated* 03 Oct 2024
  + *Revision* Library version 0.3

Substrate agnostic manager for handling MongoDB in-place upgrades.

---

Index

* [def unit\_number(
  unit\_
  )](https://charmhub.io/mongodb/libraries/upgrade_helpers#unit_number)
* [class StatusException](https://charmhub.io/mongodb/libraries/upgrade_helpers#statusexception)
* + [def \_\_init\_\_(
    self,
    status)](https://charmhub.io/mongodb/libraries/upgrade_helpers#statusexception-__init__)
* [class PrecheckFailed](https://charmhub.io/mongodb/libraries/upgrade_helpers#precheckfailed)
* + [def \_\_init\_\_(
    self,
    message)](https://charmhub.io/mongodb/libraries/upgrade_helpers#precheckfailed-__init__)
* [class FailedToElectNewPrimaryError](https://charmhub.io/mongodb/libraries/upgrade_helpers#failedtoelectnewprimaryerror)
* [class ClusterNotHealthyError](https://charmhub.io/mongodb/libraries/upgrade_helpers#clusternothealthyerror)
* [class BalancerStillRunningError](https://charmhub.io/mongodb/libraries/upgrade_helpers#balancerstillrunningerror)
* [class PeerRelationNotReady](https://charmhub.io/mongodb/libraries/upgrade_helpers#peerrelationnotready)
* [class UnitState](https://charmhub.io/mongodb/libraries/upgrade_helpers#unitstate)
* [class AbstractUpgrade](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade)
* + [def \_\_init\_\_(
    self,
    charm\_)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-__init__)
* + [def unit\_state(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-unit_state)
* + [def unit\_state(
    self,
    value)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-unit_state)
* + [def is\_compatible(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-is_compatible)
* + [def in\_progress(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-in_progress)
* + [def get\_unit\_juju\_status(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-get_unit_juju_status)
* + [def app\_status(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-app_status)
* + [def versions\_set(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-versions_set)
* + [def set\_versions\_in\_app\_databag(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-set_versions_in_app_databag)
* + [def upgrade\_resumed(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-upgrade_resumed)
* + [def reconcile\_partition(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-reconcile_partition)
* + [def pre\_upgrade\_check(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#abstractupgrade-pre_upgrade_check)
* [class GenericMongoDBUpgrade](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade)
* + [def \_\_init\_\_(
    self,
    charm)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-__init__)
* + [def move\_primary\_to\_last\_upgrade\_unit(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-move_primary_to_last_upgrade_unit)
* + [def wait\_for\_cluster\_healthy(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-wait_for_cluster_healthy)
* + [def is\_cluster\_healthy(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-is_cluster_healthy)
* + [def are\_nodes\_healthy(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-are_nodes_healthy)
* + [def are\_replicas\_in\_sharded\_cluster\_healthy(
    self,
    mongos\_config)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-are_replicas_in_sharded_cluster_healthy)
* + [def are\_shards\_healthy(
    self,
    mongos\_config)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-are_shards_healthy)
* + [def get\_all\_replica\_set\_configs\_in\_cluster(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-get_all_replica_set_configs_in_cluster)
* + [def are\_replica\_set\_nodes\_healthy(
    self,
    mongodb\_config)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-are_replica_set_nodes_healthy)
* + [def is\_cluster\_able\_to\_read\_write(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-is_cluster_able_to_read_write)
* + [def is\_sharded\_cluster\_able\_to\_read\_write(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-is_sharded_cluster_able_to_read_write)
* + [def get\_mongodb\_config\_from\_shard\_entry(
    self,
    shard\_entry)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-get_mongodb_config_from_shard_entry)
* + [def get\_cluster\_mongos(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-get_cluster_mongos)
* + [def is\_replica\_set\_able\_read\_write(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-is_replica_set_able_read_write)
* + [def clear\_db\_collection(
    self,
    mongos\_config,
    db\_name)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-clear_db_collection)
* + [def clear\_tmp\_collection(
    self,
    mongodb\_config,
    collection\_name)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-clear_tmp_collection)
* + [def confirm\_excepted\_write\_on\_replica(
    self,
    host,
    db\_name,
    collection,
    expected\_write\_value,
    secondary\_config)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-confirm_excepted_write_on_replica)
* + [def get\_random\_write\_and\_collection(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-get_random_write_and_collection)
* + [def add\_write\_to\_sharded\_cluster(
    self,
    mongos\_config,
    db\_name,
    collection\_name,
    write\_value)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-add_write_to_sharded_cluster)
* + [def add\_write\_to\_replica\_set(
    self,
    mongodb\_config,
    collection\_name,
    write\_value)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-add_write_to_replica_set)
* + [def is\_write\_on\_secondaries(
    self,
    mongodb\_config,
    collection\_name,
    expected\_write\_value,
    db\_name)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-is_write_on_secondaries)
* + [def step\_down\_primary\_and\_wait\_reelection(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-step_down_primary_and_wait_reelection)
* + [def are\_pre\_upgrade\_operations\_config\_server\_successful(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-are_pre_upgrade_operations_config_server_successful)
* + [def is\_feature\_compatibility\_version(
    self,
    expected\_feature\_version)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-is_feature_compatibility_version)
* + [def set\_mongos\_feature\_compatibilty\_version(
    self,
    feature\_version)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-set_mongos_feature_compatibilty_version)
* + [def turn\_off\_and\_wait\_for\_balancer(
    self)](https://charmhub.io/mongodb/libraries/upgrade_helpers#genericmongodbupgrade-turn_off_and_wait_for_balancer)

#### def unit\_number(unit\_: Unit)

Description

Get unit number. None

#### class StatusException

Description

Exception with ops status. None

Methods

StatusException.
\_\_init\_\_(

*self*

,
status: StatusBase
)

#### class PrecheckFailed

Description

App is not ready to upgrade. None

Methods

PrecheckFailed.
\_\_init\_\_(

*self*

,
message: str
)

#### class FailedToElectNewPrimaryError

Description

Raised when a new primary isn't elected after stepping down. None

#### class ClusterNotHealthyError

Description

Raised when the cluster is not healthy. None

#### class BalancerStillRunningError

Description

Raised when the balancer is still running after stopping it. None

#### class PeerRelationNotReady

Description

Upgrade peer relation not available (to this unit). None

#### class UnitState

Description

Unit upgrade state. None

#### class AbstractUpgrade

In-place upgrades abstract class (typing).

Description

Based off specification: DA058 - In-Place Upgrades - Kubernetes v2
(https://docs.google.com/document/d/1tLjknwHudjcHs42nzPVBNkHs98XxAOT2BXGGpP7NyEU/)

Methods

AbstractUpgrade.
\_\_init\_\_(

*self*

,
charm\_: CharmBase
)

AbstractUpgrade.
unit\_state(

*self*
)

Description

Unit upgrade state. None

AbstractUpgrade.
unit\_state(

*self*

,
value: UnitState
)

AbstractUpgrade.
is\_compatible(

*self*
)

Description

Whether upgrade is supported from previous versions. None

AbstractUpgrade.
in\_progress(

*self*
)

Description

Whether upgrade is in progress. None

AbstractUpgrade.
get\_unit\_juju\_status(

*self*
)

Description

Unit upgrade status. None

AbstractUpgrade.
app\_status(

*self*
)

Description

App upgrade status. None

AbstractUpgrade.
versions\_set(

*self*
)

Whether versions have been saved in app databag.

Description

Should only be `False` during first charm install.

If a user upgrades from a charm that does not set versions, this charm will get stuck.

AbstractUpgrade.
set\_versions\_in\_app\_databag(

*self*
)

Save current versions in app databag.

Description

Used after next upgrade to check compatibility (i.e. whether that upgrade should be
allowed).

AbstractUpgrade.
upgrade\_resumed(

*self*
)

Description

Whether user has resumed upgrade with Juju action. None

AbstractUpgrade.
reconcile\_partition(

*self*
)

Description

If ready, allow next unit to upgrade. None

AbstractUpgrade.
pre\_upgrade\_check(

*self*
)

Check if this app is ready to upgrade.

Description

Runs before any units are upgraded

Does *not* run during rollback

On machines, this runs before any units are upgraded (after `juju refresh`)
On machines & Kubernetes, this also runs during pre-upgrade-check action

Can run on leader or non-leader unit

#### class GenericMongoDBUpgrade

Description

Substrate agnostif, abstract handler for upgrade events. None

Methods

GenericMongoDBUpgrade.
\_\_init\_\_(

*self*

,
charm: CharmBase
)

GenericMongoDBUpgrade.
move\_primary\_to\_last\_upgrade\_unit(

*self*
)

Moves the primary to last unit that gets upgraded (the unit with the lowest id).

Description

Raises FailedToMovePrimaryError

GenericMongoDBUpgrade.
wait\_for\_cluster\_healthy(

*self*
)

Waits until the cluster is healthy after upgrading.

Description

After a unit restarts it can take some time for the cluster to settle.

Raises:
ClusterNotHealthyError.

GenericMongoDBUpgrade.
is\_cluster\_healthy(

*self*
)

Description

Returns True if all nodes in the cluster/replcia set are healthy. None

GenericMongoDBUpgrade.
are\_nodes\_healthy(

*self*
)

Description

Returns true if all nodes in the MongoDB deployment are healthy. None

GenericMongoDBUpgrade.
are\_replicas\_in\_sharded\_cluster\_healthy(

*self*

,
mongos\_config: MongoConfiguration
)

Description

Returns True if all replicas in the sharded cluster are healthy. None

GenericMongoDBUpgrade.
are\_shards\_healthy(

*self*

,
mongos\_config: MongoConfiguration
)

Description

Returns True if all shards in the cluster are healthy. None

GenericMongoDBUpgrade.
get\_all\_replica\_set\_configs\_in\_cluster(

*self*
)

Description

Returns a list of all the mongodb\_configurations for each application in the cluster. None

GenericMongoDBUpgrade.
are\_replica\_set\_nodes\_healthy(

*self*

,
mongodb\_config: MongoConfiguration
)

Description

Returns true if all nodes in the MongoDB replica set are healthy. None

GenericMongoDBUpgrade.
is\_cluster\_able\_to\_read\_write(

*self*
)

Description

Returns True if read and write is feasible for cluster. None

GenericMongoDBUpgrade.
is\_sharded\_cluster\_able\_to\_read\_write(

*self*
)

Description

Returns True if possible to write all cluster shards and read from all replicas. None

GenericMongoDBUpgrade.
get\_mongodb\_config\_from\_shard\_entry(

*self*

,
shard\_entry: dict
)

Description

Returns a replica set MongoConfiguration based on a shard entry from ListShards. None

GenericMongoDBUpgrade.
get\_cluster\_mongos(

*self*
)

Description

Return a mongos configuration for the sharded cluster. None

GenericMongoDBUpgrade.
is\_replica\_set\_able\_read\_write(

*self*
)

Description

Returns True if is possible to write to primary and read from replicas. None

GenericMongoDBUpgrade.
clear\_db\_collection(

*self*

,
mongos\_config: MongoConfiguration

,
db\_name: str
)

Description

Clears the temporary collection. None

GenericMongoDBUpgrade.
clear\_tmp\_collection(

*self*

,
mongodb\_config: MongoConfiguration

,
collection\_name: str
)

Description

Clears the temporary collection. None

GenericMongoDBUpgrade.
confirm\_excepted\_write\_on\_replica(

*self*

,
host: str

,
db\_name: str

,
collection: str

,
expected\_write\_value: str

,
secondary\_config: MongoConfiguration
)

Description

Returns True if the replica contains the expected write in the provided collection. None

GenericMongoDBUpgrade.
get\_random\_write\_and\_collection(

*self*
)

Description

Returns a tuple for a random collection name and a unique write to add to it. None

GenericMongoDBUpgrade.
add\_write\_to\_sharded\_cluster(

*self*

,
mongos\_config: MongoConfiguration

,
db\_name

,
collection\_name

,
write\_value
)

Description

Adds a the provided write to the provided database with the provided collection. None

GenericMongoDBUpgrade.
add\_write\_to\_replica\_set(

*self*

,
mongodb\_config: MongoConfiguration

,
collection\_name

,
write\_value
)

Description

Adds a the provided write to the admin database with the provided collection. None

GenericMongoDBUpgrade.
is\_write\_on\_secondaries(

*self*

,
mongodb\_config: MongoConfiguration

,
collection\_name

,
expected\_write\_value

,
db\_name: str
)

Description

Returns true if the expected write. None

GenericMongoDBUpgrade.
step\_down\_primary\_and\_wait\_reelection(

*self*
)

Description

Steps down the current primary and waits for a new one to be elected. None

GenericMongoDBUpgrade.
are\_pre\_upgrade\_operations\_config\_server\_successful(

*self*
)

Description

Runs pre-upgrade operations for config-server and returns True if successful. None

GenericMongoDBUpgrade.
is\_feature\_compatibility\_version(

*self*

,
expected\_feature\_version
)

Returns True if all nodes in the sharded cluster have the expected\_feature\_version.

Description

Note it is NOT sufficient to check only mongos or the individual shards. It is necessary to
check each node according to MongoDB upgrade docs.

GenericMongoDBUpgrade.
set\_mongos\_feature\_compatibilty\_version(

*self*

,
feature\_version
)

Description

Sets the mongos feature compatibility version. None

GenericMongoDBUpgrade.
turn\_off\_and\_wait\_for\_balancer(

*self*
)

Description

Sends the stop command to the balancer and wait for it to stop running. None