postgresql-charms-single-kernel 16.3.8__tar.gz → 16.3.9__tar.gz

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: postgresql-charms-single-kernel
-Version: 16.3.8
+Version: 16.3.9
 Summary: Shared and reusable code for PostgreSQL-related charms
 Author: Canonical Data Platform
 Author-email: Canonical Data Platform <data-platform@lists.launchpad.net>
@@ -224,6 +224,8 @@ Requires-Dist: tomli ; python_full_version >= '3.12' and extra == 'postgresql'
 Requires-Dist: pydantic>=2.0 ; python_full_version >= '3.12' and extra == 'postgresql'
 Requires-Dist: jinja2>=3.1.6 ; python_full_version >= '3.12' and extra == 'postgresql'
 Requires-Dist: charmlibs-rollingops>=1.1.1 ; python_full_version >= '3.12' and extra == 'postgresql'
+Requires-Dist: boto3>=1.43.85 ; python_full_version >= '3.12' and extra == 'postgresql'
+Requires-Dist: botocore>=1.43.85 ; python_full_version >= '3.12' and extra == 'postgresql'
 Requires-Dist: pysyncobj>=0.3.15 ; python_full_version >= '3.12' and extra == 'vm'
 Requires-Dist: psutil>=7.2.2 ; python_full_version >= '3.12' and extra == 'vm'
 Requires-Dist: charmlibs-snap>=1.0.1 ; python_full_version >= '3.12' and extra == 'vm'

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "postgresql-charms-single-kernel"
 description = "Shared and reusable code for PostgreSQL-related charms"
