phlo-postgres 0.2.4__tar.gz → 0.3.1__tar.gz

{phlo_postgres-0.2.4 → phlo_postgres-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phlo-postgres
-Version: 0.2.4
+Version: 0.3.1
 Summary: Postgres service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT

{phlo_postgres-0.2.4 → phlo_postgres-0.3.1}/pyproject.toml

@@ -14,7 +14,7 @@ dependencies = [
 description = "Postgres service plugin for Phlo"
 name = "phlo-postgres"
 requires-python = ">=3.11"
-version = "0.2.4"
+version = "0.3.1"
 
 [[project.authors]]
 email = "team@phlo.dev"

phlo_postgres-0.3.1/src/phlo_postgres/__init__.py

@@ -0,0 +1,30 @@
+"""Phlo PostgreSQL metadata store package.
+
+This package provides the PostgreSQL integration for Phlo, including:
+- Service plugin for managing PostgreSQL containers
+- Resource management with connection pooling
+- CLI commands for database operations
+- Configuration settings management
+- Publish targets for serving data
+
+Example:
+    >>> from phlo_postgres import PostgresResource, get_settings
+    >>> settings = get_settings()
+    >>> with PostgresResource() as db:
+    ...     rows = db.query("SELECT * FROM users LIMIT 10")
+
+"""
+
+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
+
+__all__ = [
+    "PostgresPublishTarget",
+    "PostgresResource",
+    "PostgresServicePlugin",
+    "PostgresSettings",
+    "get_settings",
+]
+__version__ = "0.3.1"

phlo_postgres-0.3.1/src/phlo_postgres/authorization.py

@@ -0,0 +1,173 @@
+"""CLI regulated surface adapter for PostgreSQL.
+
+This module provides the regulated surface adapter for the PostgreSQL CLI,
+declaring mutation commands that require authorization and enforcing
+through core enforcement.
+
+Commands:
+- postgres query: Execute SQL (mutation - can be SELECT or DDL/DML)
+- postgres dump: Create database dump (mutation)
+- postgres restore: Restore from dump (mutation)
+- postgres vacuum: Run vacuumdb maintenance (mutation)
+- postgres: Raw psql passthrough (mutation)
+
+Resource/Action mapping:
+- dataset.query: SQL execution
+- dataset.manage: Database maintenance operations
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any
+
+from phlo.cli.authorization import CliPrincipalResolver
+from phlo.logging import get_logger
+from phlo.security.adapters import (
+    EnforcementResult,
+    SurfaceOperation,
+)
+from phlo.security.enforcement import enforce
+
+logger = get_logger(__name__)
+
+SURFACE_NAME = "phlo-postgres-cli"
+FRAMEWORK_TYPE = "cli"
+
+MUTATION_COMMANDS: frozenset[str] = frozenset(
+    {
+        "postgres.query",
+        "postgres.dump",
+        "postgres.restore",
+        "postgres.vacuum",
+        "postgres",
+    }
+)
+
+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",
+}
+
+
+class PostgresCliSurfaceAdapter:
+    """Regulated surface adapter for PostgreSQL CLI."""
+
+    _instance: PostgresCliSurfaceAdapter | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._resolver = CliPrincipalResolver()
+
+    @classmethod
+    def get_instance(cls) -> PostgresCliSurfaceAdapter:
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @property
+    def surface_name(self) -> str:
+        return SURFACE_NAME
+
+    @property
+    def framework_type(self) -> str:
+        return FRAMEWORK_TYPE
+
+    def list_operations(self) -> list[SurfaceOperation]:
+        operations: list[SurfaceOperation] = []
+        for command in MUTATION_COMMANDS:
+            resource_type = COMMAND_RESOURCE_MAP.get(command, "dataset")
+            action = COMMAND_ACTION_MAP.get(command, "dataset.query")
+            operations.append(
+                SurfaceOperation(
+                    action=action,
+                    resource_type=resource_type,
+                    operation_name=command,
+                    resource_id_strategy=None,
+                    framework_metadata={"command": command},
+                )
+            )
+        return operations
+
+    def is_active(self, runtime: Any) -> bool:
+        return True
+
+    def install(self, runtime: Any) -> None:
+        pass
+
+    def enforce_mutation(self, command: str, resource_id: str | None = None) -> EnforcementResult:
+        """Enforce authorization for a mutation command."""
+        if command not in MUTATION_COMMANDS:
+            return EnforcementResult.allow()
+
+        action = COMMAND_ACTION_MAP.get(command, "dataset.query")
+        resource_type = COMMAND_RESOURCE_MAP.get(command, "dataset")
+        resource_id_final = resource_id or f"postgres:{command}"
+
+        principal = self._resolver.resolve()
+
+        from phlo.capabilities.interfaces import ResourceRef
+
+        resource = ResourceRef(
+            resource_type=resource_type,
+            resource_id=resource_id_final,
+        )
+
+        request_id = os.environ.get("PHLO_REQUEST_ID")
+
+        result = enforce(
+            principal=principal,
+            action=action,
+            resource=resource,
+            context=None,
+            request_id=request_id,
+            surface=SURFACE_NAME,
+        )
+
+        logger.debug(
+            "postgres_cli_mutation_enforcement_result",
+            command=command,
+            action=action,
+            result=result.variant,
+            subject=principal.subject,
+        )
+
+        return result
+
+    def check_command_authorization(self, command_path: str) -> EnforcementResult:
+        """Check if a command is authorized to run."""
+        if command_path in READ_COMMANDS:
+            return EnforcementResult.allow()
+
+        if command_path in MUTATION_COMMANDS:
+            return self.enforce_mutation(command_path)
+
+        logger.warning(
+            "postgres_cli_unknown_command_classification",
+            command=command_path,
+        )
+        return EnforcementResult.deny(
+            reason_code="unknown_command",
+            explanation=f"Command '{command_path}' is not classified as read or mutation",
+        )
+
+
+def get_postgres_cli_adapter() -> PostgresCliSurfaceAdapter:
+    """Get the singleton PostgreSQL CLI surface adapter."""
+    return PostgresCliSurfaceAdapter.get_instance()

{phlo_postgres-0.2.4 → phlo_postgres-0.3.1}/src/phlo_postgres/cli.py

@@ -1,48 +1,106 @@
-"""CLI commands for the PostgreSQL service."""
+"""CLI commands for PostgreSQL service management.
+
+This module provides Click-based CLI commands for interacting with the PostgreSQL
+service, including running queries, dumping/restoring databases, and performing
+maintenance operations like vacuuming.
+
+All commands execute within the PostgreSQL container backend container via docker compose exec.
+
+Example:
+    $ phlo postgres query "SELECT * FROM users LIMIT 10"
+    $ phlo postgres dump --file backup.sql.gz
+    $ phlo postgres restore --file backup.sql.gz
+    $ phlo postgres vacuum --analyze
+
+"""
 
 from __future__ import annotations
 
 import gzip
 import subprocess
 from pathlib import Path
-from shutil import which
 from subprocess import TimeoutExpired
 
 import click
 
-from phlo.cli.commands.services.utils import ensure_phlo_dir
+from phlo.cli.commands.services.utils import (
+    ensure_compose_project,
+    require_container_backend as _require_selected_container_backend,
+)
 from phlo.cli.infrastructure.command import CommandError, run_command
 from phlo.cli.infrastructure.compose import compose_base_cmd
 from phlo.cli.infrastructure.utils import get_project_name
+from phlo.cli.output import (
+    command_failed_error,
+    empty_file_error,
+    exclusive_options_error,
+    file_read_error,
+)
+from phlo.cli.output import missing_query_error
 from phlo_postgres.settings import get_settings
 
 
 def _read_sql(*, query: str | None, file: Path | None) -> str:
-    """Return SQL text from inline query or file input."""
+    """Read SQL from inline query string or file path.
+
+    Validates that exactly one of query or file is provided and returns the
+    SQL content. Handles empty file detection and encoding issues.
+
+    Args:
+        query: Inline SQL query string.
+        file: Path to SQL file to read.
+
+    Returns:
+        str: The SQL content to execute.
+
+    Raises:
+        click.ClickException: If both query and file are provided, neither is
+            provided, or the file is empty/cannot be read.
+
+    Example:
+        >>> sql = _read_sql(query="SELECT 1")
+        >>> sql = _read_sql(file=Path("query.sql"))
+
+    """
     if query and file:
-        raise click.ClickException("Use either an inline query or --file, not both.")
+        raise exclusive_options_error("an inline query", "--file")
     if file is not None:
         try:
             sql = file.read_text(encoding="utf-8")
         except OSError as exc:
-            raise click.ClickException(f"Failed to read SQL file: {file}") from exc
+            raise file_read_error(file) from exc
         if sql.strip():
             return sql
-        raise click.ClickException(f"SQL file is empty: {file}")
+        raise empty_file_error(file)
     if query and query.strip():
         return query
-    raise click.ClickException("Provide a SQL query argument or --file.")
+    raise missing_query_error(command_hint='phlo postgres query "SELECT 1"')
 
 
-def _require_docker() -> None:
-    """Validate that Docker CLI is installed."""
-    if which("docker") is None:
-        raise click.ClickException("docker command not found.")
+def _require_container_backend() -> None:
+    """Validate that the selected container backend is available."""
+    _require_selected_container_backend()
 
 
 def _postgres_exec_base(*, tty: bool) -> list[str]:
-    """Build the docker compose exec command for the Postgres container."""
-    phlo_dir = ensure_phlo_dir()
+    """Build the docker compose exec base command for PostgreSQL container.
+
+    Constructs the initial portion of the docker compose exec command including
+    project name and service name. Used as a base for all container operations.
+
+    Args:
+        tty: Whether to allocate a TTY (-t flag). Disable for non-interactive
+            commands that capture output.
+
+    Returns:
+        list[str]: Base command as a list of strings ready for subprocess.
+
+    Example:
+        >>> cmd = _postgres_exec_base(tty=True)
+        >>> # Returns: ['docker', 'compose', '-p', 'phlo', '-f', '...', 'exec', '-t', 'postgres']
+
+    """
+    phlo_dir = ensure_compose_project()
     project_name = get_project_name()
     cmd = compose_base_cmd(phlo_dir=phlo_dir, project_name=project_name)
     cmd.append("exec")
@@ -53,7 +111,26 @@ def _postgres_exec_base(*, tty: bool) -> list[str]:
 
 
 def _postgres_identity(*, user: str | None, database: str | None) -> tuple[str, str]:
-    """Resolve effective Postgres user/database defaults."""
+    """Resolve PostgreSQL connection identity (user and database).
+
+    Returns explicit values if provided, otherwise falls back to settings
+    defaults. This allows CLI commands to use configured defaults while
+    permitting overrides.
+
+    Args:
+        user: Database username override, or None to use settings default.
+        database: Database name override, or None to use settings default.
+
+    Returns:
+        tuple[str, str]: Tuple of (resolved_user, resolved_database).
+
+    Example:
+        >>> user, db = _postgres_identity(user=None, database=None)
+        >>> # Uses settings.postgres_user and settings.postgres_db
+        >>> user, db = _postgres_identity(user="admin", database=None)
+        >>> # Uses "admin" for user, settings default for database
+
+    """
     settings = get_settings()
     return user or settings.postgres_user, database or settings.postgres_db
 
@@ -65,7 +142,24 @@ def _postgres_identity(*, user: str | None, database: str | None) -> tuple[str,
 @click.argument("postgres_args", nargs=-1, type=click.UNPROCESSED)
 @click.pass_context
 def postgres_group(ctx: click.Context, postgres_args: tuple[str, ...]) -> None:
-    """Run psql or Postgres helper commands against the project database."""
+    """Run psql or PostgreSQL helper commands against the project database.
+
+    This is the main entry point for PostgreSQL CLI operations. It supports:
+    - Interactive psql sessions (default if no subcommand)
+    - Subcommands: query, dump, restore, vacuum
+    - Direct psql arguments passthrough
+
+    Args:
+        ctx: Click context object.
+        postgres_args: Additional arguments passed to psql or subcommands.
+
+    Example:
+        $ phlo postgres                    # Interactive psql
+        $ phlo postgres -c "SELECT 1"       # One-off query via psql
+        $ phlo postgres query "SELECT * FROM users"
+        $ phlo postgres dump --file backup.sql.gz
+
+    """
     if postgres_args and postgres_args[0] == "query":
         postgres_query.main(
             args=list(postgres_args[1:]),
@@ -95,7 +189,7 @@ def postgres_group(ctx: click.Context, postgres_args: tuple[str, ...]) -> None:
         )
         return
 
-    _require_docker()
+    _require_container_backend()
     user, database = _postgres_identity(user=None, database=None)
     cmd = _postgres_exec_base(tty=True)
     cmd.extend(["psql", "-U", user, "-d", database])
@@ -122,8 +216,27 @@ def postgres_query(
     database: str | None,
     timeout_seconds: int,
 ) -> None:
-    """Execute a SQL query against the running PostgreSQL service."""
-    _require_docker()
+    """Execute a SQL query against the running PostgreSQL service.
+
+    Executes a SQL query inside the PostgreSQL container and prints results
+    to stdout. Supports inline queries or reading from a file.
+
+    Args:
+        query: SQL query string to execute.
+        query_file: Path to file containing SQL query.
+        user: Database user (default from settings).
+        database: Database name (default from settings).
+        timeout_seconds: Maximum time to wait for query completion.
+
+    Raises:
+        click.ClickException: If the query fails or times out.
+
+    Example:
+        $ phlo postgres query "SELECT * FROM users"
+        $ phlo postgres query --file query.sql --timeout 60
+
+    """
+    _require_container_backend()
     sql = _read_sql(query=query, file=query_file)
     resolved_user, resolved_db = _postgres_identity(user=user, database=database)
     cmd = _postgres_exec_base(tty=False)
@@ -138,7 +251,12 @@ def postgres_query(
         )
     except CommandError as exc:
         stderr = exc.stderr.strip()
-        raise click.ClickException(stderr or str(exc)) from exc
+        raise command_failed_error(
+            "psql",
+            exit_code=exc.returncode,
+            details=[stderr] if stderr else ["PostgreSQL did not complete the query."],
+            run="phlo services status postgres",
+        ) from exc
     except TimeoutExpired as exc:
         raise click.ClickException(f"Query timed out after {timeout_seconds} seconds.") from exc
 
@@ -163,8 +281,26 @@ def postgres_dump(
     database: str | None,
     timeout_seconds: int,
 ) -> None:
-    """Write a PostgreSQL logical backup to a local file."""
-    _require_docker()
+    """Create a PostgreSQL logical backup (pg_dump) to a local file.
+
+    Dumps the entire database using pg_dump, with optional gzip compression
+    if the output file has a .gz extension.
+
+    Args:
+        output_file: Path to write the dump. Use .gz extension for compression.
+        user: Database user (default from settings).
+        database: Database name (default from settings).
+        timeout_seconds: Maximum time to wait for dump completion.
+
+    Raises:
+        click.ClickException: If the dump fails or times out.
+
+    Example:
+        $ phlo postgres dump --file backup.sql
+        $ phlo postgres dump --file backup.sql.gz --timeout 300
+
+    """
+    _require_container_backend()
     resolved_user, resolved_db = _postgres_identity(user=user, database=database)
     cmd = _postgres_exec_base(tty=False)
     cmd.extend(["pg_dump", "-U", resolved_user, resolved_db])
@@ -178,7 +314,12 @@ def postgres_dump(
         )
     except CommandError as exc:
         stderr = exc.stderr.strip()
-        raise click.ClickException(stderr or str(exc)) from exc
+        raise command_failed_error(
+            "pg_dump",
+            exit_code=exc.returncode,
+            details=[stderr] if stderr else ["PostgreSQL did not create the dump."],
+            run="phlo services status postgres",
+        ) from exc
     except TimeoutExpired as exc:
         raise click.ClickException(f"Dump timed out after {timeout_seconds} seconds.") from exc
 
@@ -212,8 +353,29 @@ def postgres_restore(
     database: str | None,
     timeout_seconds: int,
 ) -> None:
-    """Restore a PostgreSQL logical backup from a local file."""
-    _require_docker()
+    """Restore a PostgreSQL database from a logical backup file.
+
+    Restores the database from a SQL dump file (plain or gzip-compressed).
+    Uses psql internally to execute the dump SQL.
+
+    Warning:
+        This may overwrite existing data. Use with caution on production databases.
+
+    Args:
+        input_file: Path to the dump file (.sql or .sql.gz).
+        user: Database user (default from settings).
+        database: Database name (default from settings).
+        timeout_seconds: Maximum time to wait for restore completion.
+
+    Raises:
+        click.ClickException: If the restore fails or times out.
+
+    Example:
+        $ phlo postgres restore --file backup.sql
+        $ phlo postgres restore --file backup.sql.gz --db mydb --timeout 600
+
+    """
+    _require_container_backend()
     resolved_user, resolved_db = _postgres_identity(user=user, database=database)
     cmd = _postgres_exec_base(tty=False)
     cmd.extend(["psql", "-U", resolved_user, "-d", resolved_db, "-v", "ON_ERROR_STOP=1"])
@@ -257,8 +419,27 @@ def postgres_vacuum(
     analyze: bool,
     timeout_seconds: int,
 ) -> None:
-    """Run vacuumdb inside the PostgreSQL service container."""
-    _require_docker()
+    """Run vacuumdb for PostgreSQL maintenance inside the container.
+
+    Executes vacuumdb to reclaim storage and optionally update statistics.
+    This is useful for routine database maintenance after large operations.
+
+    Args:
+        user: Database user (default from settings).
+        database: Database name (default from settings).
+        analyze: Whether to run ANALYZE after vacuum (updates statistics).
+        timeout_seconds: Maximum time to wait for vacuum completion.
+
+    Raises:
+        click.ClickException: If vacuum fails or times out.
+
+    Example:
+        $ phlo postgres vacuum
+        $ phlo postgres vacuum --no-analyze
+        $ phlo postgres vacuum --db analytics --timeout 300
+
+    """
+    _require_container_backend()
     resolved_user, resolved_db = _postgres_identity(user=user, database=database)
     cmd = _postgres_exec_base(tty=False)
     cmd.extend(["vacuumdb", "-U", resolved_user])

phlo_postgres-0.3.1/src/phlo_postgres/cli_plugin.py

@@ -0,0 +1,88 @@
+"""CLI plugin for PostgreSQL commands.
+
+This module provides the CLI plugin implementation that registers PostgreSQL
+commands with the phlo CLI system. It exposes the postgres command group and
+its subcommands (query, dump, restore, vacuum) to the main phlo CLI.
+
+Example:
+    >>> from phlo_postgres.cli_plugin import PostgresCliPlugin
+    >>> plugin = PostgresCliPlugin()
+    >>> commands = plugin.get_cli_commands()
+    >>> print(commands[0].name)
+    postgres
+
+"""
+
+from __future__ import annotations
+
+import click
+
+from phlo.plugins.base import CliCommandPlugin, PluginMetadata
+
+from phlo_postgres.cli import postgres_group
+
+
+class PostgresCliPlugin(CliCommandPlugin):
+    """CLI plugin that registers PostgreSQL commands with the phlo CLI.
+
+    This plugin provides the main entry point for PostgreSQL-related CLI
+    commands. It registers the postgres command group which includes
+    subcommands for querying, dumping, restoring, and maintaining PostgreSQL
+    databases.
+
+    Attributes:
+        None (uses class-level plugin registration).
+
+    Example:
+        >>> plugin = PostgresCliPlugin()
+        >>> print(plugin.metadata.name)
+        postgres
+        >>> commands = plugin.get_cli_commands()
+        >>> print([cmd.name for cmd in commands])
+        ['postgres']
+
+    """
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for the PostgreSQL CLI plugin.
+
+        Returns:
+            PluginMetadata: Metadata describing the CLI plugin including name,
+                version, and description for plugin discovery.
+
+        Example:
+            >>> plugin = PostgresCliPlugin()
+            >>> meta = plugin.metadata
+            >>> print(f"{meta.name} v{meta.version}")
+            postgres v0.1.0
+            >>> print(meta.description)
+            CLI commands for PostgreSQL service access
+
+        """
+        return PluginMetadata(
+            name="postgres",
+            version="0.1.0",
+            description="CLI commands for PostgreSQL service access",
+        )
+
+    def get_cli_commands(self) -> list[click.Command]:
+        """Return CLI commands provided by this plugin.
+
+        Returns:
+            list[click.Command]: List of Click command objects to register
+                with the main phlo CLI. Currently provides the postgres
+                command group which includes query, dump, restore, and
+                vacuum subcommands.
+
+        Example:
+            >>> plugin = PostgresCliPlugin()
+            >>> commands = plugin.get_cli_commands()
+            >>> cmd = commands[0]
+            >>> print(cmd.name)
+            postgres
+            >>> print([c.name for c in cmd.commands.values()])
+            ['query', 'dump', 'restore', 'vacuum']
+
+        """
+        return [postgres_group]