diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 52cd0eec2..572ab9064 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -77,6 +77,7 @@ jobs:
           - tls-integration
           - standalone-integration
           - legacy-client-relation-integration
+          - upgrade-integration
         agent-versions: 
           - "2.9.45"  # renovate: latest juju 2
           - "3.1.6"  # renovate: latest juju 3
diff --git a/actions.yaml b/actions.yaml
index 0a5e84d7a..5ffeba4ee 100644
--- a/actions.yaml
+++ b/actions.yaml
@@ -7,3 +7,9 @@ set-tls-private-key:
     private-key:
       type: string
       description: The content of private key for communications with clients. Content will be auto-generated if this option is not specified.
+
+pre-upgrade-check:
+  description: Run necessary pre-upgrade checks before executing a charm upgrade.
+
+resume-upgrade:
+  description: Resume a rolling upgrade after asserting successful upgrade of a new revision.
diff --git a/lib/charms/data_platform_libs/v0/data_interfaces.py b/lib/charms/data_platform_libs/v0/data_interfaces.py
index 9fa0021ec..2624dd4d6 100644
--- a/lib/charms/data_platform_libs/v0/data_interfaces.py
+++ b/lib/charms/data_platform_libs/v0/data_interfaces.py
@@ -320,7 +320,7 @@ def _on_topic_requested(self, event: TopicRequestedEvent):
 
 # Increment this PATCH version before using `charmcraft publish-lib` or reset
 # to 0 if you are raising the major API version
-LIBPATCH = 18
+LIBPATCH = 19
 
 PYDEPS = ["ops>=2.0.0"]
 
@@ -377,12 +377,19 @@ class SecretsIllegalUpdateError(SecretError):
     """Secrets aren't yet available for Juju version used."""
 
 
-def get_encoded_field(relation, member, field) -> Dict[str, str]:
+def get_encoded_field(
+    relation: Relation, member: Union[Unit, Application], field: str
+) -> Union[str, List[str], Dict[str, str]]:
     """Retrieve and decode an encoded field from relation data."""
     return json.loads(relation.data[member].get(field, "{}"))
 
 
-def set_encoded_field(relation, member, field, value) -> None:
+def set_encoded_field(
+    relation: Relation,
+    member: Union[Unit, Application],
+    field: str,
+    value: Union[str, list, Dict[str, str]],
+) -> None:
     """Set an encoded field from relation data."""
     relation.data[member].update({field: json.dumps(value)})
 
@@ -400,6 +407,15 @@ def diff(event: RelationChangedEvent, bucket: Union[Unit, Application]) -> Diff:
     """
     # Retrieve the old data from the data key in the application relation databag.
     old_data = get_encoded_field(event.relation, bucket, "data")
+
+    if not old_data:
+        old_data = {}
+
+    if not isinstance(old_data, dict):
+        # We should never get here, added to re-assure pyright
+        logger.error("Previous databag diff is of a wrong type.")
+        old_data = {}
+
     # Retrieve the new data from the event relation databag.
     new_data = (
         {key: value for key, value in event.relation.data[event.app].items() if key != "data"}
@@ -408,12 +424,16 @@ def diff(event: RelationChangedEvent, bucket: Union[Unit, Application]) -> Diff:
     )
 
     # These are the keys that were added to the databag and triggered this event.
-    added = new_data.keys() - old_data.keys()
+    added = new_data.keys() - old_data.keys()  # pyright: ignore [reportGeneralTypeIssues]
     # These are the keys that were removed from the databag and triggered this event.
-    deleted = old_data.keys() - new_data.keys()
+    deleted = old_data.keys() - new_data.keys()  # pyright: ignore [reportGeneralTypeIssues]
     # These are the keys that already existed in the databag,
     # but had their values changed.
-    changed = {key for key in old_data.keys() & new_data.keys() if old_data[key] != new_data[key]}
+    changed = {
+        key
+        for key in old_data.keys() & new_data.keys()  # pyright: ignore [reportGeneralTypeIssues]
+        if old_data[key] != new_data[key]  # pyright: ignore [reportGeneralTypeIssues]
+    }
     # Convert the new_data to a serializable format and save it for a next diff check.
     set_encoded_field(event.relation, bucket, "data", new_data)
 
@@ -426,6 +446,9 @@ def leader_only(f):
 
     def wrapper(self, *args, **kwargs):
         if not self.local_unit.is_leader():
+            logger.error(
+                "This operation (%s()) can only be performed by the leader unit", f.__name__
+            )
             return
         return f(self, *args, **kwargs)
 
@@ -587,11 +610,18 @@ def _get_relation_secret(
 
     @abstractmethod
     def _fetch_specific_relation_data(
-        self, relation, fields: Optional[List[str]]
+        self, relation: Relation, fields: Optional[List[str]]
     ) -> Dict[str, str]:
         """Fetch data available (directily or indirectly -- i.e. secrets) from the relation."""
         raise NotImplementedError
 
+    @abstractmethod
+    def _fetch_my_specific_relation_data(
+        self, relation: Relation, fields: Optional[List[str]]
+    ) -> Dict[str, str]:
+        """Fetch data available (directily or indirectly -- i.e. secrets) from the relation for owner/this_app."""
+        raise NotImplementedError
+
     # Internal helper methods
 
     @staticmethod
@@ -658,6 +688,22 @@ def _group_secret_fields(secret_fields: List[str]) -> Dict[SecretGroup, List[str
                 secret_fieldnames_grouped.setdefault(SecretGroup.EXTRA, []).append(key)
         return secret_fieldnames_grouped
 
+    def _retrieve_group_secret_contents(
+        self,
+        relation_id: int,
+        group: SecretGroup,
+        secret_fields: Optional[Union[Set[str], List[str]]] = None,
+    ) -> Dict[str, str]:
+        """Helper function to retrieve collective, requested contents of a secret."""
+        if not secret_fields:
+            secret_fields = []
+
+        if (secret := self._get_relation_secret(relation_id, group)) and (
+            secret_data := secret.get_content()
+        ):
+            return {k: v for k, v in secret_data.items() if k in secret_fields}
+        return {}
+
     @juju_secrets_only
     def _get_relation_secret_data(
         self, relation_id: int, group_mapping: SecretGroup, relation_name: Optional[str] = None
@@ -667,6 +713,72 @@ def _get_relation_secret_data(
         if secret:
             return secret.get_content()
 
+    def _fetch_relation_data_without_secrets(
+        self, app: Application, relation: Relation, fields: Optional[List[str]]
+    ) -> Dict[str, str]:
+        """Fetching databag contents when no secrets are involved.
+
+        Since the Provider's databag is the only one holding secrest, we can apply
+        a simplified workflow to read the Require's side's databag.
+        This is used typically when the Provides side wants to read the Requires side's data,
+        or when the Requires side may want to read its own data.
+        """
+        if fields:
+            return {k: relation.data[app][k] for k in fields if k in relation.data[app]}
+        else:
+            return dict(relation.data[app])
+
+    def _fetch_relation_data_with_secrets(
+        self,
+        app: Application,
+        req_secret_fields: Optional[List[str]],
+        relation: Relation,
+        fields: Optional[List[str]] = None,
+    ) -> Dict[str, str]:
+        """Fetching databag contents when secrets may be involved.
+
+        This function has internal logic to resolve if a requested field may be "hidden"
+        within a Relation Secret, or directly available as a databag field. Typically
+        used to read the Provides side's databag (eigher by the Requires side, or by
+        Provides side itself).
+        """
+        result = {}
+
+        normal_fields = fields
+        if not normal_fields:
+            normal_fields = list(relation.data[app].keys())
+
+        if req_secret_fields and self.secrets_enabled:
+            if fields:
+                # Processing from what was requested
+                normal_fields = set(fields) - set(req_secret_fields)
+                secret_fields = set(fields) - set(normal_fields)
+
+                secret_fieldnames_grouped = self._group_secret_fields(list(secret_fields))
+
+                for group in secret_fieldnames_grouped:
+                    if contents := self._retrieve_group_secret_contents(
+                        relation.id, group, secret_fields
+                    ):
+                        result.update(contents)
+                    else:
+                        # If it wasn't found as a secret, let's give it a 2nd chance as "normal" field
+                        normal_fields |= set(secret_fieldnames_grouped[group])
+            else:
+                # Processing from what is given, i.e. retrieving all
+                normal_fields = [
+                    f for f in relation.data[app].keys() if not self._is_secret_field(f)
+                ]
+                secret_fields = [f for f in relation.data[app].keys() if self._is_secret_field(f)]
+                for group in SecretGroup:
+                    result.update(
+                        self._retrieve_group_secret_contents(relation.id, group, req_secret_fields)
+                    )
+
+        # Processing "normal" fields. May include leftover from what we couldn't retrieve as a secret.
+        result.update({k: relation.data[app][k] for k in normal_fields if k in relation.data[app]})
+        return result
+
     # Public methods
 
     def get_relation(self, relation_name, relation_id) -> Relation:
@@ -716,6 +828,57 @@ def fetch_relation_data(
                 data[relation.id] = self._fetch_specific_relation_data(relation, fields)
         return data
 
+    def fetch_relation_field(
+        self, relation_id: int, field: str, relation_name: Optional[str] = None
+    ) -> Optional[str]:
+        """Get a single field from the relation data."""
+        return (
+            self.fetch_relation_data([relation_id], [field], relation_name)
+            .get(relation_id, {})
+            .get(field)
+        )
+
+    @leader_only
+    def fetch_my_relation_data(
+        self,
+        relation_ids: Optional[List[int]] = None,
+        fields: Optional[List[str]] = None,
+        relation_name: Optional[str] = None,
+    ) -> Optional[Dict[int, Dict[str, str]]]:
+        """Fetch data of the 'owner' (or 'this app') side of the relation.
+
+        NOTE: Since only the leader can read the relation's 'this_app'-side
+        Application databag, the functionality is limited to leaders
+        """
+        if not relation_name:
+            relation_name = self.relation_name
+
+        relations = []
+        if relation_ids:
+            relations = [
+                self.get_relation(relation_name, relation_id) for relation_id in relation_ids
+            ]
+        else:
+            relations = self.relations
+
+        data = {}
+        for relation in relations:
+            if not relation_ids or relation.id in relation_ids:
+                data[relation.id] = self._fetch_my_specific_relation_data(relation, fields)
+        return data
+
+    @leader_only
+    def fetch_my_relation_field(
+        self, relation_id: int, field: str, relation_name: Optional[str] = None
+    ) -> Optional[str]:
+        """Get a single field from the relation data -- owner side.
+
+        NOTE: Since only the leader can read the relation's 'this_app'-side
+        Application databag, the functionality is limited to leaders
+        """
+        if relation_data := self.fetch_my_relation_data([relation_id], [field], relation_name):
+            return relation_data.get(relation_id, {}).get(field)
+
     # Public methods - mandatory override
 
     @abstractmethod
@@ -823,18 +986,32 @@ def _get_relation_secret(
         if secret_uri := relation.data[self.local_app].get(secret_field):
             return self.secrets.get(label, secret_uri)
 
-    def _fetch_specific_relation_data(self, relation, fields: Optional[List[str]]) -> dict:
+    def _fetch_specific_relation_data(
+        self, relation: Relation, fields: Optional[List[str]]
+    ) -> Dict[str, str]:
         """Fetching relation data for Provides.
 
-        NOTE: Since all secret fields are in the Requires side of the databag, we don't need to worry about that
+        NOTE: Since all secret fields are in the Provides side of the databag, we don't need to worry about that
         """
         if not relation.app:
             return {}
 
-        if fields:
-            return {k: relation.data[relation.app].get(k) for k in fields}
-        else:
-            return relation.data[relation.app]
+        return self._fetch_relation_data_without_secrets(relation.app, relation, fields)
+
+    def _fetch_my_specific_relation_data(
+        self, relation: Relation, fields: Optional[List[str]]
+    ) -> dict:
+        """Fetching our own relation data."""
+        secret_fields = None
+        if relation.app:
+            secret_fields = get_encoded_field(relation, relation.app, REQ_SECRET_FIELDS)
+
+        return self._fetch_relation_data_with_secrets(
+            self.local_app,
+            secret_fields if isinstance(secret_fields, list) else None,
+            relation,
+            fields,
+        )
 
     # Public methods -- mandatory overrides
 
@@ -843,7 +1020,10 @@ def update_relation_data(self, relation_id: int, fields: Dict[str, str]) -> None
         """Set values for fields not caring whether it's a secret or not."""
         relation = self.get_relation(self.relation_name, relation_id)
 
-        relation_secret_fields = get_encoded_field(relation, relation.app, REQ_SECRET_FIELDS)
+        if relation.app:
+            relation_secret_fields = get_encoded_field(relation, relation.app, REQ_SECRET_FIELDS)
+        else:
+            relation_secret_fields = []
 
         normal_fields = list(fields)
         if relation_secret_fields and self.secrets_enabled:
@@ -1021,22 +1201,6 @@ def is_resource_created(self, relation_id: Optional[int] = None) -> bool:
                 else False
             )
 
-    def _retrieve_group_secret_contents(
-        self,
-        relation_id,
-        group: SecretGroup,
-        secret_fields: Optional[Union[Set[str], List[str]]] = None,
-    ) -> Dict[str, str]:
-        """Helper function to retrieve collective, requested contents of a secret."""
-        if not secret_fields:
-            secret_fields = []
-
-        if (secret := self._get_relation_secret(relation_id, group)) and (
-            secret_data := secret.get_content()
-        ):
-            return {k: v for k, v in secret_data.items() if k in secret_fields}
-        return {}
-
     # Event handlers
 
     def _on_relation_created_event(self, event: RelationCreatedEvent) -> None:
