phlo-postgres 0.3.2__tar.gz → 0.14.0__tar.gz

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/PKG-INFO

@@ -1,14 +1,13 @@
 Metadata-Version: 2.4
 Name: phlo-postgres
-Version: 0.3.2
+Version: 0.14.0
 Summary: Postgres service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT
 Requires-Python: >=3.11
 Description-Content-Type: text/plain
-Requires-Dist: phlo>=0.1.0
+Requires-Dist: phlo<0.15,>=0.14.0
 Requires-Dist: psycopg2-binary>=2.9.11
-Requires-Dist: pyyaml>=6.0.1
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/pyproject.toml

@@ -7,14 +7,13 @@ requires = [
 
 [project]
 dependencies = [
-    "phlo>=0.1.0",
+    "phlo>=0.14.0,<0.15",
     "psycopg2-binary>=2.9.11",
-    "pyyaml>=6.0.1",
 ]
 description = "Postgres service plugin for Phlo"
 name = "phlo-postgres"
 requires-python = ">=3.11"
-version = "0.3.2"
+version = "0.14.0"
 
 [[project.authors]]
 email = "team@phlo.dev"

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/src/phlo_postgres/__init__.py

@@ -19,12 +19,14 @@ from phlo_postgres.plugin import PostgresServicePlugin
 from phlo_postgres.publish_target import PostgresPublishTarget
 from phlo_postgres.resource import PostgresResource
 from phlo_postgres.settings import PostgresSettings, get_settings
+from phlo_postgres.settings_store import PostgresSettingsStore
 
 __all__ = [
     "PostgresPublishTarget",
     "PostgresResource",
     "PostgresServicePlugin",
     "PostgresSettings",
+    "PostgresSettingsStore",
     "get_settings",
 ]
-__version__ = "0.3.2"
+__version__ = "0.14.0"

phlo_postgres-0.14.0/src/phlo_postgres/authorization.py

@@ -0,0 +1,41 @@
+"""phlo_postgres CLI authorization table."""
+
+from __future__ import annotations
+
+from phlo.cli.authorization import CliSurfaceAdapter, cli_surface_adapter_class
+
+SURFACE_NAME = "phlo-postgres-cli"
+FRAMEWORK_TYPE = "cli"
+MUTATION_COMMANDS: frozenset[str] = frozenset(
+    ["postgres", "postgres.dump", "postgres.query", "postgres.restore", "postgres.vacuum"]
+)
+READ_COMMANDS: frozenset[str] = frozenset([])
+COMMAND_RESOURCE_MAP: dict[str, str] = {
+    "postgres.query": "dataset",
+    "postgres.dump": "dataset",
+    "postgres.restore": "dataset",
+    "postgres.vacuum": "dataset",
+    "postgres": "dataset",
+}
+COMMAND_ACTION_MAP: dict[str, str] = {
+    "postgres.query": "dataset.query",
+    "postgres.dump": "dataset.manage",
+    "postgres.restore": "dataset.manage",
+    "postgres.vacuum": "dataset.manage",
+    "postgres": "dataset.query",
+}
+
+PostgresCliSurfaceAdapter = cli_surface_adapter_class(
+    "PostgresCliSurfaceAdapter",
+    surface_name=SURFACE_NAME,
+    mutation_commands=MUTATION_COMMANDS,
+    read_commands=READ_COMMANDS,
+    command_resource_map=COMMAND_RESOURCE_MAP,
+    command_action_map=COMMAND_ACTION_MAP,
+    default_action_prefix="postgres",
+    default_resource_prefix="postgres",
+)
+
+
+def get_postgres_cli_adapter() -> CliSurfaceAdapter:
+    return PostgresCliSurfaceAdapter.get_instance()

phlo_postgres-0.14.0/src/phlo_postgres/cli_plugin.py

@@ -0,0 +1,17 @@
+"""Postgres CLI plugin registration."""
+
+from __future__ import annotations
+
+
+from phlo.plugins.base import cli_command_plugin_class
+
+from phlo_postgres.cli import postgres_group
+
+
+PostgresCliPlugin = cli_command_plugin_class(
+    "PostgresCliPlugin",
+    name="postgres",
+    version="0.1.0",
+    description="CLI commands for PostgreSQL service access",
+    commands=[postgres_group],
+)

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/src/phlo_postgres/exporter_service.yaml

@@ -4,7 +4,7 @@ category: observability
 default: false
 profile: observability
 
-image: quay.io/prometheuscommunity/postgres-exporter:v0.15.0
+image: quay.io/prometheuscommunity/postgres-exporter:v0.20.1@sha256:ac5ec343104fae0e2d84a27bb8d69b38430a11910c5382cad85d478d2bab713e
 
 depends_on:
   - postgres

phlo_postgres-0.14.0/src/phlo_postgres/plugin.py

@@ -0,0 +1,141 @@
+"""PostgreSQL service plugin implementations.
+
+This module provides plugin implementations that integrate PostgreSQL with the
+phlo plugin system. It includes service plugins for the PostgreSQL database,
+Prometheus exporter, and volume setup, as well as a resource provider plugin
+that exposes PostgreSQL capabilities to the rest of the system.
+
+Example:
+    >>> from phlo_postgres.plugin import PostgresServicePlugin
+    >>> plugin = PostgresServicePlugin()
+    >>> print(plugin.metadata.name)
+    postgres
+    >>> definition = plugin.service_definition
+
+"""
+
+from __future__ import annotations
+
+from phlo.capabilities import PublishTargetSpec, ResourceSpec, SettingsStoreSpec
+from phlo.plugins import PluginMetadata, ResourceProviderPlugin, service_plugin_class
+
+from phlo_postgres.publish_target import PostgresPublishTarget
+from phlo_postgres.resource import PostgresResource
+from phlo_postgres.settings_store import get_settings_stores
+
+
+PostgresServicePlugin = service_plugin_class(
+    "PostgresServicePlugin",
+    name="postgres",
+    version="0.1.0",
+    description="PostgreSQL database for metadata and operational storage",
+    author="Phlo Team",
+    tags=["core", "database", "postgres"],
+)
+
+
+PostgresExporterServicePlugin = service_plugin_class(
+    "PostgresExporterServicePlugin",
+    name="postgres-exporter",
+    version="0.1.0",
+    description="Prometheus exporter for PostgreSQL metrics",
+    author="Phlo Team",
+    tags=["observability", "metrics", "postgres"],
+    service_definition_file="exporter_service.yaml",
+)
+
+
+PostgresVolumeSetupServicePlugin = service_plugin_class(
+    "PostgresVolumeSetupServicePlugin",
+    name="postgres-volume-setup",
+    version="0.1.0",
+    description="Initialize PostgreSQL data volume permissions",
+    author="Phlo Team",
+    tags=["core", "database", "postgres"],
+    service_definition_file="volume_setup.yaml",
+)
+
+
+class PostgresResourceProvider(ResourceProviderPlugin):
+    """Resource provider plugin that exposes PostgreSQL capabilities.
+
+    This plugin registers the PostgresResource and PostgresPublishTarget with
+    the phlo resource system, making them available to other components for
+    database operations and data publishing.
+
+    Example:
+        >>> provider = PostgresResourceProvider()
+        >>> resources = provider.get_resources()
+        >>> targets = provider.get_publish_targets()
+
+    """
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for the PostgreSQL resource provider.
+
+        Returns:
+            PluginMetadata: Metadata describing the resource provider plugin.
+
+        Example:
+            >>> provider = PostgresResourceProvider()
+            >>> meta = provider.metadata
+            >>> print(meta.name)
+            postgres
+
+        """
+        return PluginMetadata(
+            name="postgres",
+            version="0.1.0",
+            description="Postgres resource for Phlo",
+        )
+
+    def get_resources(self) -> list[ResourceSpec]:
+        """Return resource specifications exposed by this provider.
+
+        Returns:
+            list[ResourceSpec]: List of registered resource specifications
+                that can be accessed by other phlo components.
+
+        Example:
+            >>> provider = PostgresResourceProvider()
+            >>> specs = provider.get_resources()
+            >>> print(specs[0].name)
+            postgres
+
+        """
+        return [ResourceSpec(name="postgres", resource=PostgresResource())]
+
+    def get_publish_targets(self) -> list[PublishTargetSpec]:
+        """Return publish target capability specs exposed by this provider.
+
+        Returns:
+            list[PublishTargetSpec]: List of publish target specifications
+                that define where data can be published to PostgreSQL.
+
+        Example:
+            >>> provider = PostgresResourceProvider()
+            >>> targets = provider.get_publish_targets()
+            >>> print(targets[0].name)
+            postgres
+            >>> print(targets[0].metadata)
+            {'target_system': 'postgres', 'role': 'serving'}
+
+        """
+        return [
+            PublishTargetSpec(
+                name="postgres",
+                provider=PostgresPublishTarget(),
+                metadata={"target_system": "postgres", "role": "serving"},
+            )
+        ]
+
+    def get_settings_stores(self) -> list[SettingsStoreSpec]:
+        """Return settings store capability specs for durable Observatory settings.
+
+        Returns:
+            list[SettingsStoreSpec]: Capability spec wrapping a
+            :class:`~phlo_postgres.settings_store.PostgresSettingsStore`
+            that persists Observatory settings to PostgreSQL.
+        """
+        return get_settings_stores()

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/src/phlo_postgres/service.yaml

@@ -6,7 +6,7 @@ default: true
 depends_on:
   - postgres-volume-setup
 
-image: postgres:16-alpine
+image: postgres:18.4-alpine3.24@sha256:9a8afca54e7861fd90fab5fdf4c42477a6b1cb7d293595148e674e0a3181de15
 
 compose:
   restart: unless-stopped
@@ -26,7 +26,7 @@ compose:
   ports:
     - "${POSTGRES_PORT:-10000}:5432"
   volumes:
-    - postgres-data:/var/lib/postgresql/data
+    - postgres-data:/var/lib/postgresql
   healthcheck:
     test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-phlo}"]
     interval: 10s
@@ -47,6 +47,7 @@ env_vars:
   POSTGRES_PORT:
     default: 10000
     description: PostgreSQL host port
+
   # SSL/TLS
   POSTGRES_SSL_MODE:
     default: "prefer"

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/src/phlo_postgres/settings.py

@@ -15,13 +15,14 @@ Example:
 
 from __future__ import annotations
 
-from functools import lru_cache
+from pathlib import Path
 from typing import Any
 from urllib.parse import quote_plus
 
 from pydantic import Field
 
 from phlo.config.base import BaseConfig
+from phlo.config.cache import project_root_cached
 from phlo.config.network import resolve_host
 
 
@@ -123,25 +124,27 @@ class PostgresSettings(BaseConfig):
         return f"postgresql://{user}:{password}@{self.postgres_host}:{self.postgres_port}{db_part}"
 
 
-@lru_cache(maxsize=1)
-def get_settings() -> PostgresSettings:
-    """Return cached PostgreSQL settings instance.
+@project_root_cached
+def get_settings(project_root: Path) -> PostgresSettings:
+    """Return cached PostgreSQL settings for the selected project root.
 
-    Provides a singleton-style access to PostgreSQL settings with LRU caching
-    to avoid repeated parsing of environment variables and configuration files.
+    Settings are cached per resolved project root, with up to 16 entries,
+    to avoid repeated parsing while isolating project configuration.
+
+    Args:
+        project_root: Resolved project root used for cache selection.
 
     Returns:
         PostgresSettings: Cached settings instance.
 
     Note:
-        The cache size of 1 ensures the same settings object is returned
-        throughout the process lifetime. Settings are loaded once on first
-        call and reused thereafter.
+        Calls for the same project root return the same settings object.
+        Call ``get_settings.cache_clear()`` after changing configuration.
 
     Example:
         >>> settings1 = get_settings()
         >>> settings2 = get_settings()
-        >>> settings1 is settings2  # Same cached instance
+        >>> settings1 is settings2  # Same cached instance for this root
         True
         >>>
         >>> # Access connection parameters

phlo_postgres-0.14.0/src/phlo_postgres/settings_store.py

@@ -0,0 +1,224 @@
+"""PostgreSQL settings store capability for Observatory settings.
+
+This module is the sole owner of the durable Observatory settings
+implementation: psycopg2 usage, SQL table creation, DSN handling, and
+connection-failure sanitisation.  It registers a ``SettingsStoreSpec``
+with the phlo capability registry so that core's ``get_settings_service``
+can resolve it without importing this package directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from jsonschema import ValidationError, validate
+
+from phlo.capabilities import SettingsStoreSpec
+from phlo.logging import get_logger
+from phlo.plugins.observatory_settings import (
+    ObservatorySettingsStorageConfig,
+    SettingsRecord,
+    SettingsScope,
+    StorageUnavailableError,
+)
+from phlo_postgres.settings import get_settings as get_postgres_settings
+
+logger = get_logger(__name__)
+
+
+def _get_psycopg2():
+    try:
+        import psycopg2
+        import psycopg2.extras
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            "psycopg2 is required to use PostgreSQL-backed observatory settings storage."
+        ) from exc
+    return psycopg2
+
+
+class PostgresSettingsStore:
+    """Durable Observatory settings store backed by PostgreSQL.
+
+    The DSN is resolved at construction time from
+    :class:`ObservatorySettingsStorageConfig` (explicit override) or
+    :mod:`phlo_postgres.settings` (default).  No database connection is
+    opened until ``get`` or ``put`` is called, so a transient outage does
+    not poison the instance — the next call retries the connection.
+    """
+
+    def __init__(self) -> None:
+        config = ObservatorySettingsStorageConfig()
+        if config.observatory_settings_db_url:
+            self._db_url = config.observatory_settings_db_url
+        else:
+            postgres_settings = get_postgres_settings()
+            self._db_url = postgres_settings.get_postgres_connection_string()
+        self._table_ensured = False
+
+    def get(self, scope: SettingsScope, namespace: str) -> SettingsRecord | None:
+        """Get settings for a scope and namespace."""
+        psycopg2 = _get_psycopg2()
+        try:
+            with psycopg2.connect(self._db_url) as conn:
+                self._ensure_table(conn)
+                with conn.cursor() as cursor:
+                    cursor.execute(
+                        """
+                        SELECT settings, updated_at
+                        FROM phlo_settings
+                        WHERE scope = %s AND namespace = %s
+                        """,
+                        (scope.value, namespace),
+                    )
+                    row = cursor.fetchone()
+                    if not row:
+                        logger.debug(
+                            "observatory_settings_not_found",
+                            scope=scope.value,
+                            namespace=namespace,
+                        )
+                        return None
+                    settings, updated_at = row
+                    return SettingsRecord(
+                        scope=scope,
+                        namespace=namespace,
+                        settings=settings,
+                        updated_at=updated_at.isoformat() if updated_at else None,
+                    )
+        except Exception as exc:
+            if isinstance(exc, StorageUnavailableError):
+                raise
+            logger.warning("observatory_settings_storage_unavailable", scope=scope.value)
+            raise StorageUnavailableError("Settings storage is unavailable") from exc
+
+    def put(
+        self,
+        scope: SettingsScope,
+        namespace: str,
+        settings: dict[str, Any],
+        schema: dict[str, Any] | None = None,
+    ) -> SettingsRecord:
+        """Upsert settings for a scope and namespace."""
+        self._validate(settings, schema)
+        psycopg2 = _get_psycopg2()
+        json_settings = psycopg2.extras.Json(settings)
+        try:
+            with psycopg2.connect(self._db_url) as conn:
+                self._ensure_table(conn)
+                with conn.cursor() as cursor:
+                    cursor.execute(
+                        """
+                        INSERT INTO phlo_settings (scope, namespace, settings, updated_at)
+                        VALUES (%s, %s, %s, NOW())
+                        ON CONFLICT (scope, namespace)
+                        DO UPDATE SET settings = EXCLUDED.settings, updated_at = NOW()
+                        RETURNING settings, updated_at
+                        """,
+                        (scope.value, namespace, json_settings),
+                    )
+                    stored_settings, updated_at = cursor.fetchone()
+                    conn.commit()
+                    return SettingsRecord(
+                        scope=scope,
+                        namespace=namespace,
+                        settings=stored_settings,
+                        updated_at=updated_at.isoformat() if updated_at else None,
+                    )
+        except Exception as exc:
+            if isinstance(exc, (StorageUnavailableError, ValueError)):
+                raise
+            logger.warning("observatory_settings_storage_unavailable", scope=scope.value)
+            raise StorageUnavailableError("Settings storage is unavailable") from exc
+
+    def mutate(
+        self,
+        scope: SettingsScope,
+        namespace: str,
+        mutation: Callable[[dict[str, Any] | None], dict[str, Any]],
+    ) -> SettingsRecord:
+        """Apply ``mutation`` while holding the row lock for one settings record."""
+        psycopg2 = _get_psycopg2()
+        try:
+            with psycopg2.connect(self._db_url) as conn:
+                self._ensure_table(conn)
+                with conn.cursor() as cursor:
+                    # A row lock alone cannot lock an absent record. The advisory
+                    # transaction lock also serialises first-write migration and
+                    # mutation across independent API processes.
+                    cursor.execute(
+                        "SELECT pg_advisory_xact_lock(hashtext(%s))",
+                        (f"{scope.value}:{namespace}",),
+                    )
+                    cursor.execute(
+                        """
+                        SELECT settings FROM phlo_settings
+                        WHERE scope = %s AND namespace = %s
+                        FOR UPDATE
+                        """,
+                        (scope.value, namespace),
+                    )
+                    row = cursor.fetchone()
+                    settings = mutation(row[0] if row else None)
+                    cursor.execute(
+                        """
+                        INSERT INTO phlo_settings (scope, namespace, settings, updated_at)
+                        VALUES (%s, %s, %s, NOW())
+                        ON CONFLICT (scope, namespace)
+                        DO UPDATE SET settings = EXCLUDED.settings, updated_at = NOW()
+                        RETURNING settings, updated_at
+                        """,
+                        (scope.value, namespace, psycopg2.extras.Json(settings)),
+                    )
+                    stored_settings, updated_at = cursor.fetchone()
+                    conn.commit()
+                    return SettingsRecord(
+                        scope=scope,
+                        namespace=namespace,
+                        settings=stored_settings,
+                        updated_at=updated_at.isoformat() if updated_at else None,
+                    )
+        except Exception as exc:
+            if isinstance(exc, StorageUnavailableError):
+                raise
+            logger.warning("observatory_settings_storage_unavailable", scope=scope.value)
+            raise StorageUnavailableError("Settings storage is unavailable") from exc
+
+    def _validate(self, settings: dict[str, Any], schema: dict[str, Any] | None) -> None:
+        if not schema:
+            return
+        try:
+            validate(instance=settings, schema=schema)
+        except ValidationError as exc:
+            logger.warning("observatory_settings_validation_failed", error=str(exc))
+            raise ValueError(str(exc)) from exc
+
+    def _ensure_table(self, conn) -> None:
+        if self._table_ensured:
+            return
+        with conn.cursor() as cursor:
+            cursor.execute(
+                """
+                CREATE TABLE IF NOT EXISTS phlo_settings (
+                    scope TEXT NOT NULL,
+                    namespace TEXT NOT NULL,
+                    settings JSONB NOT NULL,
+                    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                    PRIMARY KEY (scope, namespace)
+                )
+                """
+            )
+            conn.commit()
+        self._table_ensured = True
+        logger.debug("observatory_settings_table_ensured")
+
+
+def get_settings_stores() -> list[SettingsStoreSpec]:
+    """Return capability specs for the PostgreSQL settings store."""
+    return [
+        SettingsStoreSpec(
+            name="postgres",
+            provider=PostgresSettingsStore(),
+        )
+    ]