-version = "16.3.8"
+version = "16.3.9"
 readme = "README.md"
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -33,6 +33,8 @@ postgresql = [
     "pydantic>=2.0; python_version >= '3.12'",
     "jinja2 >=3.1.6; python_version >= '3.12'",
     "charmlibs-rollingops>=1.1.1; python_version >= '3.12'",
+    "boto3>=1.43.85; python_version >= '3.12'",
+    "botocore>=1.43.85; python_version >= '3.12'",
 ]
 vm = [
     "pysyncobj>=0.3.15; python_version >= '3.12'",
@@ -155,12 +157,12 @@ exclude = [
 ]
 
 [dependency-groups]
-format = ["ruff==0.16.3"]
+format = ["ruff==0.16.8"]
 lint = [
     "codespell==2.4.3",
-    "ty==0.0.72",
+    "ty==0.0.82",
 ]
 unit = [
-    "coverage[toml]==7.15.4",
+    "coverage[toml]==7.16.1",
     "pytest==9.1.1",
 ]

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/pyproject.toml.orig

@@ -4,7 +4,7 @@
 [project]
 name = "postgresql-charms-single-kernel"
 description = "Shared and reusable code for PostgreSQL-related charms"
-version = "16.3.8"
+version = "16.3.9"
 readme = "README.md"
 license = {file = "LICENSE"}
 authors = [
@@ -33,6 +33,8 @@ postgresql = [
     "pydantic>=2.0; python_version >= '3.12'",
     "jinja2 >=3.1.6; python_version >= '3.12'",
     "charmlibs-rollingops>=1.1.1; python_version >= '3.12'",
+    "boto3>=1.43.85; python_version >= '3.12'",
+    "botocore>=1.43.85; python_version >= '3.12'",
 ]
 vm = [
     "pysyncobj>=0.3.15; python_version >= '3.12'",
@@ -61,14 +63,14 @@ module-root = ""
 
 [dependency-groups]
 format = [
-    "ruff==0.16.3"
+    "ruff==0.16.8"
 ]
 lint = [
     "codespell==2.4.3",
-    "ty==0.0.72"
+    "ty==0.0.82"
 ]
 unit = [
-    "coverage[toml]==7.15.4",
+    "coverage[toml]==7.16.1",
     "pytest==9.1.1"
 ]
 

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/single_kernel_postgresql/charms/abstract_charm.py

@@ -16,6 +16,7 @@ from single_kernel_postgresql.events.tls import TLS
 from single_kernel_postgresql.lib.charms.data_platform_libs.v0.data_interfaces import (
     DatabaseProvides,
 )
+from single_kernel_postgresql.lib.charms.data_platform_libs.v0.s3 import S3Requirer
 from single_kernel_postgresql.managers.cluster import ClusterManager
 from single_kernel_postgresql.managers.config import ConfigManager
 from single_kernel_postgresql.managers.database import DatabaseManager
@@ -24,7 +25,7 @@ from single_kernel_postgresql.managers.tls import TLSManager
 from single_kernel_postgresql.workload.base import BaseWorkload, ResourceProvider
 
 from ..config.enums import Substrates
-from ..config.literals import DATABASE
+from ..config.literals import DATABASE, S3_RELATION_NAME
 from ..utils.postgresql import PostgreSQL
 
 
@@ -35,7 +36,11 @@ class AbstractPostgreSQLCharm(CharmBase, ABC):
         super().__init__(*args)
 
         # State
-        self.state = CharmState(charm=self, substrate=self.substrate)
+        self.state = CharmState(
+            charm=self,
+            substrate=self.substrate,
+            s3_requirer=S3Requirer(self, relation_name=S3_RELATION_NAME),
+        )
 
         # TLS events handler owns the two certificate requirers; build it before the
         # TLS manager so the manager can constructor-inject them for its live-fetch getters.

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/single_kernel_postgresql/config/exceptions.py

@@ -77,3 +77,15 @@ class UpdateSyncNodeCountError(Exception):
 
 class DeployedWithoutTrustError(Exception):
     """Raised when the K8s API denies access because the app wasn't deployed with --trust."""
+
+
+class StanzaOperationError(PostgreSQLBaseError):
+    """Raised when a pgBackRest stanza-create/check/info operation fails."""
+
+
+class BackupRunError(PostgreSQLBaseError):
+    """Raised when a pgBackRest backup run fails and the logs were uploaded."""
+
+
+class ListBackupsError(PostgreSQLBaseError):
+    """Raised when pgBackRest fails to list backups."""

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/single_kernel_postgresql/config/literals.py

@@ -10,9 +10,13 @@ from typing import Literal
 # Permissions.
 POSTGRESQL_STORAGE_PERMISSIONS = 0o700
 
+# Snap
+POSTGRESQL_SNAP_NAME = "charmed-postgresql"
+
 # Relations
 PEER_RELATION = "database-peers"
 STATUS_PEERS_RELATION = "status-peers"
+S3_RELATION_NAME = "s3-parameters"
 
 # Users.
 BACKUP_USER = "backup"
@@ -25,18 +29,20 @@ SYSTEM_USERS = [BACKUP_USER, MONITORING_USER, REPLICATION_USER, REWIND_USER, USE
 
 # Paths
 ## VM Paths
-BASE_SNAP_DIR = "/var/snap/charmed-postgresql"
+BASE_SNAP_DIR = f"/var/snap/{POSTGRESQL_SNAP_NAME}"
 SNAP_DATA = "current"
 SNAP_COMMON = "common"
-SNAP = "/snap/charmed-postgresql/current"
+SNAP = f"/snap/{POSTGRESQL_SNAP_NAME}/current"
 VM_LOGS_PATH = "var/log/postgresql"
 VM_DATA_PATH = "var/lib/postgresql"
 VM_ARCHIVE_PATH = "data/archive"
 VM_DATA_LOGS_PATH = "data/logs"
 VM_TEMP_PATH = "data/temp"
+VM_PGBACKREST_LOGS_PATH = "var/log/pgbackrest"
 
 ## K8s Paths
 K8S_DATA_PATH = "var/lib/pg/data"
+K8S_PGBACKREST_LOGS_PATH = "16/main/pgbackrest_logs"
 
 ## Shared Paths
 # NOTE: The paths don't have leading slahes since pathops
@@ -179,5 +185,6 @@ RAFT_PORT = 2222
 RAFT_PARTNER_PREFIX = "partner_node_status_server_"
 
 # VM services
-VM_PATRONI_SERVICE_NAME = "snap.charmed-postgresql.patroni.service"
+VM_PATRONI_SERVICE_NAME = f"snap.{POSTGRESQL_SNAP_NAME}.patroni.service"
 VM_PATRONI_SERVICE_DEFAULT_PATH = f"/etc/systemd/system/{VM_PATRONI_SERVICE_NAME}"
+VM_PGBACKREST_SERVICE_NAME = "pgbackrest-service"

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/single_kernel_postgresql/core/peer_relation.py

@@ -72,6 +72,11 @@ class PostgreSQLPeer(RelationState):
         """Returns whether the unit is in a blocked state."""
         return isinstance(self.unit.status, BlockedStatus)
 
+    @property
+    def status_message(self) -> str:
+        """Returns the current unit status message, if any."""
+        return self.unit.status.message
+
     @property
     def internal_cert(self) -> str | None:
         """Get internal certificate.
@@ -225,6 +230,55 @@ class PostgreSQLPeer(RelationState):
             return True
         return self.relation.data[self.unit].get("connectivity", "on") == "on"
 
+    @is_connectivity_enabled.setter
+    def is_connectivity_enabled(self, value: bool) -> None:
+        """Enable or disable external connectivity to this unit."""
+        if not self.relation:
+            return
+        self.relation.data[self.unit]["connectivity"] = "on" if value else "off"
+
+    @property
+    def stanza(self) -> str | None:
+        """Get the pgBackRest stanza name from the unit peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.unit].get("stanza")
+
+    @stanza.setter
+    def stanza(self, value: str) -> None:
+        """Set the pgBackRest stanza name in the unit peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.unit]["stanza"] = value
+
+    @property
+    def s3_initialization_done(self) -> str | None:
+        """Get the s3-initialization-done marker from the unit peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.unit].get("s3-initialization-done")
+
+    @s3_initialization_done.setter
+    def s3_initialization_done(self, value: str) -> None:
+        """Set the s3-initialization-done marker in the unit peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.unit]["s3-initialization-done"] = value
+
+    @property
+    def s3_initialization_block_message(self) -> str | None:
+        """Get the s3 initialization block message from the unit peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.unit].get("s3-initialization-block-message")
+
+    @s3_initialization_block_message.setter
+    def s3_initialization_block_message(self, value: str) -> None:
+        """Set the s3 initialization block message in the unit peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.unit]["s3-initialization-block-message"] = value
+
     @property
     def config_hash(self) -> str | None:
         """Get the last-applied PostgreSQL config hash from the peer relation data."""
@@ -474,6 +528,118 @@ class PostgreSQLApplication(RelationState):
             return
         self.relation.data[self.app]["user_hash"] = value
 
+    @property
+    def stanza(self) -> str | None:
+        """Get the pgBackRest stanza name from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("stanza")
+
+    @stanza.setter
+    def stanza(self, value: str) -> None:
+        """Set the pgBackRest stanza name in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["stanza"] = value
+
+    @property
+    def s3_initialization_start(self) -> str | None:
+        """Get the s3-initialization-start timestamp from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("s3-initialization-start")
+
+    @s3_initialization_start.setter
+    def s3_initialization_start(self, value: str) -> None:
+        """Set the s3-initialization-start timestamp in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["s3-initialization-start"] = value
+
+    @property
+    def s3_initialization_block_message(self) -> str | None:
+        """Get the s3 initialization block message from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("s3-initialization-block-message")
+
+    @s3_initialization_block_message.setter
+    def s3_initialization_block_message(self, value: str) -> None:
+        """Set the s3 initialization block message in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["s3-initialization-block-message"] = value
+
+    @property
+    def s3_initialization_done(self) -> str | None:
+        """Get the s3-initialization-done marker from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("s3-initialization-done")
+
+    @s3_initialization_done.setter
+    def s3_initialization_done(self, value: str) -> None:
+        """Set the s3-initialization-done marker in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["s3-initialization-done"] = value
+
+    @property
+    def restoring_backup(self) -> str | None:
+        """Get the restoring-backup marker from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("restoring-backup")
+
+    @restoring_backup.setter
+    def restoring_backup(self, value: str) -> None:
+        """Set the restoring-backup marker in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["restoring-backup"] = value
+
+    @property
+    def restore_stanza(self) -> str | None:
+        """Get the restore-stanza name from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("restore-stanza")
+
+    @restore_stanza.setter
+    def restore_stanza(self, value: str) -> None:
+        """Set the restore-stanza name in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["restore-stanza"] = value
+
+    @property
+    def restore_timeline(self) -> str | None:
+        """Get the restore-timeline from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("restore-timeline")
+
+    @restore_timeline.setter
+    def restore_timeline(self, value: str) -> None:
+        """Set the restore-timeline in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["restore-timeline"] = value
+
+    @property
+    def restore_to_time(self) -> str | None:
+        """Get the restore-to-time target from the app peer relation data."""
+        if not self.relation:
+            return None
+        return self.relation.data[self.app].get("restore-to-time")
+
+    @restore_to_time.setter
+    def restore_to_time(self, value: str) -> None:
+        """Set the restore-to-time target in the app peer relation data."""
+        if not self.relation:
+            return
+        self.relation.data[self.app]["restore-to-time"] = value
+
     def get_secret(self, key: str) -> str | None:
         """Get the secret value for 'key' from the peer relation data."""
         if not self.relation:

postgresql_charms_single_kernel-16.3.9/single_kernel_postgresql/core/s3.py

@@ -0,0 +1,62 @@
+# Copyright 2026 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""Live-fetch view over the S3 (s3-parameters) relation data."""
+
+import logging
+
+from single_kernel_postgresql.lib.charms.data_platform_libs.v0.s3 import S3Requirer
+
+logger = logging.getLogger(__name__)
+
+
+class S3ConnectionInfo:
+    """Reads and normalizes S3 connection parameters from the s3-parameters relation."""
+
+    def __init__(self, s3_requirer: S3Requirer):
+        """Initialize the S3 connection info with the requirer bound to the relation."""
+        self.s3_requirer = s3_requirer
+
+    def retrieve_s3_parameters(self) -> tuple[dict, list[str]]:
+        """Retrieve S3 parameters from the S3 integrator relation.
+
+        Returns:
+            a tuple of (parameters, missing_required_parameters). If any required
+            parameter is missing, parameters is empty and missing lists the absent
+            keys. Otherwise parameters has defaults applied and values normalized.
+        """
+        s3_parameters = self.s3_requirer.get_s3_connection_info()
+        required_parameters = [
+            "bucket",
+            "access-key",
+            "secret-key",
+        ]
+        missing_required_parameters = [
+            param for param in required_parameters if param not in s3_parameters
+        ]
+        if missing_required_parameters:
+            logger.warning(
+                f"Missing required S3 parameters in relation with S3 integrator: {missing_required_parameters}"
+            )
+            return {}, missing_required_parameters
+
+        # Add some sensible defaults (as expected by the code) for missing optional parameters
+        s3_parameters.setdefault("endpoint", "https://s3.amazonaws.com")
+        s3_parameters.setdefault("path", "")
+        s3_parameters.setdefault("s3-uri-style", "host")
+        s3_parameters.setdefault("delete-older-than-days", "9999999")
+
+        # Strip whitespaces from all parameters.
+        for key, value in s3_parameters.items():
+            if isinstance(value, str):
+                s3_parameters[key] = value.strip()
+
+        # Clean up extra slash symbols to avoid issues on 3rd-party storages
+        # like Ceph Object Gateway (radosgw).
+        s3_parameters["endpoint"] = s3_parameters["endpoint"].rstrip("/")
+        s3_parameters["path"] = (
+            f"/{s3_parameters['path'].strip('/')}"  # The slash in the beginning is required by pgBackRest.
+        )
+        s3_parameters["bucket"] = s3_parameters["bucket"].strip("/")
+
+        return s3_parameters, []

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/single_kernel_postgresql/core/state.py

@@ -31,15 +31,18 @@ from single_kernel_postgresql.config.literals import (
     PEER_RELATION,
     REPLICATION_CONSUMER_RELATION,
     REPLICATION_OFFER_RELATION,
+    S3_RELATION_NAME,
     SCOPES,
     STATUS_PEERS_RELATION,
 )
 from single_kernel_postgresql.core.config import CharmConfig
 from single_kernel_postgresql.core.peer_relation import PostgreSQLApplication, PostgreSQLPeer
+from single_kernel_postgresql.core.s3 import S3ConnectionInfo
 from single_kernel_postgresql.lib.charms.data_platform_libs.v0.data_interfaces import (
     DataPeerData,
     DataPeerUnitData,
 )
+from single_kernel_postgresql.lib.charms.data_platform_libs.v0.s3 import S3Requirer
 from single_kernel_postgresql.utils import unit_name_to_pod_name
 from single_kernel_postgresql.utils.secret import translate_field_to_secret_key
 from single_kernel_postgresql.utils.status import format_status
@@ -52,6 +55,7 @@ class CharmState(Object):
         self,
         charm: CharmBase,
         substrate: Substrates,
+        s3_requirer: S3Requirer,
     ) -> None:
         """Initialize the CharmState object."""
         super().__init__(charm, "charm_state")