@@ -1070,49 +1234,16 @@ def _get_relation_secret(
     def _fetch_specific_relation_data(
         self, relation, fields: Optional[List[str]] = None
     ) -> Dict[str, str]:
+        """Fetching Requires data -- that may include secrets."""
         if not relation.app:
             return {}
+        return self._fetch_relation_data_with_secrets(
+            relation.app, self.secret_fields, relation, fields
+        )
 
-        result = {}
-
-        normal_fields = fields
-        if not normal_fields:
-            normal_fields = list(relation.data[relation.app].keys())
-
-        if self.secret_fields and self.secrets_enabled:
-            if fields:
-                # Processing from what was requested
-                normal_fields = set(fields) - set(self.secret_fields)
-                secret_fields = set(fields) - set(normal_fields)
-
-                secret_fieldnames_grouped = self._group_secret_fields(list(secret_fields))
-
-                for group in secret_fieldnames_grouped:
-                    if contents := self._retrieve_group_secret_contents(
-                        relation.id, group, secret_fields
-                    ):
-                        result.update(contents)
-                    else:
-                        # If it wasn't found as a secret, let's give it a 2nd chance as "normal" field
-                        normal_fields |= set(secret_fieldnames_grouped[group])
-            else:
-                # Processing from what is given, i.e. retrieving all
-                normal_fields = [
-                    f for f in relation.data[relation.app].keys() if not self._is_secret_field(f)
-                ]
-                secret_fields = [
-                    f for f in relation.data[relation.app].keys() if self._is_secret_field(f)
-                ]
-                for group in SecretGroup:
-                    result.update(
-                        self._retrieve_group_secret_contents(
-                            relation.id, group, self.secret_fields
-                        )
-                    )
-
-        # Processing "normal" fields. May include leftover from what we couldn't retrieve as a secret.
-        result.update({k: relation.data[relation.app].get(k) for k in normal_fields})
-        return result
+    def _fetch_my_specific_relation_data(self, relation, fields: Optional[List[str]]) -> dict:
+        """Fetching our own relation data."""
+        return self._fetch_relation_data_without_secrets(self.local_app, relation, fields)
 
     # Public methods -- mandatory overrides
 
@@ -1135,18 +1266,6 @@ def update_relation_data(self, relation_id: int, data: dict) -> None:
         if relation:
             relation.data[self.local_app].update(data)
 
-    # "Native" public methods
-
-    def fetch_relation_field(
-        self, relation_id: int, field: str, relation_name: Optional[str] = None
-    ) -> Optional[str]:
-        """Get a single field from the relation data."""
-        return (
-            self.fetch_relation_data([relation_id], [field], relation_name)
-            .get(relation_id, {})
-            .get(field)
-        )
-
 
 # General events
 
diff --git a/lib/charms/data_platform_libs/v0/upgrade.py b/lib/charms/data_platform_libs/v0/upgrade.py
new file mode 100644
index 000000000..b8c753776
--- /dev/null
+++ b/lib/charms/data_platform_libs/v0/upgrade.py
@@ -0,0 +1,1074 @@
+# Copyright 2023 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""Library to manage in-place upgrades for charms running on VMs and K8s.
+
+This library contains handlers for `upgrade` relation events used to coordinate
+between units in an application during a `juju refresh`, as well as `Pydantic` models
+for instantiating, validating and comparing dependencies.
+
+An upgrade on VMs is initiated with the command `juju refresh`. Once executed, the following
+events are emitted to each unit at random:
+    - `upgrade-charm`
+    - `config-changed`
+    - `leader-settings-changed` - Non-leader only
+
+Charm authors can implement the classes defined in this library to streamline the process of
+coordinating which unit updates when, achieved through updating of unit-data `state` throughout.
+
+At a high-level, the upgrade steps are as follows:
+    - Run pre-checks on the cluster to confirm it is safe to upgrade
+    - Create stack of unit.ids, to serve as the upgrade order (generally workload leader is last)
+    - Start the upgrade by issuing a Juju CLI command
+    - The unit at the top of the stack gets permission to upgrade
+    - The unit handles the upgrade and restarts their service
+    - Repeat, until all units have restarted
+
+### Usage by charm authors
+
+#### `upgrade` relation
+
+Charm authors must implement an additional peer-relation.
+
+As this library uses relation data exchanged between units to coordinate, charm authors
+need to add a new relation interface. The relation name does not matter.
+
+`metadata.yaml`
+```yaml
+peers:
+  upgrade:
+    interface: upgrade
+```
+
+#### Dependencies JSON/Dict
+
+Charm authors must implement a dict object tracking current charm versions, requirements + upgradability.
+
+Many workload versions may be incompatible with older/newer versions. This same idea also can apply to
+charm or snap versions. Workloads with required related applications (e.g Kafka + ZooKeeper) also need to
+ensure their versions are compatible during an upgrade, to avoid cluster failure.
+
+As such, it is necessasry to freeze any dependencies within each published charm. An example of this could
+be creating a `DEPENDENCIES` dict within the charm code, with the following structure:
+
+`src/literals.py`
+```python
+DEPENDENCIES = {
+    "kafka_charm": {
+        "dependencies": {"zookeeper": ">50"},
+        "name": "kafka",
+        "upgrade_supported": ">90",
+        "version": "100",
+    },
+    "kafka_service": {
+        "dependencies": {"zookeeper": "^3"},
+        "name": "kafka",
+        "upgrade_supported": ">=0.8",
+        "version": "3.3.2",
+    },
+}
+```
+
+The first-level key names are arbitrary labels for tracking what those versions+dependencies are for.
+The `dependencies` second-level values are a key-value map of any required external applications,
+    and the versions this packaged charm can support.
+The `upgrade_suppported` second-level values are requirements from which an in-place upgrade can be
+    supported by the charm.
+The `version` second-level values correspond to the current version of this packaged charm.
+
+Any requirements comply with [`poetry`'s dependency specifications](https://python-poetry.org/docs/dependency-specification/#caret-requirements).
+
+### Dependency Model
+
+Charm authors must implement their own class inheriting from `DependencyModel`.
+
+Using a `Pydantic` model to instantiate the aforementioned `DEPENDENCIES` dict gives stronger type safety and additional
+layers of validation.
+
+Implementation just needs to ensure that the top-level key names from `DEPENDENCIES` are defined as attributed in the model.
+
+`src/upgrade.py`
+```python
+from pydantic import BaseModel
+
+class KafkaDependenciesModel(BaseModel):
+    kafka_charm: DependencyModel
+    kafka_service: DependencyModel
+```
+
+### Overrides for `DataUpgrade`
+
+Charm authors must define their own class, inheriting from `DataUpgrade`, overriding all required `abstractmethod`s.
+
+```python
+class ZooKeeperUpgrade(DataUpgrade):
+    def __init__(self, charm: "ZooKeeperUpgrade", **kwargs):
+        super().__init__(charm, **kwargs)
+        self.charm = charm
+```
+
+#### Implementation of `pre_upgrade_check()`
+
+Before upgrading a cluster, it's a good idea to check that it is stable and healthy before permitting it.
+Here, charm authors can validate upgrade safety through API calls, relation-data checks, etc.
+If any of these checks fail, raise `ClusterNotReadyError`.
+
+```python
+    @override
+    def pre_upgrade_check(self) -> None:
+        default_message = "Pre-upgrade check failed and cannot safely upgrade"
+        try:
+            if not self.client.members_broadcasting or not len(self.client.server_members) == len(
+                self.charm.cluster.peer_units
+            ):
+                raise ClusterNotReadyError(
+                    message=default_message,
+                    cause="Not all application units are connected and broadcasting in the quorum",
+                )
+
+            if self.client.members_syncing:
+                raise ClusterNotReadyError(
+                    message=default_message, cause="Some quorum members are syncing data"
+                )
+
+            if not self.charm.cluster.stable:
+                raise ClusterNotReadyError(
+                    message=default_message, cause="Charm has not finished initialising"
+                )
+
+        except QuorumLeaderNotFoundError:
+            raise ClusterNotReadyError(message=default_message, cause="Quorum leader not found")
+        except ConnectionClosedError:
+            raise ClusterNotReadyError(
+                message=default_message, cause="Unable to connect to the cluster"
+            )
+```
+
+#### Implementation of `build_upgrade_stack()` - VM ONLY
+
+Oftentimes, it is necessary to ensure that the workload leader is the last unit to upgrade,
+to ensure high-availability during the upgrade process.
+Here, charm authors can create a LIFO stack of unit.ids, represented as a list of unit.id strings,
+with the leader unit being at i[0].
+
+```python
+@override
+def build_upgrade_stack(self) -> list[int]:
+    upgrade_stack = []
+    for unit in self.charm.cluster.peer_units:
+        config = self.charm.cluster.unit_config(unit=unit)
+
+        # upgrade quorum leader last
+        if config["host"] == self.client.leader:
+            upgrade_stack.insert(0, int(config["unit_id"]))
+        else:
+            upgrade_stack.append(int(config["unit_id"]))
+
+    return upgrade_stack
+```
+
+#### Implementation of `_on_upgrade_granted()`
+
+On relation-changed events, each unit will check the current upgrade-stack persisted to relation data.
+If that unit is at the top of the stack, it will emit an `upgrade-granted` event, which must be handled.
+Here, workloads can be re-installed with new versions, checks can be made, data synced etc.
+If the new unit successfully rejoined the cluster, call `set_unit_completed()`.
+If the new unit failed to rejoin the cluster, call `set_unit_failed()`.
+
+NOTE - It is essential here to manually call `on_upgrade_changed` if the unit is the current leader.
+This ensures that the leader gets it's own relation-changed event, and updates the upgrade-stack for
+other units to follow suit.
+
+```python
+@override
+def _on_upgrade_granted(self, event: UpgradeGrantedEvent) -> None:
+    self.charm.snap.stop_snap_service()
+
+    if not self.charm.snap.install():
+        logger.error("Unable to install ZooKeeper Snap")
+        self.set_unit_failed()
+        return None
+
+    logger.info(f"{self.charm.unit.name} upgrading service...")
+    self.charm.snap.restart_snap_service()
+
+    try:
+        logger.debug("Running post-upgrade check...")
+        self.pre_upgrade_check()
+
+        logger.debug("Marking unit completed...")
+        self.set_unit_completed()
+
+        # ensures leader gets it's own relation-changed when it upgrades
+        if self.charm.unit.is_leader():
+            logger.debug("Re-emitting upgrade-changed on leader...")
+            self.on_upgrade_changed(event)
+
+    except ClusterNotReadyError as e:
+        logger.error(e.cause)
+        self.set_unit_failed()
+```
+
+#### Implementation of `log_rollback_instructions()`
+
+If the upgrade fails, manual intervention may be required for cluster recovery.
+Here, charm authors can log out any necessary steps to take to recover from a failed upgrade.
+When a unit fails, this library will automatically log out this message.
+
+```python
+@override
+def log_rollback_instructions(self) -> None:
+    logger.error("Upgrade failed. Please run `juju refresh` to previous version.")
+```
+
+### Instantiating in the charm and deferring events
+
+Charm authors must add a class attribute for the child class of `DataUpgrade` in the main charm.
+They must also ensure that any non-upgrade related events that may be unsafe to handle during
+an upgrade, are deferred if the unit is not in the `idle` state - i.e not currently upgrading.
+
+```python
+class ZooKeeperCharm(CharmBase):
+    def __init__(self, *args):
+        super().__init__(*args)
+        self.upgrade = ZooKeeperUpgrade(
+            self,
+            relation_name = "upgrade",
+            substrate = "vm",
+            dependency_model=ZooKeeperDependencyModel(
+                **DEPENDENCIES
+            ),
+        )
+
+    def restart(self, event) -> None:
+        if not self.upgrade.state == "idle":
+            event.defer()
+            return None
+
+        self.restart_snap_service()
+```
+"""
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from typing import List, Literal, Optional, Set, Tuple
+
+import poetry.core.constraints.version as poetry_version
+from ops.charm import (
+    ActionEvent,
+    CharmBase,
+    CharmEvents,
+    RelationCreatedEvent,
+    UpgradeCharmEvent,
+)
+from ops.framework import EventBase, EventSource, Object
+from ops.model import ActiveStatus, BlockedStatus, MaintenanceStatus, Relation, Unit, WaitingStatus
+from pydantic import BaseModel, root_validator, validator
+
+# The unique Charmhub library identifier, never change it
+LIBID = "156258aefb79435a93d933409a8c8684"
+
+# Increment this major API version when introducing breaking changes
+LIBAPI = 0
+
+# Increment this PATCH version before using `charmcraft publish-lib` or reset
+# to 0 if you are raising the major API version
+LIBPATCH = 13
+
+PYDEPS = ["pydantic>=1.10,<2", "poetry-core"]
+
+logger = logging.getLogger(__name__)
+
+# --- DEPENDENCY RESOLUTION FUNCTIONS ---
+
+
+def verify_requirements(version: str, requirement: str) -> bool:
+    """Verifies a specified version against defined constraint.
+
+    Supports Poetry version constraints
+    https://python-poetry.org/docs/dependency-specification/#version-constraints
+
+    Args:
+        version: the version currently in use
+        requirement: Poetry version constraint
+
+    Returns:
+        True if `version` meets defined `requirement`. Otherwise False
+    """
+    return poetry_version.parse_constraint(requirement).allows(
+        poetry_version.Version.parse(version)
+    )
+
+
+# --- DEPENDENCY MODEL TYPES ---
+
+
+class DependencyModel(BaseModel):
+    """Manager for a single dependency.
+
+    To be used as part of another model representing a collection of arbitrary dependencies.
+
+    Example::
+
+        class KafkaDependenciesModel(BaseModel):
+            kafka_charm: DependencyModel
+            kafka_service: DependencyModel
+
+        deps = {
+            "kafka_charm": {
+                "dependencies": {"zookeeper": ">5"},
+                "name": "kafka",
+                "upgrade_supported": ">5",
+                "version": "10",
+            },
+            "kafka_service": {
+                "dependencies": {"zookeeper": "^3.6"},
+                "name": "kafka",
+                "upgrade_supported": "~3.3",
+                "version": "3.3.2",
+            },
+        }
+
+        model = KafkaDependenciesModel(**deps)  # loading dict in to model
+
+        print(model.dict())  # exporting back validated deps
+    """
+
+    dependencies: dict[str, str]
+    name: str
+    upgrade_supported: str
+    version: str
+
+    @validator("dependencies", "upgrade_supported", each_item=True)
+    @classmethod
+    def dependencies_validator(cls, value):
+        """Validates version constraint."""
+        if isinstance(value, dict):
+            deps = value.values()
+        else:
+            deps = [value]
+
+        for dep in deps:
+            poetry_version.parse_constraint(dep)
+
+        return value
+
+    @root_validator(skip_on_failure=True)
+    @classmethod
+    def version_upgrade_supported_validator(cls, values):
+        """Validates specified `version` meets `upgrade_supported` requirement."""
+        if not verify_requirements(
+            version=values.get("version"), requirement=values.get("upgrade_supported")
+        ):
+            raise ValueError(
+                f"upgrade_supported value {values.get('upgrade_supported')} greater than version value {values.get('version')} for {values.get('name')}."
+            )
+
+        return values
+
+    def can_upgrade(self, dependency: "DependencyModel") -> bool:
+        """Compares two instances of :class:`DependencyModel` for upgradability.
+
+        Args:
+            dependency: a dependency model to compare this model against
+
+        Returns:
+            True if current model can upgrade from dependent model. Otherwise False
+        """
+        return verify_requirements(version=self.version, requirement=dependency.upgrade_supported)
+
+
+# --- CUSTOM EXCEPTIONS ---
+
+
+class UpgradeError(Exception):
+    """Base class for upgrade related exceptions in the module."""
+
+    def __init__(self, message: str, cause: Optional[str], resolution: Optional[str]):
+        super().__init__(message)
+        self.message = message
+        self.cause = cause or ""
+        self.resolution = resolution or ""
+
+    def __repr__(self):
+        """Representation of the UpgradeError class."""
+        return f"{type(self).__module__}.{type(self).__name__} - {str(vars(self))}"
+
+    def __str__(self):
+        """String representation of the UpgradeError class."""
+        return repr(self)
+
+
+class ClusterNotReadyError(UpgradeError):
+    """Exception flagging that the cluster is not ready to start upgrading.
+
+    For example, if the cluster fails :class:`DataUpgrade._on_pre_upgrade_check_action`
+
+    Args:
+        message: string message to be logged out
+        cause: short human-readable description of the cause of the error
+        resolution: short human-readable instructions for manual error resolution (optional)
+    """
+
+    def __init__(self, message: str, cause: str, resolution: Optional[str] = None):
+        super().__init__(message, cause=cause, resolution=resolution)
+
+
+class KubernetesClientError(UpgradeError):
+    """Exception flagging that a call to Kubernetes API failed.
+
+    For example, if the cluster fails :class:`DataUpgrade._set_rolling_update_partition`
+
+    Args:
+        message: string message to be logged out
+        cause: short human-readable description of the cause of the error
+        resolution: short human-readable instructions for manual error resolution (optional)
+    """
+
+    def __init__(self, message: str, cause: str, resolution: Optional[str] = None):
+        super().__init__(message, cause=cause, resolution=resolution)
+
+
+class VersionError(UpgradeError):
+    """Exception flagging that the old `version` fails to meet the new `upgrade_supported`s.
+
+    For example, upgrades from version `2.x` --> `4.x`,
+        but `4.x` only supports upgrading from `3.x` onwards
+
+    Args:
+        message: string message to be logged out
+        cause: short human-readable description of the cause of the error
+        resolution: short human-readable instructions for manual solutions to the error (optional)
+    """
+
+    def __init__(self, message: str, cause: str, resolution: Optional[str] = None):
+        super().__init__(message, cause=cause, resolution=resolution)
+
+
+class DependencyError(UpgradeError):
+    """Exception flagging that some new `dependency` is not being met.
+
+    For example, new version requires related App version `2.x`, but currently is `1.x`
+
+    Args:
+        message: string message to be logged out
+        cause: short human-readable description of the cause of the error
+        resolution: short human-readable instructions for manual solutions to the error (optional)
+    """
+
+    def __init__(self, message: str, cause: str, resolution: Optional[str] = None):
+        super().__init__(message, cause=cause, resolution=resolution)
+
+
+# --- CUSTOM EVENTS ---
+
+
+class UpgradeGrantedEvent(EventBase):
+    """Used to tell units that they can process an upgrade."""
+
+
+class UpgradeFinishedEvent(EventBase):
+    """Used to tell units that they finished the upgrade."""
+
+
+class UpgradeEvents(CharmEvents):
+    """Upgrade events.
+
+    This class defines the events that the lib can emit.
+    """
+
+    upgrade_granted = EventSource(UpgradeGrantedEvent)
+    upgrade_finished = EventSource(UpgradeFinishedEvent)
+
+
+# --- EVENT HANDLER ---
+
+
+class DataUpgrade(Object, ABC):
+    """Manages `upgrade` relation operations for in-place upgrades."""
+
+    STATES = ["recovery", "failed", "idle", "ready", "upgrading", "completed"]
+
+    on = UpgradeEvents()  # pyright: ignore [reportGeneralTypeIssues]
+
+    def __init__(
+        self,
+        charm: CharmBase,
+        dependency_model: BaseModel,
+        relation_name: str = "upgrade",
+        substrate: Literal["vm", "k8s"] = "vm",
+    ):
+        super().__init__(charm, relation_name)
+        self.charm = charm
+        self.dependency_model = dependency_model
+        self.relation_name = relation_name
+        self.substrate = substrate
+        self._upgrade_stack = None
+
+        # events
+        self.framework.observe(
+            self.charm.on[relation_name].relation_created, self._on_upgrade_created
+        )
+        self.framework.observe(
+            self.charm.on[relation_name].relation_changed, self.on_upgrade_changed
+        )
+        self.framework.observe(self.charm.on.upgrade_charm, self._on_upgrade_charm)
+        self.framework.observe(getattr(self.on, "upgrade_granted"), self._on_upgrade_granted)
+        self.framework.observe(getattr(self.on, "upgrade_finished"), self._on_upgrade_finished)
+
+        # actions
+        self.framework.observe(
+            getattr(self.charm.on, "pre_upgrade_check_action"), self._on_pre_upgrade_check_action
+        )
+        if self.substrate == "k8s":
+            self.framework.observe(
+                getattr(self.charm.on, "resume_upgrade_action"), self._on_resume_upgrade_action
+            )
+
+    @property
+    def peer_relation(self) -> Optional[Relation]:
+        """The upgrade peer relation."""
+        return self.charm.model.get_relation(self.relation_name)
+
+    @property
+    def app_units(self) -> Set[Unit]:
+        """The peer-related units in the application."""
+        if not self.peer_relation:
+            return set()
+
+        return set([self.charm.unit] + list(self.peer_relation.units))
+
+    @property
+    def state(self) -> Optional[str]:
+        """The unit state from the upgrade peer relation."""
+        if not self.peer_relation:
+            return None
+
+        return self.peer_relation.data[self.charm.unit].get("state", None)
+
+    @property
+    def stored_dependencies(self) -> Optional[BaseModel]:
+        """The application dependencies from the upgrade peer relation."""
+        if not self.peer_relation:
+            return None
+
+        if not (deps := self.peer_relation.data[self.charm.app].get("dependencies", "")):
+            return None
+
+        return type(self.dependency_model)(**json.loads(deps))
+
+    @property
+    def upgrade_stack(self) -> Optional[List[int]]:
+        """Gets the upgrade stack from the upgrade peer relation.
+
+        Unit.ids are ordered Last-In-First-Out (LIFO).
+            i.e unit.id at index `-1` is the first unit to upgrade.
+            unit.id at index `0` is the last unit to upgrade.
+
+        Returns:
+            List of integer unit.ids, ordered in upgrade order in a stack
+        """
+        if not self.peer_relation:
+            return None
+
+        # lazy-load
+        if self._upgrade_stack is None:
+            self._upgrade_stack = (
+                json.loads(self.peer_relation.data[self.charm.app].get("upgrade-stack", "[]"))
+                or None
+            )
+
+        return self._upgrade_stack
+
+    @upgrade_stack.setter
+    def upgrade_stack(self, stack: List[int]) -> None:
+        """Sets the upgrade stack to the upgrade peer relation.
+
+        Unit.ids are ordered Last-In-First-Out (LIFO).
+            i.e unit.id at index `-1` is the first unit to upgrade.
+            unit.id at index `0` is the last unit to upgrade.
+        """
+        if not self.peer_relation:
+            return
+
+        self.peer_relation.data[self.charm.app].update({"upgrade-stack": json.dumps(stack)})
+        self._upgrade_stack = stack
+
+    @property
+    def unit_states(self) -> list:
+        """Current upgrade state for all units.
+
+        Returns:
+            Unsorted list of upgrade states for all units.
+        """
+        if not self.peer_relation:
+            return []
+
+        return [self.peer_relation.data[unit].get("state", "") for unit in self.app_units]
+
+    @property
+    def cluster_state(self) -> Optional[str]:
+        """Current upgrade state for cluster units.
+
+        Determined from :class:`DataUpgrade.STATE`, taking the lowest ordinal unit state.
+
+        For example, if units in have states: `["ready", "upgrading", "completed"]`,
+            the overall state for the cluster is `ready`.
+
+        Returns:
+            String of upgrade state from the furthest behind unit.
+        """
+        if not self.unit_states:
+            return None
+
+        try:
+            return sorted(self.unit_states, key=self.STATES.index)[0]
+        except (ValueError, KeyError):
+            return None
+
+    @property
+    def idle(self) -> Optional[bool]:
+        """Flag for whether the cluster is in an idle upgrade state.
+
+        Returns:
+            True if all application units in idle state. Otherwise False
+        """
+        return set(self.unit_states) == {"idle"}
+
+    @abstractmethod
+    def pre_upgrade_check(self) -> None:
+        """Runs necessary checks validating the cluster is in a healthy state to upgrade.
+
+        Called by all units during :meth:`_on_pre_upgrade_check_action`.
+
+        Raises:
+            :class:`ClusterNotReadyError`: if cluster is not ready to upgrade
+        """
+        pass
+
+    def build_upgrade_stack(self) -> List[int]:
+        """Builds ordered iterable of all application unit.ids to upgrade in.
+
+        Called by leader unit during :meth:`_on_pre_upgrade_check_action`.
+
+        Returns:
+            Iterable of integer unit.ids, LIFO ordered in upgrade order
+                i.e `[5, 2, 4, 1, 3]`, unit `3` upgrades first, `5` upgrades last
+        """
+        # don't raise if k8s substrate, uses default statefulset order
+        if self.substrate == "k8s":
+            return []
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def log_rollback_instructions(self) -> None:
+        """Sets charm state and logs out rollback instructions.
+
+        Called by all units when `state=failed` found during :meth:`_on_upgrade_changed`.
+        """
+        pass
+
+    def _repair_upgrade_stack(self) -> None:
+        """Ensures completed units are re-added to the upgrade-stack after failure."""
+        # need to update the stack as it was not refreshed by rollback run of pre-upgrade-check
+        # avoids difficult health check implementation by charm-authors needing to exclude dead units
+
+        # if the first unit in the stack fails, the stack will be the same length as units
+        # i.e this block not ran
+        if (
+            self.cluster_state in ["failed", "recovery"]
+            and self.upgrade_stack
+            and len(self.upgrade_stack) != len(self.app_units)
+            and self.charm.unit.is_leader()
+        ):
+            new_stack = self.upgrade_stack
+            for unit in self.app_units:
+                unit_id = int(unit.name.split("/")[1])
+
+                # if a unit fails, it rolls back first
+                if unit_id not in new_stack:
+                    new_stack.insert(-1, unit_id)
+                    logger.debug(f"Inserted {unit_id} in to upgrade-stack - {new_stack}")
+
+            self.upgrade_stack = new_stack
+
+    def set_unit_failed(self, cause: Optional[str] = None) -> None:
+        """Sets unit `state=failed` to the upgrade peer data.
+
+        Args:
+            cause: short description of cause of failure
+        """
+        if not self.peer_relation:
+            return None
+
+        # needed to refresh the stack
+        # now leader pulls a fresh stack from newly updated relation data
+        if self.charm.unit.is_leader():
+            self._upgrade_stack = None
+
+        self.charm.unit.status = BlockedStatus(cause if cause else "")
+        self.peer_relation.data[self.charm.unit].update({"state": "failed"})
+        self.log_rollback_instructions()
+
+    def set_unit_completed(self) -> None:
+        """Sets unit `state=completed` to the upgrade peer data."""
+        if not self.peer_relation:
+            return None
+
+        # needed to refresh the stack
+        # now leader pulls a fresh stack from newly updated relation data
+        if self.charm.unit.is_leader():
+            self._upgrade_stack = None
+
+        self.charm.unit.status = MaintenanceStatus("upgrade completed")
+        self.peer_relation.data[self.charm.unit].update({"state": "completed"})
+
+        # Emit upgrade_finished event to run unit's post upgrade operations.
+        if self.substrate == "k8s":
+            logger.debug(
+                f"{self.charm.unit.name} has completed the upgrade, emitting `upgrade_finished` event..."
+            )
+            getattr(self.on, "upgrade_finished").emit()
+
+    def _on_upgrade_created(self, event: RelationCreatedEvent) -> None:
+        """Handler for `upgrade-relation-created` events."""
+        if not self.peer_relation:
+            event.defer()
+            return
+
+        # setting initial idle state needed to avoid execution on upgrade-changed events
+        self.peer_relation.data[self.charm.unit].update({"state": "idle"})
+
+        if self.charm.unit.is_leader():
+            logger.debug("Persisting dependencies to upgrade relation data...")
+            self.peer_relation.data[self.charm.app].update(
+                {"dependencies": json.dumps(self.dependency_model.dict())}
+            )
+
+    def _on_pre_upgrade_check_action(self, event: ActionEvent) -> None:
+        """Handler for `pre-upgrade-check-action` events."""
+        if not self.peer_relation:
+            event.fail(message="Could not find upgrade relation.")
+            return
+
+        if not self.charm.unit.is_leader():
+            event.fail(message="Action must be ran on the Juju leader.")
+            return
+
+        if self.cluster_state == "failed":
+            logger.info("Entering recovery state for rolling-back to previous version...")
+            self._repair_upgrade_stack()
+            self.charm.unit.status = BlockedStatus("ready to rollback application")
+            self.peer_relation.data[self.charm.unit].update({"state": "recovery"})
+            return
+
+        # checking if upgrade in progress
+        if self.cluster_state != "idle":
+            event.fail("Cannot run pre-upgrade checks, cluster already upgrading.")
+            return
+
+        try:
+            logger.info("Running pre-upgrade-check...")
+            self.pre_upgrade_check()
+
+            if self.substrate == "k8s":
+                logger.info("Building upgrade-stack for K8s...")
+                built_upgrade_stack = sorted(
+                    [int(unit.name.split("/")[1]) for unit in self.app_units]
+                )
+            else:
+                logger.info("Building upgrade-stack for VMs...")
+                built_upgrade_stack = self.build_upgrade_stack()
+
+            logger.debug(f"Built upgrade stack of {built_upgrade_stack}")
+
+        except ClusterNotReadyError as e:
+            logger.error(e)
+            event.fail(message=e.message)
+            return
+        except Exception as e:
+            logger.error(e)
+            event.fail(message="Unknown error found.")
+            return
+
+        logger.info("Setting upgrade-stack to relation data...")
+        self.upgrade_stack = built_upgrade_stack
+
+    def _on_resume_upgrade_action(self, event: ActionEvent) -> None:
+        """Handle resume upgrade action.
+
+        Continue the upgrade by setting the partition to the next unit.
+        """
+        if not self.peer_relation:
+            event.fail(message="Could not find upgrade relation.")
+            return
+
+        if not self.charm.unit.is_leader():
+            event.fail(message="Action must be ran on the Juju leader.")
+            return
+
+        if not self.upgrade_stack:
+            event.fail(message="Nothing to resume, upgrade stack unset.")
+            return
+
+        # Check whether this is being run after juju refresh was called
+        # (the size of the upgrade stack should match the number of total
+        # unit minus one).
+        if len(self.upgrade_stack) != len(self.peer_relation.units):
+            event.fail(message="Upgrade can be resumed only once after juju refresh is called.")
+            return
+
+        try:
+            next_partition = self.upgrade_stack[-1]
+            self._set_rolling_update_partition(partition=next_partition)
+            event.set_results({"message": f"Upgrade will resume on unit {next_partition}"})
+        except KubernetesClientError:
+            event.fail(message="Cannot set rolling update partition.")
+
+    def _upgrade_supported_check(self) -> None:
+        """Checks if previous versions can be upgraded to new versions.
+
+        Raises:
+            :class:`VersionError` if upgrading to existing `version` is not supported
+        """
+        keys = self.dependency_model.__fields__.keys()
+
+        compatible = True
+        incompatibilities: List[Tuple[str, str, str, str]] = []
+        for key in keys:
+            old_dep: DependencyModel = getattr(self.stored_dependencies, key)
+            new_dep: DependencyModel = getattr(self.dependency_model, key)
+
+            if not old_dep.can_upgrade(dependency=new_dep):
+                compatible = False
+                incompatibilities.append(
+                    (key, old_dep.version, new_dep.version, new_dep.upgrade_supported)
+                )
+
+        base_message = "Versions incompatible"
+        base_cause = "Upgrades only supported for specific versions"
+        if not compatible:
+            for incompat in incompatibilities:
+                base_message += (
+                    f", {incompat[0]} {incompat[1]} can not be upgraded to {incompat[2]}"
+                )
+                base_cause += f", {incompat[0]} versions satisfying requirement {incompat[3]}"
+
+            raise VersionError(
+                message=base_message,
+                cause=base_cause,
+            )
+
+    def _on_upgrade_charm(self, event: UpgradeCharmEvent) -> None:
+        """Handler for `upgrade-charm` events."""
+        # defer if not all units have pre-upgraded
+        if not self.peer_relation:
+            event.defer()
+            return
+
+        if not self.upgrade_stack:
+            logger.error("Cluster upgrade failed, ensure pre-upgrade checks are ran first.")
+            return
+
+        if self.substrate == "vm":
+            # for VM run version checks on leader only
+            if self.charm.unit.is_leader():
+                try:
+                    self._upgrade_supported_check()
+                except VersionError as e:  # not ready if not passed check
+                    logger.error(e)
+                    self.set_unit_failed()
+                    return
+            self.charm.unit.status = WaitingStatus("other units upgrading first...")
+            self.peer_relation.data[self.charm.unit].update({"state": "ready"})
+
+        else:
+            # for k8s run version checks only on highest ordinal unit
+            if (
+                self.charm.unit.name
+                == f"{self.charm.app.name}/{self.charm.app.planned_units() -1}"
+            ):
+                try:
+                    self._upgrade_supported_check()
+                except VersionError as e:  # not ready if not passed check
+                    logger.error(e)
+                    self.set_unit_failed()
+                    return
+            # On K8s an unit that receives the upgrade-charm event is upgrading
+            self.charm.unit.status = MaintenanceStatus("upgrading unit")
+            self.peer_relation.data[self.charm.unit].update({"state": "upgrading"})
+
+    def on_upgrade_changed(self, event: EventBase) -> None:
+        """Handler for `upgrade-relation-changed` events."""
+        if not self.peer_relation:
+            return
+
+        # if any other unit failed, don't continue with upgrade
+        if self.cluster_state == "failed":
+            logger.debug("Cluster failed to upgrade, exiting...")
+            return
+
+        if self.substrate == "vm" and self.cluster_state == "recovery":
+            # Only defer for vm, that will set unit states to "ready" on upgrade-charm
+            # on k8s only the upgrading unit will receive the upgrade-charm event
+            # and deferring will prevent the upgrade stack from being popped
+            logger.debug("Cluster in recovery, deferring...")
+            event.defer()
+            return
+
+        # if all units completed, mark as complete
+        if not self.upgrade_stack:
+            if self.state == "completed" and self.cluster_state in ["idle", "completed"]:
+                logger.info("All units completed upgrade, setting idle upgrade state...")
+                self.charm.unit.status = ActiveStatus()
+                self.peer_relation.data[self.charm.unit].update({"state": "idle"})
+
+                if self.charm.unit.is_leader():
+                    logger.debug("Persisting new dependencies to upgrade relation data...")
+                    self.peer_relation.data[self.charm.app].update(
+                        {"dependencies": json.dumps(self.dependency_model.dict())}
+                    )
+                return
+
+            if self.cluster_state == "idle":
+                logger.debug("upgrade-changed event handled before pre-checks, exiting...")
+                return
+
+            logger.debug("Did not find upgrade-stack or completed cluster state, skipping...")
+            return
+
+        # upgrade ongoing, set status for waiting units
+        if "upgrading" in self.unit_states and self.state in ["idle", "ready"]:
+            self.charm.unit.status = WaitingStatus("other units upgrading first...")
+
+        # pop mutates the `upgrade_stack` attr
+        top_unit_id = self.upgrade_stack.pop()
+        top_unit = self.charm.model.get_unit(f"{self.charm.app.name}/{top_unit_id}")
+        top_state = self.peer_relation.data[top_unit].get("state")
+
+        # if top of stack is completed, leader pops it
+        if self.charm.unit.is_leader() and top_state == "completed":
+            logger.debug(f"{top_unit} has finished upgrading, updating stack...")
+
+            # writes the mutated attr back to rel data
+            self.peer_relation.data[self.charm.app].update(
+                {"upgrade-stack": json.dumps(self.upgrade_stack)}
+            )
+
+            # recurse on leader to ensure relation changed event not lost
+            # in case leader is next or the last unit to complete
+            self.on_upgrade_changed(event)
+
+        # if unit top of stack and all units ready (i.e stack), emit granted event
+        if (
+            self.charm.unit == top_unit
+            and top_state in ["ready", "upgrading"]
+            and self.cluster_state == "ready"
+        ):
+            logger.debug(
+                f"{top_unit.name} is next to upgrade, emitting `upgrade_granted` event and upgrading..."
+            )
+            self.charm.unit.status = MaintenanceStatus("upgrading...")
+            self.peer_relation.data[self.charm.unit].update({"state": "upgrading"})
+
+            try:
+                getattr(self.on, "upgrade_granted").emit()
+            except DependencyError as e:
+                logger.error(e)
+                self.set_unit_failed()
+                return
+
+    def _on_upgrade_granted(self, event: UpgradeGrantedEvent) -> None:
+        """Handler for `upgrade-granted` events.
+
+        Handlers of this event must meet the following:
+            - SHOULD check for related application deps from :class:`DataUpgrade.dependencies`
+                - MAY raise :class:`DependencyError` if dependency not met
+            - MUST update unit `state` after validating the success of the upgrade, calling one of:
+                - :class:`DataUpgrade.set_unit_failed` if the unit upgrade fails
+                - :class:`DataUpgrade.set_unit_completed` if the unit upgrade succeeds
+            - MUST call :class:`DataUpgarde.on_upgrade_changed` on exit so event not lost on leader
+        """
+        # don't raise if k8s substrate, only return
+        if self.substrate == "k8s":
+            return
+
+        raise NotImplementedError
+
+    def _on_upgrade_finished(self, _) -> None:
+        """Handler for `upgrade-finished` events."""
+        if self.substrate == "vm" or not self.peer_relation:
+            return
+
+        # Emit the upgrade relation changed event in the leader to update the upgrade_stack.
+        if self.charm.unit.is_leader():
+            self.charm.on[self.relation_name].relation_changed.emit(
+                self.model.get_relation(self.relation_name)
+            )
+
+        # This hook shouldn't run for the last unit (the first that is upgraded). For that unit it
+        # should be done through an action after the upgrade success on that unit is double-checked.
+        unit_number = int(self.charm.unit.name.split("/")[1])
+        if unit_number == len(self.peer_relation.units):
+            logger.info(
+                f"{self.charm.unit.name} unit upgraded. Evaluate and run `resume-upgrade` action to continue upgrade"
+            )
+            return
+
+        # Also, the hook shouldn't run for the first unit (the last that is upgraded).
+        if unit_number == 0:
+            logger.info(f"{self.charm.unit.name} unit upgraded. Upgrade is complete")
+            return
+
+        try:
+            # Use the unit number instead of the upgrade stack to avoid race conditions
+            # (i.e. the leader updates the upgrade stack after this hook runs).
+            next_partition = unit_number - 1
+            logger.debug(f"Set rolling update partition to unit {next_partition}")
+            self._set_rolling_update_partition(partition=next_partition)
+        except KubernetesClientError:
+            logger.exception("Cannot set rolling update partition")
+            self.set_unit_failed()
+            self.log_rollback_instructions()
+
+    def _set_rolling_update_partition(self, partition: int) -> None:
+        """Patch the StatefulSet's `spec.updateStrategy.rollingUpdate.partition`.
+
+        Args:
+            partition: partition to set.
+
+        K8s only. It should decrement the rolling update strategy partition by using a code
+        like the following:
+
+            from lightkube.core.client import Client
+            from lightkube.core.exceptions import ApiError
+            from lightkube.resources.apps_v1 import StatefulSet
+
+            try:
+                patch = {"spec": {"updateStrategy": {"rollingUpdate": {"partition": partition}}}}
+                Client().patch(StatefulSet, name=self.charm.model.app.name, namespace=self.charm.model.name, obj=patch)
+                logger.debug(f"Kubernetes StatefulSet partition set to {partition}")
+            except ApiError as e:
+                if e.status.code == 403:
+                    cause = "`juju trust` needed"
+                else:
+                    cause = str(e)
+                raise KubernetesClientError("Kubernetes StatefulSet patch failed", cause)
+        """
+        if self.substrate == "vm":
+            return
+
+        raise NotImplementedError
diff --git a/metadata.yaml b/metadata.yaml
index 244e59ea4..94c873d1c 100644
--- a/metadata.yaml
+++ b/metadata.yaml
@@ -63,3 +63,5 @@ requires:
 peers:
   pgb-peers:
     interface: pgb_peers
+  upgrade:
+    interface: upgrade
diff --git a/poetry.lock b/poetry.lock
index 2a0b79d52..32fdf8730 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -554,13 +554,13 @@ tests = ["asttokens (>=2.1.0)", "coverage", "coverage-enable-subprocess", "ipyth
 
 [[package]]
 name = "google-auth"
-version = "2.23.2"
+version = "2.23.3"
 description = "Google Authentication Library"
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "google-auth-2.23.2.tar.gz", hash = "sha256:5a9af4be520ba33651471a0264eead312521566f44631cbb621164bc30c8fd40"},
-    {file = "google_auth-2.23.2-py2.py3-none-any.whl", hash = "sha256:c2e253347579d483004f17c3bd0bf92e611ef6c7ba24d41c5c59f2e7aeeaf088"},
+    {file = "google-auth-2.23.3.tar.gz", hash = "sha256:6864247895eea5d13b9c57c9e03abb49cb94ce2dc7c58e91cba3248c7477c9e3"},
+    {file = "google_auth-2.23.3-py2.py3-none-any.whl", hash = "sha256:a8f4608e65c244ead9e0538f181a96c6e11199ec114d41f1d7b1bffa96937bda"},
 ]
 
 [package.dependencies]
@@ -1150,6 +1150,17 @@ files = [
 dev = ["pre-commit", "tox"]
 testing = ["pytest", "pytest-benchmark"]
 
+[[package]]
+name = "poetry-core"
+version = "1.7.0"
+description = "Poetry PEP 517 Build Backend"
+optional = false
+python-versions = ">=3.8,<4.0"
+files = [
+    {file = "poetry_core-1.7.0-py3-none-any.whl", hash = "sha256:38e174cdb00a84ee4a1cab66a378b435747f72414f5573bc18cfc3850a94df38"},
+    {file = "poetry_core-1.7.0.tar.gz", hash = "sha256:8f679b83bd9c820082637beca1204124d5d2a786e4818da47ec8acefd0353b74"},
+]
+
 [[package]]
 name = "prompt-toolkit"
 version = "3.0.39"
@@ -1276,6 +1287,58 @@ files = [
     {file = "pycparser-2.21.tar.gz", hash = "sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"},
 ]
 
+[[package]]
+name = "pydantic"
+version = "1.10.13"
+description = "Data validation and settings management using python type hints"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "pydantic-1.10.13-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:efff03cc7a4f29d9009d1c96ceb1e7a70a65cfe86e89d34e4a5f2ab1e5693737"},
+    {file = "pydantic-1.10.13-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:3ecea2b9d80e5333303eeb77e180b90e95eea8f765d08c3d278cd56b00345d01"},
+    {file = "pydantic-1.10.13-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1740068fd8e2ef6eb27a20e5651df000978edce6da6803c2bef0bc74540f9548"},
+    {file = "pydantic-1.10.13-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:84bafe2e60b5e78bc64a2941b4c071a4b7404c5c907f5f5a99b0139781e69ed8"},
+    {file = "pydantic-1.10.13-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:bc0898c12f8e9c97f6cd44c0ed70d55749eaf783716896960b4ecce2edfd2d69"},
+    {file = "pydantic-1.10.13-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:654db58ae399fe6434e55325a2c3e959836bd17a6f6a0b6ca8107ea0571d2e17"},
+    {file = "pydantic-1.10.13-cp310-cp310-win_amd64.whl", hash = "sha256:75ac15385a3534d887a99c713aa3da88a30fbd6204a5cd0dc4dab3d770b9bd2f"},
+    {file = "pydantic-1.10.13-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:c553f6a156deb868ba38a23cf0df886c63492e9257f60a79c0fd8e7173537653"},
+    {file = "pydantic-1.10.13-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:5e08865bc6464df8c7d61439ef4439829e3ab62ab1669cddea8dd00cd74b9ffe"},
+    {file = "pydantic-1.10.13-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e31647d85a2013d926ce60b84f9dd5300d44535a9941fe825dc349ae1f760df9"},
+    {file = "pydantic-1.10.13-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:210ce042e8f6f7c01168b2d84d4c9eb2b009fe7bf572c2266e235edf14bacd80"},
+    {file = "pydantic-1.10.13-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:8ae5dd6b721459bfa30805f4c25880e0dd78fc5b5879f9f7a692196ddcb5a580"},
+    {file = "pydantic-1.10.13-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:f8e81fc5fb17dae698f52bdd1c4f18b6ca674d7068242b2aff075f588301bbb0"},
+    {file = "pydantic-1.10.13-cp311-cp311-win_amd64.whl", hash = "sha256:61d9dce220447fb74f45e73d7ff3b530e25db30192ad8d425166d43c5deb6df0"},
+    {file = "pydantic-1.10.13-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:4b03e42ec20286f052490423682016fd80fda830d8e4119f8ab13ec7464c0132"},
+    {file = "pydantic-1.10.13-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f59ef915cac80275245824e9d771ee939133be38215555e9dc90c6cb148aaeb5"},
+    {file = "pydantic-1.10.13-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:5a1f9f747851338933942db7af7b6ee8268568ef2ed86c4185c6ef4402e80ba8"},
+    {file = "pydantic-1.10.13-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:97cce3ae7341f7620a0ba5ef6cf043975cd9d2b81f3aa5f4ea37928269bc1b87"},
+    {file = "pydantic-1.10.13-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:854223752ba81e3abf663d685f105c64150873cc6f5d0c01d3e3220bcff7d36f"},
+    {file = "pydantic-1.10.13-cp37-cp37m-win_amd64.whl", hash = "sha256:b97c1fac8c49be29486df85968682b0afa77e1b809aff74b83081cc115e52f33"},
+    {file = "pydantic-1.10.13-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:c958d053453a1c4b1c2062b05cd42d9d5c8eb67537b8d5a7e3c3032943ecd261"},
+    {file = "pydantic-1.10.13-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:4c5370a7edaac06daee3af1c8b1192e305bc102abcbf2a92374b5bc793818599"},
+    {file = "pydantic-1.10.13-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7d6f6e7305244bddb4414ba7094ce910560c907bdfa3501e9db1a7fd7eaea127"},
+    {file = "pydantic-1.10.13-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d3a3c792a58e1622667a2837512099eac62490cdfd63bd407993aaf200a4cf1f"},
+    {file = "pydantic-1.10.13-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:c636925f38b8db208e09d344c7aa4f29a86bb9947495dd6b6d376ad10334fb78"},
+    {file = "pydantic-1.10.13-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:678bcf5591b63cc917100dc50ab6caebe597ac67e8c9ccb75e698f66038ea953"},
+    {file = "pydantic-1.10.13-cp38-cp38-win_amd64.whl", hash = "sha256:6cf25c1a65c27923a17b3da28a0bdb99f62ee04230c931d83e888012851f4e7f"},
+    {file = "pydantic-1.10.13-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:8ef467901d7a41fa0ca6db9ae3ec0021e3f657ce2c208e98cd511f3161c762c6"},
+    {file = "pydantic-1.10.13-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:968ac42970f57b8344ee08837b62f6ee6f53c33f603547a55571c954a4225691"},
+    {file = "pydantic-1.10.13-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9849f031cf8a2f0a928fe885e5a04b08006d6d41876b8bbd2fc68a18f9f2e3fd"},
+    {file = "pydantic-1.10.13-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:56e3ff861c3b9c6857579de282ce8baabf443f42ffba355bf070770ed63e11e1"},
+    {file = "pydantic-1.10.13-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:9f00790179497767aae6bcdc36355792c79e7bbb20b145ff449700eb076c5f96"},
+    {file = "pydantic-1.10.13-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:75b297827b59bc229cac1a23a2f7a4ac0031068e5be0ce385be1462e7e17a35d"},
+    {file = "pydantic-1.10.13-cp39-cp39-win_amd64.whl", hash = "sha256:e70ca129d2053fb8b728ee7d1af8e553a928d7e301a311094b8a0501adc8763d"},
+    {file = "pydantic-1.10.13-py3-none-any.whl", hash = "sha256:b87326822e71bd5f313e7d3bfdc77ac3247035ac10b0c0618bd99dcf95b1e687"},
+    {file = "pydantic-1.10.13.tar.gz", hash = "sha256:32c8b48dcd3b2ac4e78b0ba4af3a2c2eb6048cb75202f0ea7b34feb740efc340"},
+]
+
+[package.dependencies]
+typing-extensions = ">=4.2.0"
+
+[package.extras]
+dotenv = ["python-dotenv (>=0.10.4)"]
+email = ["email-validator (>=1.0.3)"]
+
 [[package]]
 name = "pygments"
 version = "2.16.1"
@@ -1534,108 +1597,110 @@ rsa = ["oauthlib[signedtoken] (>=3.0.0)"]
 
 [[package]]
 name = "rpds-py"
-version = "0.10.3"
+version = "0.10.4"
 description = "Python bindings to Rust's persistent data structures (rpds)"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "rpds_py-0.10.3-cp310-cp310-macosx_10_7_x86_64.whl", hash = "sha256:485747ee62da83366a44fbba963c5fe017860ad408ccd6cd99aa66ea80d32b2e"},
-    {file = "rpds_py-0.10.3-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:c55f9821f88e8bee4b7a72c82cfb5ecd22b6aad04033334f33c329b29bfa4da0"},
-    {file = "rpds_py-0.10.3-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d3b52a67ac66a3a64a7e710ba629f62d1e26ca0504c29ee8cbd99b97df7079a8"},
-    {file = "rpds_py-0.10.3-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3aed39db2f0ace76faa94f465d4234aac72e2f32b009f15da6492a561b3bbebd"},
-    {file = "rpds_py-0.10.3-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:271c360fdc464fe6a75f13ea0c08ddf71a321f4c55fc20a3fe62ea3ef09df7d9"},
-    {file = "rpds_py-0.10.3-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ef5fddfb264e89c435be4adb3953cef5d2936fdeb4463b4161a6ba2f22e7b740"},
-    {file = "rpds_py-0.10.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a771417c9c06c56c9d53d11a5b084d1de75de82978e23c544270ab25e7c066ff"},
-    {file = "rpds_py-0.10.3-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:52b5cbc0469328e58180021138207e6ec91d7ca2e037d3549cc9e34e2187330a"},
-    {file = "rpds_py-0.10.3-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:6ac3fefb0d168c7c6cab24fdfc80ec62cd2b4dfd9e65b84bdceb1cb01d385c33"},
-    {file = "rpds_py-0.10.3-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:8d54bbdf5d56e2c8cf81a1857250f3ea132de77af543d0ba5dce667183b61fec"},
-    {file = "rpds_py-0.10.3-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:cd2163f42868865597d89399a01aa33b7594ce8e2c4a28503127c81a2f17784e"},
-    {file = "rpds_py-0.10.3-cp310-none-win32.whl", hash = "sha256:ea93163472db26ac6043e8f7f93a05d9b59e0505c760da2a3cd22c7dd7111391"},
-    {file = "rpds_py-0.10.3-cp310-none-win_amd64.whl", hash = "sha256:7cd020b1fb41e3ab7716d4d2c3972d4588fdfbab9bfbbb64acc7078eccef8860"},
-    {file = "rpds_py-0.10.3-cp311-cp311-macosx_10_7_x86_64.whl", hash = "sha256:1d9b5ee46dcb498fa3e46d4dfabcb531e1f2e76b477e0d99ef114f17bbd38453"},
-    {file = "rpds_py-0.10.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:563646d74a4b4456d0cf3b714ca522e725243c603e8254ad85c3b59b7c0c4bf0"},
-    {file = "rpds_py-0.10.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e626b864725680cd3904414d72e7b0bd81c0e5b2b53a5b30b4273034253bb41f"},
-    {file = "rpds_py-0.10.3-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:485301ee56ce87a51ccb182a4b180d852c5cb2b3cb3a82f7d4714b4141119d8c"},
-    {file = "rpds_py-0.10.3-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:42f712b4668831c0cd85e0a5b5a308700fe068e37dcd24c0062904c4e372b093"},
-    {file = "rpds_py-0.10.3-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6c9141af27a4e5819d74d67d227d5047a20fa3c7d4d9df43037a955b4c748ec5"},
-    {file = "rpds_py-0.10.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ef750a20de1b65657a1425f77c525b0183eac63fe7b8f5ac0dd16f3668d3e64f"},
-    {file = "rpds_py-0.10.3-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e1a0ffc39f51aa5f5c22114a8f1906b3c17eba68c5babb86c5f77d8b1bba14d1"},
-    {file = "rpds_py-0.10.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:f4c179a7aeae10ddf44c6bac87938134c1379c49c884529f090f9bf05566c836"},
-    {file = "rpds_py-0.10.3-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:176287bb998fd1e9846a9b666e240e58f8d3373e3bf87e7642f15af5405187b8"},
-    {file = "rpds_py-0.10.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:6446002739ca29249f0beaaf067fcbc2b5aab4bc7ee8fb941bd194947ce19aff"},
-    {file = "rpds_py-0.10.3-cp311-none-win32.whl", hash = "sha256:c7aed97f2e676561416c927b063802c8a6285e9b55e1b83213dfd99a8f4f9e48"},
-    {file = "rpds_py-0.10.3-cp311-none-win_amd64.whl", hash = "sha256:8bd01ff4032abaed03f2db702fa9a61078bee37add0bd884a6190b05e63b028c"},
-    {file = "rpds_py-0.10.3-cp312-cp312-macosx_10_7_x86_64.whl", hash = "sha256:4cf0855a842c5b5c391dd32ca273b09e86abf8367572073bd1edfc52bc44446b"},
-    {file = "rpds_py-0.10.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:69b857a7d8bd4f5d6e0db4086da8c46309a26e8cefdfc778c0c5cc17d4b11e08"},
-    {file = "rpds_py-0.10.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:975382d9aa90dc59253d6a83a5ca72e07f4ada3ae3d6c0575ced513db322b8ec"},
-    {file = "rpds_py-0.10.3-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:35fbd23c1c8732cde7a94abe7fb071ec173c2f58c0bd0d7e5b669fdfc80a2c7b"},
-    {file = "rpds_py-0.10.3-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:106af1653007cc569d5fbb5f08c6648a49fe4de74c2df814e234e282ebc06957"},
-    {file = "rpds_py-0.10.3-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ce5e7504db95b76fc89055c7f41e367eaadef5b1d059e27e1d6eabf2b55ca314"},
-    {file = "rpds_py-0.10.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5aca759ada6b1967fcfd4336dcf460d02a8a23e6abe06e90ea7881e5c22c4de6"},
-    {file = "rpds_py-0.10.3-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:b5d4bdd697195f3876d134101c40c7d06d46c6ab25159ed5cbd44105c715278a"},
-    {file = "rpds_py-0.10.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:a657250807b6efd19b28f5922520ae002a54cb43c2401e6f3d0230c352564d25"},
-    {file = "rpds_py-0.10.3-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:177c9dd834cdf4dc39c27436ade6fdf9fe81484758885f2d616d5d03c0a83bd2"},
-    {file = "rpds_py-0.10.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:e22491d25f97199fc3581ad8dd8ce198d8c8fdb8dae80dea3512e1ce6d5fa99f"},
-    {file = "rpds_py-0.10.3-cp38-cp38-macosx_10_7_x86_64.whl", hash = "sha256:2f3e1867dd574014253b4b8f01ba443b9c914e61d45f3674e452a915d6e929a3"},
-    {file = "rpds_py-0.10.3-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:c22211c165166de6683de8136229721f3d5c8606cc2c3d1562da9a3a5058049c"},
-    {file = "rpds_py-0.10.3-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:40bc802a696887b14c002edd43c18082cb7b6f9ee8b838239b03b56574d97f71"},
-    {file = "rpds_py-0.10.3-cp38-cp38-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5e271dd97c7bb8eefda5cca38cd0b0373a1fea50f71e8071376b46968582af9b"},
-    {file = "rpds_py-0.10.3-cp38-cp38-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:95cde244e7195b2c07ec9b73fa4c5026d4a27233451485caa1cd0c1b55f26dbd"},
-    {file = "rpds_py-0.10.3-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:08a80cf4884920863623a9ee9a285ee04cef57ebedc1cc87b3e3e0f24c8acfe5"},
-    {file = "rpds_py-0.10.3-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:763ad59e105fca09705d9f9b29ecffb95ecdc3b0363be3bb56081b2c6de7977a"},
-    {file = "rpds_py-0.10.3-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:187700668c018a7e76e89424b7c1042f317c8df9161f00c0c903c82b0a8cac5c"},
-    {file = "rpds_py-0.10.3-cp38-cp38-musllinux_1_2_aarch64.whl", hash = "sha256:5267cfda873ad62591b9332fd9472d2409f7cf02a34a9c9cb367e2c0255994bf"},
-    {file = "rpds_py-0.10.3-cp38-cp38-musllinux_1_2_i686.whl", hash = "sha256:2ed83d53a8c5902ec48b90b2ac045e28e1698c0bea9441af9409fc844dc79496"},
-    {file = "rpds_py-0.10.3-cp38-cp38-musllinux_1_2_x86_64.whl", hash = "sha256:255f1a10ae39b52122cce26ce0781f7a616f502feecce9e616976f6a87992d6b"},
-    {file = "rpds_py-0.10.3-cp38-none-win32.whl", hash = "sha256:a019a344312d0b1f429c00d49c3be62fa273d4a1094e1b224f403716b6d03be1"},
-    {file = "rpds_py-0.10.3-cp38-none-win_amd64.whl", hash = "sha256:efb9ece97e696bb56e31166a9dd7919f8f0c6b31967b454718c6509f29ef6fee"},
-    {file = "rpds_py-0.10.3-cp39-cp39-macosx_10_7_x86_64.whl", hash = "sha256:570cc326e78ff23dec7f41487aa9c3dffd02e5ee9ab43a8f6ccc3df8f9327623"},
-    {file = "rpds_py-0.10.3-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:cff7351c251c7546407827b6a37bcef6416304fc54d12d44dbfecbb717064717"},
-    {file = "rpds_py-0.10.3-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:177914f81f66c86c012311f8c7f46887ec375cfcfd2a2f28233a3053ac93a569"},
-    {file = "rpds_py-0.10.3-cp39-cp39-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:448a66b8266de0b581246ca7cd6a73b8d98d15100fb7165974535fa3b577340e"},
-    {file = "rpds_py-0.10.3-cp39-cp39-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:3bbac1953c17252f9cc675bb19372444aadf0179b5df575ac4b56faaec9f6294"},
-    {file = "rpds_py-0.10.3-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9dd9d9d9e898b9d30683bdd2b6c1849449158647d1049a125879cb397ee9cd12"},
-    {file = "rpds_py-0.10.3-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e8c71ea77536149e36c4c784f6d420ffd20bea041e3ba21ed021cb40ce58e2c9"},
-    {file = "rpds_py-0.10.3-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:16a472300bc6c83fe4c2072cc22b3972f90d718d56f241adabc7ae509f53f154"},
-    {file = "rpds_py-0.10.3-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:b9255e7165083de7c1d605e818025e8860636348f34a79d84ec533546064f07e"},
-    {file = "rpds_py-0.10.3-cp39-cp39-musllinux_1_2_i686.whl", hash = "sha256:53d7a3cd46cdc1689296348cb05ffd4f4280035770aee0c8ead3bbd4d6529acc"},
-    {file = "rpds_py-0.10.3-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:22da15b902f9f8e267020d1c8bcfc4831ca646fecb60254f7bc71763569f56b1"},
-    {file = "rpds_py-0.10.3-cp39-none-win32.whl", hash = "sha256:850c272e0e0d1a5c5d73b1b7871b0a7c2446b304cec55ccdb3eaac0d792bb065"},
-    {file = "rpds_py-0.10.3-cp39-none-win_amd64.whl", hash = "sha256:de61e424062173b4f70eec07e12469edde7e17fa180019a2a0d75c13a5c5dc57"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-macosx_10_7_x86_64.whl", hash = "sha256:af247fd4f12cca4129c1b82090244ea5a9d5bb089e9a82feb5a2f7c6a9fe181d"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:3ad59efe24a4d54c2742929001f2d02803aafc15d6d781c21379e3f7f66ec842"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:642ed0a209ced4be3a46f8cb094f2d76f1f479e2a1ceca6de6346a096cd3409d"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:37d0c59548ae56fae01c14998918d04ee0d5d3277363c10208eef8c4e2b68ed6"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:aad6ed9e70ddfb34d849b761fb243be58c735be6a9265b9060d6ddb77751e3e8"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8f94fdd756ba1f79f988855d948ae0bad9ddf44df296770d9a58c774cfbcca72"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:77076bdc8776a2b029e1e6ffbe6d7056e35f56f5e80d9dc0bad26ad4a024a762"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:87d9b206b1bd7a0523375dc2020a6ce88bca5330682ae2fe25e86fd5d45cea9c"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:8efaeb08ede95066da3a3e3c420fcc0a21693fcd0c4396d0585b019613d28515"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-musllinux_1_2_i686.whl", hash = "sha256:a4d9bfda3f84fc563868fe25ca160c8ff0e69bc4443c5647f960d59400ce6557"},
-    {file = "rpds_py-0.10.3-pp310-pypy310_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:d27aa6bbc1f33be920bb7adbb95581452cdf23005d5611b29a12bb6a3468cc95"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-macosx_10_7_x86_64.whl", hash = "sha256:ed8313809571a5463fd7db43aaca68ecb43ca7a58f5b23b6e6c6c5d02bdc7882"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-macosx_11_0_arm64.whl", hash = "sha256:e10e6a1ed2b8661201e79dff5531f8ad4cdd83548a0f81c95cf79b3184b20c33"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:015de2ce2af1586ff5dc873e804434185199a15f7d96920ce67e50604592cae9"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ae87137951bb3dc08c7d8bfb8988d8c119f3230731b08a71146e84aaa919a7a9"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:0bb4f48bd0dd18eebe826395e6a48b7331291078a879295bae4e5d053be50d4c"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:09362f86ec201288d5687d1dc476b07bf39c08478cde837cb710b302864e7ec9"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:821392559d37759caa67d622d0d2994c7a3f2fb29274948ac799d496d92bca73"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7170cbde4070dc3c77dec82abf86f3b210633d4f89550fa0ad2d4b549a05572a"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:5de11c041486681ce854c814844f4ce3282b6ea1656faae19208ebe09d31c5b8"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-musllinux_1_2_i686.whl", hash = "sha256:4ed172d0c79f156c1b954e99c03bc2e3033c17efce8dd1a7c781bc4d5793dfac"},
-    {file = "rpds_py-0.10.3-pp38-pypy38_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:11fdd1192240dda8d6c5d18a06146e9045cb7e3ba7c06de6973000ff035df7c6"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-macosx_10_7_x86_64.whl", hash = "sha256:f602881d80ee4228a2355c68da6b296a296cd22bbb91e5418d54577bbf17fa7c"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-macosx_11_0_arm64.whl", hash = "sha256:691d50c99a937709ac4c4cd570d959a006bd6a6d970a484c84cc99543d4a5bbb"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:24cd91a03543a0f8d09cb18d1cb27df80a84b5553d2bd94cba5979ef6af5c6e7"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fc2200e79d75b5238c8d69f6a30f8284290c777039d331e7340b6c17cad24a5a"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ea65b59882d5fa8c74a23f8960db579e5e341534934f43f3b18ec1839b893e41"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:829e91f3a8574888b73e7a3feb3b1af698e717513597e23136ff4eba0bc8387a"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:eab75a8569a095f2ad470b342f2751d9902f7944704f0571c8af46bede438475"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:061c3ff1f51ecec256e916cf71cc01f9975af8fb3af9b94d3c0cc8702cfea637"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:39d05e65f23a0fe897b6ac395f2a8d48c56ac0f583f5d663e0afec1da89b95da"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-musllinux_1_2_i686.whl", hash = "sha256:4eca20917a06d2fca7628ef3c8b94a8c358f6b43f1a621c9815243462dcccf97"},
-    {file = "rpds_py-0.10.3-pp39-pypy39_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:e8d0f0eca087630d58b8c662085529781fd5dc80f0a54eda42d5c9029f812599"},
-    {file = "rpds_py-0.10.3.tar.gz", hash = "sha256:fcc1ebb7561a3e24a6588f7c6ded15d80aec22c66a070c757559b57b17ffd1cb"},
+    {file = "rpds_py-0.10.4-cp310-cp310-macosx_10_7_x86_64.whl", hash = "sha256:e41824343c2c129599645373992b1ce17720bb8a514f04ff9567031e1c26951e"},
+    {file = "rpds_py-0.10.4-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:b9d8884d58ea8801e5906a491ab34af975091af76d1a389173db491ee7e316bb"},
+    {file = "rpds_py-0.10.4-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5db93f9017b384a4f194e1d89e1ce82d0a41b1fafdbbd3e0c8912baf13f2950f"},
+    {file = "rpds_py-0.10.4-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c31ecfc53ac03dad4928a1712f3a2893008bfba1b3cde49e1c14ff67faae2290"},
+    {file = "rpds_py-0.10.4-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4f92d2372ec992c82fd7c74aa21e2a1910b3dcdc6a7e6392919a138f21d528a3"},
+    {file = "rpds_py-0.10.4-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f7ea49ddf51d5ec0c3cbd95190dd15e077a3153c8d4b22a33da43b5dd2b3c640"},
+    {file = "rpds_py-0.10.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1c27942722cd5039bbf5098c7e21935a96243fed00ea11a9589f3c6c6424bd84"},
+    {file = "rpds_py-0.10.4-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:08f07150c8ebbdbce1d2d51b8e9f4d588749a2af6a98035485ebe45c7ad9394e"},
+    {file = "rpds_py-0.10.4-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:f3331a3684192659fa1090bf2b448db928152fcba08222e58106f44758ef25f7"},
+    {file = "rpds_py-0.10.4-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:efffa359cc69840c8793f0c05a7b663de6afa7b9078fa6c80309ee38b9db677d"},
+    {file = "rpds_py-0.10.4-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:86e8d6ff15fa7a9590c0addaf3ce52fb58bda4299cab2c2d0afa404db6848dab"},
+    {file = "rpds_py-0.10.4-cp310-none-win32.whl", hash = "sha256:8f90fc6dd505867514c8b8ef68a712dc0be90031a773c1ae2ad469f04062daef"},
+    {file = "rpds_py-0.10.4-cp310-none-win_amd64.whl", hash = "sha256:9f9184744fb800c9f28e155a5896ecb54816296ee79d5d1978be6a2ae60f53c4"},
+    {file = "rpds_py-0.10.4-cp311-cp311-macosx_10_7_x86_64.whl", hash = "sha256:72e9b1e92830c876cd49565d8404e4dcc9928302d348ea2517bc3f9e3a873a2a"},
+    {file = "rpds_py-0.10.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:3650eae998dc718960e90120eb45d42bd57b18b21b10cb9ee05f91bff2345d48"},
+    {file = "rpds_py-0.10.4-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f40413d2859737ce6d95c29ce2dde0ef7cdc3063b5830ae4342fef5922c3bba7"},
+    {file = "rpds_py-0.10.4-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:b953d11b544ca5f2705bb77b177d8e17ab1bfd69e0fd99790a11549d2302258c"},
+    {file = "rpds_py-0.10.4-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:28b4942ec7d9d6114c1e08cace0157db92ef674636a38093cab779ace5742d3a"},
+    {file = "rpds_py-0.10.4-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2e0e2e01c5f61ddf47e3ed2d1fe1c9136e780ca6222d57a2517b9b02afd4710c"},
+    {file = "rpds_py-0.10.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:927e3461dae0c09b1f2e0066e50c1a9204f8a64a3060f596e9a6742d3b307785"},
+    {file = "rpds_py-0.10.4-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8e69bbe0ede8f7fe2616e779421bbdb37f025c802335a90f6416e4d98b368a37"},
+    {file = "rpds_py-0.10.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:cc688a59c100f038fa9fec9e4ab457c2e2d1fca350fe7ea395016666f0d0a2dc"},
+    {file = "rpds_py-0.10.4-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:ec001689402b9104700b50a005c2d3d0218eae90eaa8bdbbd776fe78fe8a74b7"},
+    {file = "rpds_py-0.10.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:628fbb8be71a103499d10b189af7764996ab2634ed7b44b423f1e19901606e0e"},
+    {file = "rpds_py-0.10.4-cp311-none-win32.whl", hash = "sha256:e3f9c9e5dd8eba4768e15f19044e1b5e216929a43a54b4ab329e103aed9f3eda"},
+    {file = "rpds_py-0.10.4-cp311-none-win_amd64.whl", hash = "sha256:3bc561c183684636c0099f9c3fbab8c1671841942edbce784bb01b4707d17924"},
+    {file = "rpds_py-0.10.4-cp312-cp312-macosx_10_7_x86_64.whl", hash = "sha256:36ff30385fb9fb3ac23a28bffdd4a230a5229ed5b15704b708b7c84bfb7fce51"},
+    {file = "rpds_py-0.10.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:db0589e0bf41ff6ce284ab045ca89f27be1adf19e7bce26c2e7de6739a70c18b"},
+    {file = "rpds_py-0.10.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a5c330cb125983c5d380fef4a4155248a276297c86d64625fdaf500157e1981c"},
+    {file = "rpds_py-0.10.4-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d230fddc60caced271cc038e43e6fb8f4dd6b2dbaa44ac9763f2d76d05b0365a"},
+    {file = "rpds_py-0.10.4-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2a9e864ec051a58fdb6bb2e6da03942adb20273897bc70067aee283e62bbac4d"},
+    {file = "rpds_py-0.10.4-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5e41d5b334e8de4bc3f38843f31b2afa9a0c472ebf73119d3fd55cde08974bdf"},
+    {file = "rpds_py-0.10.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5bb3f3cb6072c73e6ec1f865d8b80419b599f1597acf33f63fbf02252aab5a03"},
+    {file = "rpds_py-0.10.4-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:576d48e1e45c211e99fc02655ade65c32a75d3e383ccfd98ce59cece133ed02c"},
+    {file = "rpds_py-0.10.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b28b9668a22ca2cfca4433441ba9acb2899624a323787a509a3dc5fbfa79c49d"},
+    {file = "rpds_py-0.10.4-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:ddbd113a37307638f94be5ae232a325155fd24dbfae2c56455da8724b471e7be"},
+    {file = "rpds_py-0.10.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:bd0ad98c7d72b0e4cbfe89cdfa12cd07d2fd6ed22864341cdce12b318a383442"},
+    {file = "rpds_py-0.10.4-cp312-none-win32.whl", hash = "sha256:2a97406d5e08b7095428f01dac0d3c091dc072351151945a167e7968d2755559"},
+    {file = "rpds_py-0.10.4-cp312-none-win_amd64.whl", hash = "sha256:aab24b9bbaa3d49e666e9309556591aa00748bd24ea74257a405f7fed9e8b10d"},
+    {file = "rpds_py-0.10.4-cp38-cp38-macosx_10_7_x86_64.whl", hash = "sha256:6c5ca3eb817fb54bfd066740b64a2b31536eb8fe0b183dc35b09a7bd628ed680"},
+    {file = "rpds_py-0.10.4-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:fd37ab9a24021821b715478357af1cf369d5a42ac7405e83e5822be00732f463"},
+    {file = "rpds_py-0.10.4-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2573ec23ad3a59dd2bc622befac845695972f3f2d08dc1a4405d017d20a6c225"},
+    {file = "rpds_py-0.10.4-cp38-cp38-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:362faeae52dc6ccc50c0b6a01fa2ec0830bb61c292033f3749a46040b876f4ba"},
+    {file = "rpds_py-0.10.4-cp38-cp38-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:40f6e53461b19ddbb3354fe5bcf3d50d4333604ae4bf25b478333d83ca68002c"},
+    {file = "rpds_py-0.10.4-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6090ba604ea06b525a231450ae5d343917a393cbf50423900dea968daf61d16f"},
+    {file = "rpds_py-0.10.4-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:28e29dac59df890972f73c511948072897f512974714a803fe793635b80ff8c7"},
+    {file = "rpds_py-0.10.4-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:f82abb5c5b83dc30e96be99ce76239a030b62a73a13c64410e429660a5602bfd"},
+    {file = "rpds_py-0.10.4-cp38-cp38-musllinux_1_2_aarch64.whl", hash = "sha256:a3628815fd170a64624001bfb4e28946fd515bd672e68a1902d9e0290186eaf3"},
+    {file = "rpds_py-0.10.4-cp38-cp38-musllinux_1_2_i686.whl", hash = "sha256:d37f27ad80f742ef82796af3fe091888864958ad0bc8bab03da1830fa00c6004"},
+    {file = "rpds_py-0.10.4-cp38-cp38-musllinux_1_2_x86_64.whl", hash = "sha256:255a23bded80605e9f3997753e3a4b89c9aec9efb07ec036b1ca81440efcc1a9"},
+    {file = "rpds_py-0.10.4-cp38-none-win32.whl", hash = "sha256:049098dabfe705e9638c55a3321137a821399c50940041a6fcce267a22c70db2"},
+    {file = "rpds_py-0.10.4-cp38-none-win_amd64.whl", hash = "sha256:aa45cc71bf23a3181b8aa62466b5a2b7b7fb90fdc01df67ca433cd4fce7ec94d"},
+    {file = "rpds_py-0.10.4-cp39-cp39-macosx_10_7_x86_64.whl", hash = "sha256:3507c459767cf24c11e9520e2a37c89674266abe8e65453e5cb66398aa47ee7b"},
+    {file = "rpds_py-0.10.4-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:2603e084054351cc65097da326570102c4c5bd07426ba8471ceaefdb0b642cc9"},
+    {file = "rpds_py-0.10.4-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b0f1d336786cb62613c72c00578c98e5bb8cd57b49c5bae5d4ab906ca7872f98"},
+    {file = "rpds_py-0.10.4-cp39-cp39-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bf032367f921201deaecf221d4cc895ea84b3decf50a9c73ee106f961885a0ad"},
+    {file = "rpds_py-0.10.4-cp39-cp39-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:7f050ceffd8c730c1619a16bbf0b9cd037dcdb94b54710928ba38c7bde67e4a4"},
+    {file = "rpds_py-0.10.4-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8709eb4ab477c533b7d0a76cd3065d7d95c9e25e6b9f6e27caeeb8c63e8799c9"},
+    {file = "rpds_py-0.10.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fc20dadb102140dff63529e08ce6f9745dbd36e673ebb2b1c4a63e134bca81c2"},
+    {file = "rpds_py-0.10.4-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:cd7da2adc721ccf19ac7ec86cae3a4fcaba03d9c477d5bd64ded6e9bb817bf3f"},
+    {file = "rpds_py-0.10.4-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:e5dba1c11e089b526379e74f6c636202e4c5bad9a48c7416502b8a5b0d026c91"},
+    {file = "rpds_py-0.10.4-cp39-cp39-musllinux_1_2_i686.whl", hash = "sha256:ffd539d213c1ea2989ab92a5b9371ae7159c8c03cf2bcb9f2f594752f755ecd3"},
+    {file = "rpds_py-0.10.4-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:e791e3d13b14d0a7921804d0efe4d7bd15508bbcf8cb7a0c1ee1a27319a5f033"},
+    {file = "rpds_py-0.10.4-cp39-none-win32.whl", hash = "sha256:2f2ac8bb01f705c5caaa7fe77ffd9b03f92f1b5061b94228f6ea5eaa0fca68ad"},
+    {file = "rpds_py-0.10.4-cp39-none-win_amd64.whl", hash = "sha256:7c7ca791bedda059e5195cf7c6b77384657a51429357cdd23e64ac1d4973d6dc"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-macosx_10_7_x86_64.whl", hash = "sha256:9c7e7bd1fa1f535af71dfcd3700fc83a6dc261a1204f8f5327d8ffe82e52905d"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:7089d8bfa8064b28b2e39f5af7bf12d42f61caed884e35b9b4ea9e6fb1175077"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f1f191befea279cb9669b57be97ab1785781c8bab805900e95742ebfaa9cbf1d"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:98c0aecf661c175ce9cb17347fc51a5c98c3e9189ca57e8fcd9348dae18541db"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d81359911c3bb31c899c6a5c23b403bdc0279215e5b3bc0d2a692489fed38632"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:83da147124499fe41ed86edf34b4e81e951b3fe28edcc46288aac24e8a5c8484"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:49db6c0a0e6626c2b97f5e7f8f7074da21cbd8ec73340c25e839a2457c007efa"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:125776d5db15162fdd9135372bef7fe4fb7c5f5810cf25898eb74a06a0816aec"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:32819b662e3b4c26355a4403ea2f60c0a00db45b640fe722dd12db3d2ef807fb"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-musllinux_1_2_i686.whl", hash = "sha256:3bd38b80491ef9686f719c1ad3d24d14fbd0e069988fdd4e7d1a6ffcdd7f4a13"},
+    {file = "rpds_py-0.10.4-pp310-pypy310_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:2e79eeeff8394284b09577f36316d410525e0cf0133abb3de10660e704d3d38e"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-macosx_10_7_x86_64.whl", hash = "sha256:3e37f1f134037601eb4b1f46854194f0cc082435dac2ee3de11e51529f7831f2"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-macosx_11_0_arm64.whl", hash = "sha256:ba3246c60303eab3d0e562addf25a983d60bddc36f4d1edc2510f056d19df255"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9123ba0f3f98ff79780eebca9984a2b525f88563844b740f94cffb9099701230"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d98802b78093c7083cc51f83da41a5be5a57d406798c9f69424bd75f8ae0812a"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:58bae860d1d116e6b4e1aad0cdc48a187d5893994f56d26db0c5534df7a47afd"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cd7e62e7d5bcfa38a62d8397fba6d0428b970ab7954c2197501cd1624f7f0bbb"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ac83f5228459b84fa6279e4126a53abfdd73cd9cc183947ee5084153880f65d7"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:4bcb1abecd998a72ad4e36a0fca93577fd0c059a6aacc44f16247031b98f6ff4"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:9e7b3ad9f53ea9e085b3d27286dd13f8290969c0a153f8a52c8b5c46002c374b"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-musllinux_1_2_i686.whl", hash = "sha256:cbec8e43cace64e63398155dc585dc479a89fef1e57ead06c22d3441e1bd09c3"},
+    {file = "rpds_py-0.10.4-pp38-pypy38_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:ad21c60fc880204798f320387164dcacc25818a7b4ec2a0bf6b6c1d57b007d23"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-macosx_10_7_x86_64.whl", hash = "sha256:6baea8a4f6f01e69e75cfdef3edd4a4d1c4b56238febbdf123ce96d09fbff010"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-macosx_11_0_arm64.whl", hash = "sha256:94876c21512535955a960f42a155213315e6ab06a4ce8ce372341a2a1b143eeb"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4cb55454a20d1b935f9eaab52e6ceab624a2efd8b52927c7ae7a43e02828dbe0"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:13cbd79ccedc6b39c279af31ebfb0aec0467ad5d14641ddb15738bf6e4146157"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:00a88003db3cc953f8656b59fc9af9d0637a1fb93c235814007988f8c153b2f2"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d0f7f77a77c37159c9f417b8dd847f67a29e98c6acb52ee98fc6b91efbd1b2b6"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:70563a1596d2e0660ca2cebb738443437fc0e38597e7cbb276de0a7363924a52"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e3ece9aa6d07e18c966f14b4352a4c6f40249f6174d3d2c694c1062e19c6adbb"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:d5ad7b1a1f6964d19b1a8acfc14bf7864f39587b3e25c16ca04f6cd1815026b3"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-musllinux_1_2_i686.whl", hash = "sha256:60018626e637528a1fa64bb3a2b3e46ab7bf672052316d61c3629814d5e65052"},
+    {file = "rpds_py-0.10.4-pp39-pypy39_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:ae8a32ab77a84cc870bbfb60645851ca0f7d58fd251085ad67464b1445d632ca"},
+    {file = "rpds_py-0.10.4.tar.gz", hash = "sha256:18d5ff7fbd305a1d564273e9eb22de83ae3cd9cd6329fddc8f12f6428a711a6a"},
 ]
 
 [[package]]
@@ -1840,13 +1905,13 @@ files = [
 
 [[package]]
 name = "websocket-client"
-version = "1.6.3"
+version = "1.6.4"
 description = "WebSocket client for Python with low level API options"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "websocket-client-1.6.3.tar.gz", hash = "sha256:3aad25d31284266bcfcfd1fd8a743f63282305a364b8d0948a43bd606acc652f"},
-    {file = "websocket_client-1.6.3-py3-none-any.whl", hash = "sha256:6cfc30d051ebabb73a5fa246efdcc14c8fbebbd0330f8984ac3bb6d9edd2ad03"},
+    {file = "websocket-client-1.6.4.tar.gz", hash = "sha256:b3324019b3c28572086c4a319f91d1dcd44e6e11cd340232978c684a7650d0df"},
+    {file = "websocket_client-1.6.4-py3-none-any.whl", hash = "sha256:084072e0a7f5f347ef2ac3d8698a5e0b4ffbfcab607628cadabc650fc9a83a24"},
 ]
 
 [package.extras]
@@ -2012,4 +2077,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8.10"
-content-hash = "1ea0e748459fe81ed35e4c591b62657dfdd492216ae604816e02d1d7026445a9"
+content-hash = "8df25ec6ae226f49ed1a20319f92e92d1d0a15d6038c25ed2d1096775d986f16"
diff --git a/pyproject.toml b/pyproject.toml
index c4ddc592f..483ba7d76 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -18,6 +18,10 @@ cryptography = "41.0.4"
 jsonschema = "4.19.1"
 tenacity = "8.2.3"
 cosl = "0.0.7"
+poetry-core = "1.7.0"
+lightkube = "0.14.0"
+lightkube-models = "1.28.1.4"
+pydantic = "1.10.13"
 # psycopg2 = "^2.9.5" # Injected in charmcraft.yaml
 
 [tool.poetry.group.format]
diff --git a/requirements.txt b/requirements.txt
index c675db2b5..391f7270f 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,16 +1,28 @@
+anyio==4.0.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 attrs==23.1.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+certifi==2023.7.22 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 cffi==1.16.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 cosl==0.0.7 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 cryptography==41.0.4 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+exceptiongroup==1.1.3 ; python_full_version >= "3.8.10" and python_version < "3.11"
+h11==0.14.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+httpcore==0.18.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+httpx==0.25.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+idna==3.4 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 importlib-resources==6.1.0 ; python_full_version >= "3.8.10" and python_version < "3.9"
 jsonschema-specifications==2023.7.1 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 jsonschema==4.19.1 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+lightkube-models==1.28.1.4 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+lightkube==0.14.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 ops==2.7.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 pkgutil-resolve-name==1.3.10 ; python_full_version >= "3.8.10" and python_version < "3.9"
+poetry-core==1.7.0 ; python_full_version >= "3.8.10" and python_version < "4.0"
 pycparser==2.21 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+pydantic==1.10.13 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 pyyaml==6.0.1 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 referencing==0.30.2 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 rpds-py==0.10.4 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
+sniffio==1.3.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 tenacity==8.2.3 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 typing-extensions==4.8.0 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
 websocket-client==1.6.4 ; python_full_version >= "3.8.10" and python_full_version < "4.0.0"
diff --git a/src/charm.py b/src/charm.py
index 3b2fd2a4d..3ae72ba99 100755
--- a/src/charm.py
+++ b/src/charm.py
@@ -54,6 +54,7 @@
 from relations.db import DbProvides
 from relations.peers import Peers
 from relations.pgbouncer_provider import PgBouncerProvider
+from upgrade import PgbouncerUpgrade, get_pgbouncer_k8s_dependencies_model
 
 logger = logging.getLogger(__name__)
 
@@ -105,6 +106,13 @@ def __init__(self, *args):
             container_name="pgbouncer",
         )
 
+        self.upgrade = PgbouncerUpgrade(
+            self,
+            model=get_pgbouncer_k8s_dependencies_model(),
+            relation_name="upgrade",
+            substrate="k8s",
+        )
+
     # =======================
     #  Charm Lifecycle Hooks
     # =======================
diff --git a/src/dependency.json b/src/dependency.json
new file mode 100644
index 000000000..39ea07119
--- /dev/null
+++ b/src/dependency.json
@@ -0,0 +1,14 @@
+{
+  "charm": {
+    "dependencies": {},
+    "name": "pgbouncer",
+    "upgrade_supported": ">0",
+    "version": "1"
+  },
+  "rock": {
+    "dependencies": {},
+    "name": "charmed-postgresql",
+    "upgrade_supported": "^1",
+    "version": "1.18.0"
+  }
+}
diff --git a/src/relations/backend_database.py b/src/relations/backend_database.py
index d7ff5b970..27eb678b2 100644
--- a/src/relations/backend_database.py
+++ b/src/relations/backend_database.py
@@ -129,7 +129,8 @@ def postgres(self) -> PostgreSQL:
         if not self.relation:
             return None
 
-        databag = self.postgres_databag
+        if not (databag := self.postgres_databag):
+            return None
         endpoint = databag.get("endpoints")
         user = self.database.fetch_relation_field(self.relation.id, "username")
         password = self.database.fetch_relation_field(self.relation.id, "password")
diff --git a/src/upgrade.py b/src/upgrade.py
new file mode 100644
index 000000000..643aaea42
--- /dev/null
+++ b/src/upgrade.py
@@ -0,0 +1,138 @@
+# Copyright 2023 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""Manager for handling Pgbouncer in-place upgrades."""
+
+import json
+import logging
+
+from charms.data_platform_libs.v0.upgrade import (
+    ClusterNotReadyError,
+    DataUpgrade,
+    DependencyModel,
+    KubernetesClientError,
+)
+from lightkube.core.client import Client
+from lightkube.core.exceptions import ApiError
+from lightkube.resources.apps_v1 import StatefulSet
+from ops.charm import WorkloadEvent
+from ops.pebble import ConnectionError
+from pydantic import BaseModel
+from typing_extensions import override
+
+DEFAULT_MESSAGE = "Pre-upgrade check failed and cannot safely upgrade"
+
+logger = logging.getLogger(__name__)
+
+
+class PgbouncerDependencyModel(BaseModel):
+    """Model for Pgbouncer Operator dependencies."""
+
+    charm: DependencyModel
+    rock: DependencyModel
+
+
+def get_pgbouncer_k8s_dependencies_model() -> PgbouncerDependencyModel:
+    """Return the Pgbouncer dependencies model."""
+    with open("src/dependency.json") as dependency_file:
+        _deps = json.load(dependency_file)
+    return PgbouncerDependencyModel(**_deps)
+
+
+class PgbouncerUpgrade(DataUpgrade):
+    """Implementation of :class:`DataUpgrade` overrides for in-place upgrades."""
+
+    def __init__(self, charm, model: BaseModel, **kwargs):
+        super().__init__(charm, model, **kwargs)
+        self.charm = charm
+
+        self.framework.observe(self.charm.on.upgrade_relation_changed, self._on_upgrade_changed)
+        self.framework.observe(
+            getattr(self.charm.on, "pgbouncer_pebble_ready"), self._on_pgbouncer_pebble_ready
+        )
+
+    def _cluster_checks(self) -> None:
+        """Check that the cluster is in healthy state."""
+        try:
+            if not self.charm.check_pgb_running():
+                raise ClusterNotReadyError(
+                    DEFAULT_MESSAGE, "Not all pgbouncer services are up yet."
+                )
+        except ConnectionError:
+            raise ClusterNotReadyError(DEFAULT_MESSAGE, "Not all pgbouncer services are missing.")
+
+        if self.charm.backend.postgres and not self.charm.backend.ready:
+            raise ClusterNotReadyError(DEFAULT_MESSAGE, "Backend relation is still initialising.")
+
+    @override
+    def pre_upgrade_check(self) -> None:
+        """Runs necessary checks validating the cluster is in a healthy state to upgrade.
+
+        Called by all units during :meth:`_on_pre_upgrade_check_action`.
+
+        Raises:
+            :class:`ClusterNotReadyError`: if cluster is not ready to upgrade.
+        """
+        self._cluster_checks()
+
+        try:
+            self._set_rolling_update_partition(self.charm.app.planned_units() - 1)
+        except KubernetesClientError as e:
+            raise ClusterNotReadyError(e.message, e.cause)
+
+    def _on_pgbouncer_pebble_ready(self, event: WorkloadEvent) -> None:
+        if not self.peer_relation:
+            logger.debug("Deferring on_pebble_ready: no upgrade peer relation yet")
+            event.defer()
+            return
+
+        if self.peer_relation.data[self.charm.unit].get("state") != "upgrading":
+            return
+
+        try:
+            self._cluster_checks()
+        except ClusterNotReadyError:
+            logger.exception("Deferring on_pebble_ready: checks did not pass")
+            event.defer()
+            return
+
+        self.set_unit_completed()
+
+    def _on_upgrade_changed(self, _) -> None:
+        """Rerenders the configuration."""
+        try:
+            if not self.peer_relation or not self.charm.check_pgb_running():
+                return
+        except ConnectionError:
+            logger.debug("on_upgrade_changed early exit: Cannot get pebble services")
+            return
+
+        self.charm.update_config()
+
+    @override
+    def log_rollback_instructions(self) -> None:
+        logger.info(
+            "Run `juju refresh --revision <previous-revision> pgbouncer-k8s` to initiate the rollback"
+        )
+        logger.info(
+            "and `juju run-action pgbouncerl-k8s/leader resume-upgrade` to resume the rollback"
+        )
+
+    @override
+    def _set_rolling_update_partition(self, partition: int) -> None:
+        """Set the rolling update partition to a specific value."""
+        try:
+            patch = {"spec": {"updateStrategy": {"rollingUpdate": {"partition": partition}}}}
+            Client().patch(
+                StatefulSet,
+                name=self.charm.model.app.name,
+                namespace=self.charm.model.name,
+                obj=patch,
+            )
+            logger.debug(f"Kubernetes StatefulSet partition set to {partition}")
+        except ApiError as e:
+            if e.status.code == 403:
+                cause = "`juju trust` needed"
+            else:
+                cause = str(e)
+            raise KubernetesClientError("Kubernetes StatefulSet patch failed", cause)
diff --git a/tests/integration/relations/pgbouncer_provider/test_pgbouncer_provider.py b/tests/integration/relations/pgbouncer_provider/test_pgbouncer_provider.py
index 67bf18778..163492f2c 100644
--- a/tests/integration/relations/pgbouncer_provider/test_pgbouncer_provider.py
+++ b/tests/integration/relations/pgbouncer_provider/test_pgbouncer_provider.py
@@ -73,6 +73,7 @@ async def test_database_relation_with_charm_libraries(ops_test: OpsTest, pgb_cha
             application_name=PGB,
             num_units=2,
             series=CHARM_SERIES,
+            trust=True,
         ),
         ops_test.model.deploy(
             PG,
diff --git a/tests/integration/relations/test_backend_database.py b/tests/integration/relations/test_backend_database.py
index 302f0464a..5dc643068 100644
--- a/tests/integration/relations/test_backend_database.py
+++ b/tests/integration/relations/test_backend_database.py
@@ -52,6 +52,7 @@ async def test_relate_pgbouncer_to_postgres(ops_test: OpsTest, pgb_charm):
                 resources=resources,
                 application_name=PGB,
                 series=CHARM_SERIES,
+                trust=True,
             ),
             # Edge 5 is the new postgres charm
             ops_test.model.deploy(PG, channel="14/edge", trust=True, num_units=3),
diff --git a/tests/integration/relations/test_db.py b/tests/integration/relations/test_db.py
index d8c74d1bc..aa30caac3 100644
--- a/tests/integration/relations/test_db.py
+++ b/tests/integration/relations/test_db.py
@@ -50,6 +50,7 @@ async def test_create_db_legacy_relation(ops_test: OpsTest, pgb_charm):
                 application_name=PGB,
                 num_units=3,
                 series=CHARM_SERIES,
+                trust=True,
             ),
             ops_test.model.deploy(PG, num_units=3, trust=True, channel="14/edge"),
             ops_test.model.deploy("finos-waltz-k8s", application_name=FINOS_WALTZ, channel="edge"),
diff --git a/tests/integration/relations/test_db_admin.py b/tests/integration/relations/test_db_admin.py
index 2dd95d611..0ad58374c 100644
--- a/tests/integration/relations/test_db_admin.py
+++ b/tests/integration/relations/test_db_admin.py
@@ -43,6 +43,7 @@ async def test_create_db_admin_legacy_relation(ops_test: OpsTest, pgb_charm):
                 resources=resources,
                 application_name=PGB,
                 series=CHARM_SERIES,
+                trust=True,
             ),
             ops_test.model.deploy(PG, trust=True, num_units=3, channel="14/edge"),
             ops_test.model.deploy(
diff --git a/tests/integration/relations/test_peers.py b/tests/integration/relations/test_peers.py
index bcc3ffbe3..04fad8570 100644
--- a/tests/integration/relations/test_peers.py
+++ b/tests/integration/relations/test_peers.py
@@ -34,7 +34,12 @@ async def test_deploy_at_scale(ops_test, pgb_charm):
     }
     async with ops_test.fast_forward():
         await ops_test.model.deploy(
-            pgb_charm, resources=resources, application_name=PGB, num_units=3, series=CHARM_SERIES
+            pgb_charm,
+            resources=resources,
+            application_name=PGB,
+            num_units=3,
+            series=CHARM_SERIES,
+            trust=True,
         )
         await ops_test.model.wait_for_idle(
             apps=[PGB], status="blocked", timeout=1000, wait_for_exact_units=3
diff --git a/tests/integration/test_charm.py b/tests/integration/test_charm.py
index fd912a3ae..f037378e4 100644
--- a/tests/integration/test_charm.py
+++ b/tests/integration/test_charm.py
@@ -29,6 +29,7 @@ async def test_build_and_deploy(ops_test: OpsTest, pgb_charm):
             resources=resources,
             application_name=PGB,
             series=CHARM_SERIES,
+            trust=True,
         )
         await ops_test.model.wait_for_idle(apps=[PGB], status="blocked", timeout=1000)
 