phlo_postgres-0.14.0/src/phlo_postgres/volume_setup.yaml

@@ -0,0 +1,24 @@
+name: postgres-volume-setup
+description: Initialize PostgreSQL data volume permissions
+category: core
+default: false
+
+image: alpine:3.24.1@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b
+
+compose:
+  restart: "no"
+  user: "0:0"
+  entrypoint: /bin/sh
+  command: >
+    -c "
+    if [ -f /var/lib/postgresql/PG_VERSION ]; then
+      echo 'PostgreSQL 16 data volume detected. Back it up with PostgreSQL 16, then restore it into a new PostgreSQL 18 volume before starting Phlo.' >&2;
+      exit 1;
+    fi &&
+    mkdir -p /var/lib/postgresql &&
+    chown -R 70:70 /var/lib/postgresql &&
+    chmod 700 /var/lib/postgresql &&
+    echo 'Postgres data volume ownership initialized'
+    "
+  volumes:
+    - postgres-data:/var/lib/postgresql

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/src/phlo_postgres.egg-info/PKG-INFO

@@ -1,14 +1,13 @@
 Metadata-Version: 2.4
 Name: phlo-postgres
-Version: 0.3.2
+Version: 0.14.0
 Summary: Postgres service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT
 Requires-Python: >=3.11
 Description-Content-Type: text/plain