@@ -60,6 +64,7 @@ class CharmState(Object):
         self.peer_unit_interface = DataPeerUnitData(model=charm.model, relation_name=PEER_RELATION)
 
         self.statuses = StatusesState(self, STATUS_PEERS_RELATION)
+        self.s3_requirer = s3_requirer
 
     # -- Charm Config
     @cached_property
@@ -93,6 +98,11 @@ class CharmState(Object):
         """Get status peers relation."""
         return self.model.get_relation(STATUS_PEERS_RELATION)
 
+    @property
+    def s3_relation(self) -> Relation | None:
+        """Get the S3 parameters relation."""
+        return self.model.get_relation(S3_RELATION_NAME)
+
     # -- Core State Components
 
     @property
@@ -133,6 +143,11 @@ class CharmState(Object):
             substrate=self.substrate,
         )
 
+    @property
+    def s3_connection_info(self) -> S3ConnectionInfo:
+        """Get the S3 connection info state."""
+        return S3ConnectionInfo(self.s3_requirer)
+
     # -- Cluster state utilities
     def _get_hostname_from_unit(self, member: str) -> str:
         """Create a DNS name for a PostgreSQL/Patroni cluster member.
@@ -216,6 +231,11 @@ class CharmState(Object):
         """Current model name."""
         return self.model.name
 
+    @property
+    def cluster_name(self) -> str:
+        """Patroni cluster name, substrate-conditional (delegates to the app peer state)."""
+        return self.application.cluster_name
+
     @cached_property
     def patroni_url(self) -> str:
         """Patroni REST API URL."""
@@ -325,6 +345,22 @@ class CharmState(Object):
             ips.append(self.replication_consumer_ip)
         return ips
 
+    @property
+    def cluster_stanza(self) -> str | None:
+        """Return the pgBackRest stanza of the cluster, whichever unit published it.
+
+        The stanza is written by the primary into its unit databag during S3
+        initialization and only later adopted by the leader into app data, so
+        while a cluster is mid-initialization (or mid-restore) the authoritative
+        copy may still live on a unit. Fetched live on every access.
+        """
+        if stanza := self.application.stanza:
+            return stanza
+        for peer in self.application_peers:
+            if stanza := peer.stanza:
+                return stanza
+        return None
+
     # -- Secrets
     # TODO: This is temporary till data interfaces v1 is integrated
     def get_secret(self, scope: SCOPES, key: str) -> str | None:

{postgresql_charms_single_kernel-16.3.8 → postgresql_charms_single_kernel-16.3.9}/single_kernel_postgresql/events/tls_transfer.py

@@ -60,7 +60,7 @@ class TLSTransfer(Object):
     def _on_certificate_removed(self, event: CertificateRemovedEvent) -> None:
         """Disable TLS when TLS certificate is removed."""
         relation = self.charm.model.get_relation(TLS_TRANSFER_RELATION, event.relation_id)
-        if relation is None:
+        if relation is None or relation.app is None:
             logger.error("Relationship not established anymore.")
             return