postgresql-charms-single-kernel 16.2.2__tar.gz → 16.3.1__tar.gz

{postgresql_charms_single_kernel-16.2.2 → postgresql_charms_single_kernel-16.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: postgresql-charms-single-kernel
-Version: 16.2.2
+Version: 16.3.1
 Summary: Shared and reusable code for PostgreSQL-related charms
 Author: Canonical Data Platform
 Author-email: Canonical Data Platform <data-platform@lists.launchpad.net>
@@ -210,11 +210,25 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX :: Linux
 Requires-Dist: ops>=2.0.0
-Requires-Dist: psycopg2>=2.9.10
 Requires-Dist: tenacity>=9.0.0
+Requires-Dist: psycopg2>=2.9.10 ; extra == 'db-driver'
 Requires-Dist: httpx ; python_full_version >= '3.12' and extra == 'postgresql'
+Requires-Dist: data-platform-helpers>=0.1.7 ; python_full_version >= '3.12' and extra == 'postgresql'
+Requires-Dist: charmlibs-pathops>=1.0.1 ; python_full_version >= '3.12' and extra == 'postgresql'
+Requires-Dist: charmlibs-interfaces-tls-certificates>=1.8.3 ; python_full_version >= '3.12' and extra == 'postgresql'
+Requires-Dist: charm-refresh ; python_full_version >= '3.12' and extra == 'postgresql'
+Requires-Dist: requests ; python_full_version >= '3.12' and extra == 'postgresql'
+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: 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'
 Requires-Python: >=3.8, <4.0
+Provides-Extra: db-driver
 Provides-Extra: postgresql
+Provides-Extra: vm
 Description-Content-Type: text/markdown
 
 # postgresql-single-kernel-library

{postgresql_charms_single_kernel-16.2.2 → postgresql_charms_single_kernel-16.3.1}/pyproject.toml

@@ -4,7 +4,7 @@
 [project]
 name = "postgresql-charms-single-kernel"
 description = "Shared and reusable code for PostgreSQL-related charms"
-version = "16.2.2"
+version = "16.3.1"
 readme = "README.md"
 license = {file = "LICENSE"}
 authors = [
@@ -18,12 +18,30 @@ classifiers = [
 requires-python = ">=3.8,<4.0"
 dependencies = [
     "ops>=2.0.0",
-    "psycopg2>=2.9.10",
     "tenacity>=9.0.0",
 ]
 
 [project.optional-dependencies]
-postgresql = ["httpx; python_version >= '3.12'"]
+postgresql = [
+    "httpx; python_version >= '3.12'",
+    "data-platform-helpers>=0.1.7; python_version >= '3.12'",
+    "charmlibs-pathops>=1.0.1; python_version >= '3.12'",
+    "charmlibs-interfaces-tls-certificates>=1.8.3; python_version >= '3.12'",
+    "charm-refresh; python_version >= '3.12'",
+    "requests; python_version >= '3.12'",
+    "tomli; python_version >= '3.12'",
+    "pydantic>=2.0; python_version >= '3.12'",
+    "jinja2 >=3.1.6; python_version >= '3.12'",
+    "charmlibs-rollingops>=1.1.1; python_version >= '3.12'",
+]
+vm = [
+    "pysyncobj>=0.3.15; python_version >= '3.12'",
+    "psutil>=7.2.2; python_version >= '3.12'",
+    "charmlibs-snap>=1.0.1; python_version >= '3.12'",
+]
+db-driver = [
+    "psycopg2>=2.9.10",
+]
 
 [build-system]
 requires = ["uv_build>=0.11.0,<0.12.0"]
@@ -35,15 +53,15 @@ module-root = ""
 
 [dependency-groups]
 format = [
-    "ruff==0.15.14"
+    "ruff==0.15.20"
 ]
 lint = [
     "codespell==2.4.2",
-    "ty==0.0.39"
+    "ty==0.0.55"
 ]
 unit = [
-    "coverage[toml]==7.14.0",
-    "pytest==9.0.3"
+    "coverage[toml]==7.14.3",
+    "pytest==9.1.1"
 ]
 
 
@@ -117,4 +135,4 @@ python = ".tox/lint/"
 python-version = "3.12"
 
 [tool.ty.src]
-exclude = ["tests"]
+exclude = ["tests", "single_kernel_postgresql/lib"]

postgresql_charms_single_kernel-16.3.1/single_kernel_postgresql/charms/__init__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+# Copyright 2026 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""Charms Definitions."""

postgresql_charms_single_kernel-16.3.1/single_kernel_postgresql/charms/abstract_charm.py

@@ -0,0 +1,76 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+"""Skeleton for the abstract charm."""
+
+from abc import ABC, abstractmethod
+
+from data_platform_helpers.advanced_statuses import StatusHandler
+from ops.charm import CharmBase
+
+from single_kernel_postgresql.core.state import CharmState
+from single_kernel_postgresql.events.postgresql import PostgreSQLEventsHandler
+from single_kernel_postgresql.managers.cluster import ClusterManager
+from single_kernel_postgresql.managers.config import ConfigManager
+from single_kernel_postgresql.managers.patroni import PatroniManager
+from single_kernel_postgresql.managers.tls import TLSManager
+from single_kernel_postgresql.workload.base import BaseWorkload
+
+from ..config.enums import Substrates
+from ..utils.postgresql import PostgreSQL
+
+
+class AbstractPostgreSQLCharm(CharmBase, ABC):
+    """An abstract PostgreSQL charm."""
+
+    def __init__(self, *args):
+        super().__init__(*args)
+
+        # State
+        self.state = CharmState(charm=self, substrate=self.substrate)
+
+        # Managers
+        self.tls_manager = TLSManager(state=self.state, workload=self.workload)
+        self.patroni_manager = PatroniManager(state=self.state, workload=self.workload)
+        self.cluster_manager = ClusterManager(state=self.state, workload=self.workload)
+        self.config_manager = ConfigManager(state=self.state, workload=self.workload)
+
+        # Events Handler
+        self.postgresql_events_handler = PostgreSQLEventsHandler(
+            self,
+            self.workload,
+            self.state,
+            self.cluster_manager,
+            self.tls_manager,
+            self.config_manager,
+            self.patroni_manager,
+        )
+
+        # Status Handler
+        self.status_handler = StatusHandler(
+            self,
+            self.cluster_manager,
+            self.tls_manager,
+            self.config_manager,
+            self.patroni_manager,
+        )
+
+    # Postgresql Client
+    @property
+    @abstractmethod
+    def postgresql(self) -> PostgreSQL:
+        """Return a PostgreSQL client."""
+        pass
+
+    # Postgresql Workload
+    @property
+    @abstractmethod
+    def workload(self) -> BaseWorkload:
+        """Access current workload."""
+        pass
+
+    # Postgresql Substrate
+    @property
+    @abstractmethod
+    def substrate(self) -> Substrates:
+        """Access current substrate."""
+        pass

postgresql_charms_single_kernel-16.3.1/single_kernel_postgresql/charms/k8s_charm.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""PostgreSQL Kubernetes Charm."""
+
+import logging
+
+from single_kernel_postgresql.charms.abstract_charm import AbstractPostgreSQLCharm, PostgreSQL
+from single_kernel_postgresql.config.enums import Substrates
+from single_kernel_postgresql.config.literals import CONTAINER_NAME, SYSTEM_USERS, USER
+from single_kernel_postgresql.managers.k8s import K8sManager
+from single_kernel_postgresql.workload.base import BaseWorkload
+from single_kernel_postgresql.workload.k8s import K8sWorkload
+
+logger = logging.getLogger(__name__)
+
+
+class PostgreSQLK8sCharm(AbstractPostgreSQLCharm):
+    """PostgreSQL K8s Charm."""
+
+    def __init__(self, *args):
+        """Initialize the PostgreSQL Kubernetes Charm."""
+        super().__init__(*args)
+        assert isinstance(self.workload, K8sWorkload), (  # noqa: S101
+            "Workload must be an instance of K8sWorkload"
+        )
+        self.k8s_manager = K8sManager(self.state, self.workload)
+
+    @property
+    def postgresql(self) -> PostgreSQL:
+        """Return a PostgreSQL client."""
+        return PostgreSQL(
+            substrate=Substrates.K8S,
+            primary_host="localhost",
+            current_host="localhost",
+            user=USER,
+            # The password is hardcoded because this is an abstract charm and
+            # it meant to be used only in unit tests.
+            password="test-password",  # noqa S106
+            database="test-database",
+            system_users=SYSTEM_USERS,
+        )
+
+    @property
+    def workload(self) -> BaseWorkload:
+        """Access current workload instance.
+
+        Returns the workload object.
+
+        Returns:
+            BaseWorkload: The K8sWorkload instance for this charm
+        """
+        return K8sWorkload(
+            charm_dir=self.charm_dir, container=self.unit.get_container(CONTAINER_NAME)
+        )
+
+    @property
+    def substrate(self) -> Substrates:
+        """Access current substrate type.
+
+        Returns:
+            Substrates: always Substrates.K8S for this charm
+        """
+        return Substrates.K8S

postgresql_charms_single_kernel-16.3.1/single_kernel_postgresql/charms/vm_charm.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""PostgreSQL VM Charm."""
+
+import logging
+
+from single_kernel_postgresql.charms.abstract_charm import AbstractPostgreSQLCharm, PostgreSQL
+from single_kernel_postgresql.config.enums import Substrates
+from single_kernel_postgresql.config.literals import SYSTEM_USERS, USER
+from single_kernel_postgresql.workload.base import BaseWorkload
+from single_kernel_postgresql.workload.vm import VMWorkload
+
+logger = logging.getLogger(__name__)
+
+
+class PostgreSQLVMCharm(AbstractPostgreSQLCharm):
+    """PostgreSQL VM Charm."""
+
+    def __init__(self, *args):
+        """Initialize the PostgreSQL VM Charm."""
+        super().__init__(*args)
+
+    @property
+    def postgresql(self) -> PostgreSQL:
+        """Return a PostgreSQL client."""
+        return PostgreSQL(
+            substrate=Substrates.VM,
+            primary_host="localhost",
+            current_host="localhost",
+            user=USER,
+            # The password is hardcoded because this is an abstract charm and
+            # it meant to be used only in unit tests.
+            password="test-password",  # noqa S106
+            database="test-database",
+            system_users=SYSTEM_USERS,
+        )
+
+    @property
+    def workload(self) -> BaseWorkload:
+        """Access current workload instance.
+
+        Returns the workload object.
+
+        Returns:
+            BaseWorkload: The VMWorkload instance for this charm
+        """
+        return VMWorkload(charm_dir=self.charm_dir)
+
+    @property
+    def substrate(self) -> Substrates:
+        """Access current substrate type.
+
+        Returns:
+            Substrates: always Substrates.VM for this charm
+        """
+        return Substrates.VM

postgresql_charms_single_kernel-16.3.1/single_kernel_postgresql/config/enums.py

@@ -0,0 +1,13 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""PostgreSQL enums."""
+
+from enum import Enum
+
+
+class Substrates(str, Enum):
+    """Possible substrates."""
+
+    K8S = "k8s"
+    VM = "vm"

postgresql_charms_single_kernel-16.3.1/single_kernel_postgresql/config/exceptions.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""Charm-specific exceptions."""
+
+from single_kernel_postgresql.compat.postgresql import PostgreSQLBaseError
+
+
+class PostgreSQLFileOperationError(PostgreSQLBaseError):
+    """Exception thrown when file operations related to PostgreSQL fail."""
+
+
+class StorageUnavailableError(Exception):
+    """Cannot find storage mountpoint."""
+
+
+class SettingSystemPasswordError(PostgreSQLBaseError):
+    """Exception thrown when setting the system password fails."""
+
+
+class PostgreSQLCannotConnectError(Exception):
+    """Cannot run smoke check on connected Database."""
+
+
+class TlsError(Exception):
+    """TLS implementation internal exception."""
+
+
+class RaftPostgresqlNotUpError(Exception):
+    """Postgresql not yet started."""
+
+
+class RaftPostgresqlStillUpError(Exception):
+    """Postgresql not yet down."""
+
+
+class RaftNotPromotedError(Exception):
+    """Leader not yet set when reinitialising raft."""
+
+
+class ClusterNotPromotedError(Exception):
+    """Raised when a cluster is not promoted."""
+
+
+class NotReadyError(Exception):
+    """Raised when not all cluster members healthy or finished initial sync."""
+
+
+class EndpointNotReadyError(Exception):
+    """Raised when an endpoint is not ready."""
+
+
+class StandbyClusterAlreadyPromotedError(Exception):
+    """Raised when a standby cluster is already promoted."""
+
+
+class RemoveRaftMemberFailedError(Exception):
+    """Raised when a remove raft member failed for some reason."""
+
+
+class AddRaftMemberFailedError(Exception):
+    """Raised when adding raft member failed for some reason."""
+
+
+class SwitchoverFailedError(Exception):
+    """Raised when a switchover failed for some reason."""
+
+
+class SwitchoverNotSyncError(SwitchoverFailedError):
+    """Raised when a switchover failed because node is not sync."""
+
+
+class UpdateSyncNodeCountError(Exception):
+    """Raised when updating synchronous_node_count failed for some reason."""

postgresql_charms_single_kernel-16.3.1/single_kernel_postgresql/config/literals.py

@@ -0,0 +1,176 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+"""Literal string for the different charms.
+
+This module should contain the literals used in the charms (paths, relation names, etc).
+"""
+
+from typing import Literal
+
+# Permissions.
+POSTGRESQL_STORAGE_PERMISSIONS = 0o700
+
+# Relations
+PEER_RELATION = "database-peers"
+STATUS_PEERS_RELATION = "status-peers"
+
+# Users.
+BACKUP_USER = "backup"
+MONITORING_USER = "monitoring"
+REPLICATION_USER = "replication"
+REWIND_USER = "rewind"
+SNAP_USER = "_daemon_"
+USER = "operator"
+SYSTEM_USERS = [BACKUP_USER, MONITORING_USER, REPLICATION_USER, REWIND_USER, USER]
+
+# Paths
+## VM Paths
+BASE_SNAP_DIR = "/var/snap/charmed-postgresql"
+SNAP_DATA = "current"
+SNAP_COMMON = "common"
+SNAP = "/snap/charmed-postgresql/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"
+
+## K8s Paths
+K8S_DATA_PATH = "var/lib/pg/data"
+
+## Shared Paths
+# NOTE: The paths don't have leading slahes since pathops
+# will handle path concatenation otherwise it will use "/var/lib/postgresql"
+# instead of using the root path or any other part defined by the / operator.
+# e.g. snap_current / "/etc/postgresql" will result in "/etc/postgresql" instead of "/var/snap/postgresql/current/etc/postgresql"
+POSTGRESQL_CONF_PATH = "etc/postgresql"
+POSTGRESQL_CONF_FILE = "postgresql.conf"
+## Pgbackreest Paths
+PGBACKREST_CONF_PATH = "etc/pgbackrest"
+PGBACKREST_CONF_FILE = "pgbackrest.conf"
+
+## TLS Paths
+TLS_CA_BUNDLE_FILE = "peer_ca_bundle.pem"
+
+# Scopes
+SCOPES = Literal["app", "unit"]
+APP_SCOPE = "app"
+UNIT_SCOPE = "unit"
+
+# Patroni
+## Patroni Paths
+PATRONI_CONF_PATH = "etc/patroni"
+PATRONI_LOGS_PATH = "var/log/patroni"
+## Patroni states
+STARTED_STATES = ["running", "streaming"]
+RUNNING_STATES = [*STARTED_STATES, "starting"]
+## Patroni config
+ORIGINAL_PATRONI_ON_FAILURE_CONDITION = "restart"
+
+
+# Secrets
+SECRET_KEY_OVERRIDES = {"ca": "cauth"}
+
+
+# Password keys
+REPLICATION_PASSWORD_KEY = "replication-password"  # noqa: S105
+REWIND_PASSWORD_KEY = "rewind-password"  # noqa: S105
+USER_PASSWORD_KEY = "operator-password"  # noqa: S105
+MONITORING_PASSWORD_KEY = "monitoring-password"  # noqa: S105
+RAFT_PASSWORD_KEY = "raft-password"  # noqa: S105
+PATRONI_PASSWORD_KEY = "patroni-password"  # noqa: S105
+SECRET_INTERNAL_LABEL = "internal-secret"  # noqa: S105
+SECRET_DELETED_LABEL = "None"  # noqa: S105
+SYSTEM_USERS_PASSWORD_CONFIG = "system-users"  # noqa: S105
+
+# K8s
+## K8s Services
+K8S_POSTGRESQL_SERVICE_NAME = "postgresql"
+K8S_PGBACK_REST_SERVER_SERVICE_NAME = "pgbackrest server"
+K8S_LDAP_SYNC_SERVICE_NAME = "ldap-sync"
+K8S_METRICS_SERVER_SERVICE_NAME = "metrics_server"
+K8S_PGBACKREST_METRICS_SERVER_SERVICE_NAME = "pgbackrest_metrics_server"
+K8S_ROTATE_LOGS_SERVICE_NAME = "rotate-logs"
+## K8s User and group
+K8S_WORKLOAD_OS_GROUP = "postgres"
+K8S_WORKLOAD_OS_USER = "postgres"
+
+
+# File permissions as octal
+# standard directory permissions
+DIR_PERMISSIONS_READONLY = 0o750
+
+
+# Container name for K8s deployments
+CONTAINER_NAME = "postgresql"
+
+API_REQUEST_TIMEOUT = 5
+
+
+# --- Shared constants migrated from the charms ---
+
+# Database
+DATABASE = "database"
+DATABASE_DEFAULT_NAME = "postgres"
+DATABASE_PORT = "5432"
+
+# Client relations
+ALL_CLIENT_RELATIONS = [DATABASE]
+
+# Async replication relations
+REPLICATION_CONSUMER_RELATION = "replication"
+REPLICATION_OFFER_RELATION = "replication-offer"
+
+# TLS files
+TLS_KEY_FILE = "key.pem"
+TLS_CA_FILE = "ca.pem"
+TLS_CERT_FILE = "cert.pem"
+
+# Metrics ports (kept as str to match the K8s charm; VM adapts on flip)
+METRICS_PORT = "9187"
+PGBACKREST_METRICS_PORT = "9854"
+
+# Secret/database mapping labels
+USERNAME_MAPPING_LABEL = "custom-usernames"
+DATABASE_MAPPING_LABEL = "prefix-databases"
+
+# Overrides
+BACKUP_TYPE_OVERRIDES = {"full": "full", "differential": "diff", "incremental": "incr"}
+PLUGIN_OVERRIDES = {"audit": "pgaudit", "uuid_ossp": '"uuid-ossp"'}
+
+# SPI extension modules
+SPI_MODULE = ["refint", "autoinc", "insert_username", "moddatetime"]
+
+# Tracing
+TRACING_RELATION_NAME = "tracing"
+TRACING_PROTOCOL = "otlp_http"
+
+# Patroni
+PATRONI_CLUSTER_STATUS_ENDPOINT = "cluster"
+
+# pgBackRest
+PGBACKREST_LOGROTATE_FILE = "/etc/logrotate.d/pgbackrest.logrotate"
+# pgBackRest emits all error/warning output on stderr (the default is stdout) so error
+# extraction stays consistent. Reference: https://pgbackrest.org/configuration.html#section-log
+PGBACKREST_LOG_LEVEL_STDERR = "--log-level-stderr=warn"
+# Archive timeout: unable to archive WAL files within the configured timeout period.
+PGBACKREST_ARCHIVE_TIMEOUT_ERROR_CODE = 82
+
+# Backup ID formats
+BACKUP_ID_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+PGBACKREST_BACKUP_ID_FORMAT = "%Y%m%d-%H%M%S"
+
+# Watcher relation (VM)
+WATCHER_OFFER_RELATION = "watcher-offer"
+WATCHER_RELATION = "watcher"
+WATCHER_USER = "watcher"
+WATCHER_PASSWORD_KEY = "watcher-password"  # noqa: S105
+WATCHER_SECRET_LABEL = "watcher-secret"  # noqa: S105
+
+# Raft
+RAFT_PORT = 2222
+RAFT_PARTNER_PREFIX = "partner_node_status_server_"
+
+# VM services
+VM_PATRONI_SERVICE_NAME = "snap.charmed-postgresql.patroni.service"
+VM_PATRONI_SERVICE_DEFAULT_PATH = f"/etc/systemd/system/{VM_PATRONI_SERVICE_NAME}"