-Requires-Dist: phlo>=0.1.0
+Requires-Dist: phlo<0.15,>=0.14.0
 Requires-Dist: psycopg2-binary>=2.9.11
-Requires-Dist: pyyaml>=6.0.1
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/src/phlo_postgres.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/phlo_postgres/publish_target.py
 src/phlo_postgres/resource.py
 src/phlo_postgres/service.yaml
 src/phlo_postgres/settings.py
+src/phlo_postgres/settings_store.py
 src/phlo_postgres/volume_setup.yaml
 src/phlo_postgres.egg-info/PKG-INFO
 src/phlo_postgres.egg-info/SOURCES.txt
@@ -21,4 +22,5 @@ tests/test_authorization.py
 tests/test_integration_postgres.py
 tests/test_postgres_cli.py
 tests/test_postgres_plugin.py
-tests/test_resource.py
+tests/test_resource.py
+tests/test_settings_store.py

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/src/phlo_postgres.egg-info/requires.txt

@@ -1,6 +1,5 @@
-phlo>=0.1.0
+phlo<0.15,>=0.14.0
 psycopg2-binary>=2.9.11
-pyyaml>=6.0.1
 
 [dev]
 pytest>=7.0

{phlo_postgres-0.3.2 → phlo_postgres-0.14.0}/tests/test_authorization.py

@@ -111,7 +111,7 @@ class TestPostgresCliSurfaceAdapter:
         mock_result = MagicMock()
         mock_result.variant = "allow"
 
-        with patch("phlo_postgres.authorization.enforce", return_value=mock_result):
+        with patch("phlo.cli.authorization.enforce", return_value=mock_result):
             with patch.object(adapter, "_resolver"):
                 from phlo.capabilities.interfaces import AuthPrincipal