diff --git a/tests/integration/test_tls.py b/tests/integration/test_tls.py
index 6b3d6c84d..838b09293 100644
--- a/tests/integration/test_tls.py
+++ b/tests/integration/test_tls.py
@@ -40,6 +40,7 @@ async def test_build_and_deploy(ops_test: OpsTest, pgb_charm):
                 application_name=PGB,
                 num_units=APPLICATION_UNITS,
                 series=CHARM_SERIES,
+                trust=True,
             )
 
     if not await app_name(ops_test, CLIENT_APP_NAME):
diff --git a/tests/integration/test_upgrade.py b/tests/integration/test_upgrade.py
new file mode 100644
index 000000000..2660f1035
--- /dev/null
+++ b/tests/integration/test_upgrade.py
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# Copyright 2023 Canonical Ltd.
+# See LICENSE file for licensing details.
+import asyncio
+import logging
+
+import pytest
+from pytest_operator.plugin import OpsTest
+
+from constants import BACKEND_RELATION_NAME
+
+from .helpers.helpers import (
+    CHARM_SERIES,
+    PG,
+    PGB,
+    PGB_METADATA,
+)
+from .relations.pgbouncer_provider.helpers import check_new_relation
+
+logger = logging.getLogger(__name__)
+
+CLIENT_APP_NAME = "postgresql-test-app"
+SECONDARY_CLIENT_APP_NAME = "secondary-application"
+DATA_INTEGRATOR_APP_NAME = "data-integrator"
+PGB_RESOURCES = {
+    "pgbouncer-image": PGB_METADATA["resources"]["pgbouncer-image"]["upstream-source"]
+}
+APP_NAMES = [CLIENT_APP_NAME, PG, PGB]
+FIRST_DATABASE_RELATION_NAME = "first-database"
+APPLICATION_FIRST_DBNAME = "postgresql_test_app_first_database"
+
+
+@pytest.mark.abort_on_fail
+async def test_in_place_upgrade(ops_test: OpsTest, pgb_charm):
+    """Test basic functionality of database relation interface."""
+    # Deploy both charms (multiple units for each application to test that later they correctly
+    # set data in the relation application databag using only the leader unit).
+    logger.info("Deploying PGB...")
+    await asyncio.gather(
+        ops_test.model.deploy(
+            CLIENT_APP_NAME,
+            application_name=CLIENT_APP_NAME,
+            series=CHARM_SERIES,
+            channel="edge",
+        ),
+        ops_test.model.deploy(
+            pgb_charm,
+            resources=PGB_RESOURCES,
+            application_name=PGB,
+            num_units=2,
+            series=CHARM_SERIES,
+            trust=True,
+        ),
+        ops_test.model.deploy(
+            PG,
+            application_name=PG,
+            num_units=2,
+            channel="14/edge",
+            trust=True,
+        ),
+    )
+    await ops_test.model.add_relation(f"{PGB}:{BACKEND_RELATION_NAME}", f"{PG}:database")
+
+    async with ops_test.fast_forward():
+        await ops_test.model.wait_for_idle(apps=[PGB, PG], status="active")
+
+    # Relate the charms and wait for them exchanging some connection data.
+    global client_relation
+    client_relation = await ops_test.model.add_relation(
+        f"{CLIENT_APP_NAME}:{FIRST_DATABASE_RELATION_NAME}", PGB
+    )
+
+    async with ops_test.fast_forward():
+        await ops_test.model.wait_for_idle(apps=APP_NAMES, status="active", raise_on_blocked=True)
+
+    # This test hasn't passed if we can't pass a tiny amount of data through the new relation
+    await check_new_relation(
+        ops_test,
+        unit_name=ops_test.model.applications[CLIENT_APP_NAME].units[0].name,
+        relation_id=client_relation.id,
+        dbname=APPLICATION_FIRST_DBNAME,
+        relation_name=FIRST_DATABASE_RELATION_NAME,
+    )
+
+    leader = None
+    for unit in ops_test.model.applications[PGB].units:
+        if await unit.is_leader_from_status():
+            leader = unit
+            break
+
+    action = await leader.run_action("pre-upgrade-check")
+    await action.wait()
+
+    await ops_test.model.wait_for_idle(apps=APP_NAMES, status="active", raise_on_blocked=True)
+
+    logger.info("Upgrading last PGB...")
+    await ops_test.model.applications[PGB].refresh(path=pgb_charm)
+    await ops_test.model.wait_for_idle(apps=[PGB], status="active", raise_on_blocked=True)
+
+    logger.info("Resuming upgrade...")
+    action = await leader.run_action("resume-upgrade")
+    await action.wait()
+
+    await ops_test.model.wait_for_idle(apps=[PGB], status="active", raise_on_blocked=True)
+
+    await check_new_relation(
+        ops_test,
+        unit_name=ops_test.model.applications[CLIENT_APP_NAME].units[0].name,
+        relation_id=client_relation.id,
+        dbname=APPLICATION_FIRST_DBNAME,
+        relation_name=FIRST_DATABASE_RELATION_NAME,
+    )
diff --git a/tests/unit/helpers.py b/tests/unit/helpers.py
new file mode 100644
index 000000000..a06010764
--- /dev/null
+++ b/tests/unit/helpers.py
@@ -0,0 +1,25 @@
+# Copyright 2023 Canonical Ltd.
+# See LICENSE file for licensing details.
+from lightkube.core.exceptions import ApiError
+
+
+class _FakeResponse:
+    """Used to fake an httpx response during testing only."""
+
+    def __init__(self, status_code: int):
+        self.status_code = status_code
+
+    def json(self):
+        return {
+            "apiVersion": 1,
+            "code": self.status_code,
+            "message": "broken",
+            "reason": "",
+        }
+
+
+class _FakeApiError(ApiError):
+    """Used to simulate an ApiError during testing."""
+
+    def __init__(self, status_code: int = 400):
+        super().__init__(response=_FakeResponse(status_code))
diff --git a/tests/unit/test_upgrade.py b/tests/unit/test_upgrade.py
new file mode 100644
index 000000000..00ff3078f
--- /dev/null
+++ b/tests/unit/test_upgrade.py
@@ -0,0 +1,145 @@
+# Copyright 2023 Canonical Ltd.
+# See LICENSE file for licensing details.
+import unittest
+from unittest.mock import Mock, PropertyMock, patch
+
+import pytest
+from charms.data_platform_libs.v0.upgrade import ClusterNotReadyError, KubernetesClientError
+from lightkube.resources.apps_v1 import StatefulSet
+from ops.testing import Harness
+
+from charm import PgBouncerK8sCharm
+from tests.unit.helpers import _FakeApiError
+
+
+class TestUpgrade(unittest.TestCase):
+    def setUp(self):
+        self.harness = Harness(PgBouncerK8sCharm)
+        self.addCleanup(self.harness.cleanup)
+        self.harness.begin_with_initial_hooks()
+        self.charm = self.harness.charm
+
+    @patch("charm.PgBouncerK8sCharm.app", new_callable=PropertyMock)
+    @patch("charm.PgbouncerUpgrade._set_rolling_update_partition")
+    @patch("charm.PgBouncerK8sCharm.check_pgb_running")
+    def test_pre_upgrade_check(self, _check_pgb_runnig, _set_partition, _app):
+        _app.return_value.planned_units.return_value = 3
+
+        self.charm.upgrade.pre_upgrade_check()
+
+        _check_pgb_runnig.assert_called_once_with()
+        _set_partition.assert_called_once_with(2)
+
+    @patch("charm.BackendDatabaseRequires.ready", new_callable=PropertyMock, return_value=False)
+    @patch("charm.BackendDatabaseRequires.postgres", new_callable=PropertyMock, return_value=True)
+    @patch("charm.PgBouncerK8sCharm.app", new_callable=PropertyMock)
+    @patch("charm.PgbouncerUpgrade._set_rolling_update_partition")
+    @patch("charm.PgBouncerK8sCharm.check_pgb_running", return_value=False)
+    def test_pre_upgrade_check_cluster_not_ready(
+        self, _check_pgb_runnig: Mock, _set_partition: Mock, _app: Mock, _, _backend_ready: Mock
+    ):
+        _app.return_value.planned_units.return_value = 3
+
+        # PGB is not running
+        with pytest.raises(ClusterNotReadyError):
+            self.charm.upgrade.pre_upgrade_check()
+
+        _check_pgb_runnig.return_value = True
+
+        # Backend is related but not ready
+        with pytest.raises(ClusterNotReadyError):
+            self.charm.upgrade.pre_upgrade_check()
+
+        # Failed patching
+        _backend_ready.return_value = True
+        _set_partition.side_effect = KubernetesClientError("test", "test")
+
+        with pytest.raises(ClusterNotReadyError):
+            self.charm.upgrade.pre_upgrade_check()
+
+        _set_partition.assert_called_once_with(2)
+
+    @patch("charm.PgbouncerUpgrade.set_unit_completed")
+    @patch("charm.PgbouncerUpgrade._cluster_checks")
+    @patch("charm.PgbouncerUpgrade.peer_relation", new_callable=PropertyMock, return_value=None)
+    def test_on_pgbouncer_pebble_ready(
+        self, _peer_relation: Mock, _cluster_checks: Mock, _set_unit_completed: Mock
+    ):
+        event = Mock()
+
+        # Defer if no peers
+        self.charm.upgrade._on_pgbouncer_pebble_ready(event)
+
+        event.defer.assert_called_once_with()
+        event.defer.reset_mock()
+
+        # Early exit if status is not updating
+        _peer_relation.return_value = Mock()
+        _peer_relation.return_value.data = {self.charm.unit: {"state": "testing"}}
+
+        self.charm.upgrade._on_pgbouncer_pebble_ready(event)
+
+        assert event.defer.called is False
+
+        # Run checks if unit is upgrading
+        _peer_relation.return_value.data = {self.charm.unit: {"state": "upgrading"}}
+
+        self.charm.upgrade._on_pgbouncer_pebble_ready(event)
+
+        _cluster_checks.assert_called_once_with()
+        _set_unit_completed.assert_called_once_with()
+        assert event.defer.called is False
+
+        # Defer if checks fail
+        _cluster_checks.side_effect = ClusterNotReadyError("test", "test")
+
+        self.charm.upgrade._on_pgbouncer_pebble_ready(event)
+
+        event.defer.assert_called_once_with()
+
+    @patch("charm.PgBouncerK8sCharm.check_pgb_running", return_value=True)
+    @patch("charm.PgBouncerK8sCharm.update_config")
+    @patch("charm.PgbouncerUpgrade.peer_relation", new_callable=PropertyMock, return_value=None)
+    def test_on_upgrade_changed(self, _peer_relation: Mock, _update_config: Mock, _):
+        # Early exit when no peer
+        self.charm.upgrade._on_upgrade_changed(None)
+
+        assert _update_config.called is False
+
+        # update_config called
+        _peer_relation.return_value = Mock()
+        _peer_relation.return_value.data = {self.charm.unit: {"state": "testing"}}
+
+        self.charm.upgrade._on_upgrade_changed(None)
+
+        _update_config.assert_called_once_with()
+
+    @patch("upgrade.logger.info")
+    def test_log_rollback_instructions(self, _logger: Mock):
+        self.charm.upgrade.log_rollback_instructions()
+
+        assert _logger.call_count == 2
+        _logger.assert_any_call(
+            "Run `juju refresh --revision <previous-revision> pgbouncer-k8s` to initiate the rollback"
+        )
+        _logger.assert_any_call(
+            "and `juju run-action pgbouncerl-k8s/leader resume-upgrade` to resume the rollback"
+        )
+
+    @patch("upgrade.Client")
+    def test_set_rolling_update_partition(self, _k8s_client: Mock):
+        self.charm.upgrade._set_rolling_update_partition(1)
+
+        _k8s_client.return_value.patch.assert_called_once_with(
+            StatefulSet,
+            name="pgbouncer-k8s",
+            namespace=None,
+            obj={"spec": {"updateStrategy": {"rollingUpdate": {"partition": 1}}}},
+        )
+
+    @patch("upgrade.Client")
+    def test_set_rolling_update_partition_api_error(self, _k8s_client: Mock):
+        _k8s_client.return_value.patch.side_effect = _FakeApiError
+
+        with pytest.raises(KubernetesClientError):
+            self.charm.upgrade._set_rolling_update_partition(1)
diff --git a/tox.ini b/tox.ini
index 3515a0bd6..bbec35066 100644
--- a/tox.ini
+++ b/tox.ini
@@ -132,6 +132,17 @@ commands =
     pip install juju=={env:LIBJUJU}
     poetry run pytest -v --tb native --log-cli-level=INFO -s --durations=0 {posargs} {[vars]tests_path}/integration/test_tls.py
 
+[testenv:upgrade-integration-{juju2, juju3}]
+description = Run upgrade integration tests
+pass_env =
+    {[testenv]pass_env}
+    CI
+    CI_PACKED_CHARMS
+commands =
+    poetry install --with integration
+    pip install juju=={env:LIBJUJU}
+    poetry run pytest -v --tb native --log-cli-level=INFO -s --durations=0 {posargs} {[vars]tests_path}/integration/test_upgrade.py
+
 [testenv:poetry-lock]
 description = Install, lock and export poetry dependencies
 commands =