phlo-postgres 0.1.0__tar.gz → 0.2.3__tar.gz

{phlo_postgres-0.1.0 → phlo_postgres-0.2.3}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: phlo-postgres
-Version: 0.1.0
+Version: 0.2.3
 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: psycopg2-binary>=2.9.11
 Requires-Dist: pyyaml>=6.0.1
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"

phlo_postgres-0.2.3/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+    "setuptools>=45",
+    "wheel",
+]
+
+[project]
+dependencies = [
+    "phlo>=0.1.0",
+    "psycopg2-binary>=2.9.11",
+    "pyyaml>=6.0.1",
+]
+description = "Postgres service plugin for Phlo"
+name = "phlo-postgres"
+requires-python = ">=3.11"
+version = "0.2.3"
+
+[[project.authors]]
+email = "team@phlo.dev"
+name = "Phlo Team"
+
+[project.entry-points."phlo.plugins.cli"]
+postgres = "phlo_postgres.cli_plugin:PostgresCliPlugin"
+
+[project.entry-points."phlo.plugins.resources"]
+postgres = "phlo_postgres.plugin:PostgresResourceProvider"
+
+[project.entry-points."phlo.plugins.services"]
+postgres = "phlo_postgres.plugin:PostgresServicePlugin"
+postgres-exporter = "phlo_postgres.plugin:PostgresExporterServicePlugin"
+postgres-volume-setup = "phlo_postgres.plugin:PostgresVolumeSetupServicePlugin"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1.0",
+]
+
+[project.readme]
+content-type = "text/plain"
+text = "Postgres service plugin for Phlo."
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+phlo_postgres = [
+    "service.yaml",
+    "exporter_service.yaml",
+    "volume_setup.yaml",
+]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]

phlo_postgres-0.2.3/src/phlo_postgres/__init__.py

@@ -0,0 +1,15 @@
+"""Postgres service plugin package."""
+
+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.2.3"

phlo_postgres-0.2.3/src/phlo_postgres/cli.py

@@ -0,0 +1,283 @@
+"""CLI commands for the PostgreSQL service."""
+
+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.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_postgres.settings import get_settings
+
+
+def _read_sql(*, query: str | None, file: Path | None) -> str:
+    """Return SQL text from inline query or file input."""
+    if query and file:
+        raise click.ClickException("Use either an inline query or --file, not both.")
+    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
+        if sql.strip():
+            return sql
+        raise click.ClickException(f"SQL file is empty: {file}")
+    if query and query.strip():
+        return query
+    raise click.ClickException("Provide a SQL query argument or --file.")
+
+
+def _require_docker() -> None:
+    """Validate that Docker CLI is installed."""
+    if which("docker") is None:
+        raise click.ClickException("docker command not found.")
+
+
+def _postgres_exec_base(*, tty: bool) -> list[str]:
+    """Build the docker compose exec command for the Postgres container."""
+    phlo_dir = ensure_phlo_dir()
+    project_name = get_project_name()
+    cmd = compose_base_cmd(phlo_dir=phlo_dir, project_name=project_name)
+    cmd.append("exec")
+    if not tty:
+        cmd.append("-T")
+    cmd.append("postgres")
+    return cmd
+
+
+def _postgres_identity(*, user: str | None, database: str | None) -> tuple[str, str]:
+    """Resolve effective Postgres user/database defaults."""
+    settings = get_settings()
+    return user or settings.postgres_user, database or settings.postgres_db
+
+
+@click.command(
+    name="postgres",
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@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."""
+    if postgres_args and postgres_args[0] == "query":
+        postgres_query.main(
+            args=list(postgres_args[1:]),
+            prog_name="phlo postgres query",
+            standalone_mode=False,
+        )
+        return
+    if postgres_args and postgres_args[0] == "dump":
+        postgres_dump.main(
+            args=list(postgres_args[1:]),
+            prog_name="phlo postgres dump",
+            standalone_mode=False,
+        )
+        return
+    if postgres_args and postgres_args[0] == "restore":
+        postgres_restore.main(
+            args=list(postgres_args[1:]),
+            prog_name="phlo postgres restore",
+            standalone_mode=False,
+        )
+        return
+    if postgres_args and postgres_args[0] == "vacuum":
+        postgres_vacuum.main(
+            args=list(postgres_args[1:]),
+            prog_name="phlo postgres vacuum",
+            standalone_mode=False,
+        )
+        return
+
+    _require_docker()
+    user, database = _postgres_identity(user=None, database=None)
+    cmd = _postgres_exec_base(tty=True)
+    cmd.extend(["psql", "-U", user, "-d", database])
+    cmd.extend(postgres_args)
+    result = subprocess.run(cmd, check=False)
+    if result.returncode != 0:
+        raise click.ClickException(f"psql exited with status {result.returncode}.")
+
+
+@click.command(name="query")
+@click.argument("query", required=False)
+@click.option(
+    "--file",
+    "query_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option("--user", default=None, help="Database user.")
+@click.option("--db", "database", default=None, help="Database name.")
+@click.option("--timeout", "timeout_seconds", default=30, show_default=True, type=int)
+def postgres_query(
+    query: str | None,
+    query_file: Path | None,
+    user: str | None,
+    database: str | None,
+    timeout_seconds: int,
+) -> None:
+    """Execute a SQL query against the running PostgreSQL service."""
+    _require_docker()
+    sql = _read_sql(query=query, file=query_file)
+    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", "-c", sql])
+
+    try:
+        result = run_command(
+            cmd,
+            timeout_seconds=timeout_seconds,
+            capture_output=True,
+            check=True,
+        )
+    except CommandError as exc:
+        stderr = exc.stderr.strip()
+        raise click.ClickException(stderr or str(exc)) from exc
+    except TimeoutExpired as exc:
+        raise click.ClickException(f"Query timed out after {timeout_seconds} seconds.") from exc
+
+    if result.stdout:
+        click.echo(result.stdout, nl=False)
+
+
+@click.command(name="dump")
+@click.option(
+    "--file",
+    "output_file",
+    type=click.Path(dir_okay=False, path_type=Path),
+    required=True,
+    help="Output path. Use .gz for gzip-compressed dumps.",
+)
+@click.option("--user", default=None, help="Database user.")
+@click.option("--db", "database", default=None, help="Database name.")
+@click.option("--timeout", "timeout_seconds", default=120, show_default=True, type=int)
+def postgres_dump(
+    output_file: Path,
+    user: str | None,
+    database: str | None,
+    timeout_seconds: int,
+) -> None:
+    """Write a PostgreSQL logical backup to a local file."""
+    _require_docker()
+    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])
+
+    try:
+        result = run_command(
+            cmd,
+            timeout_seconds=timeout_seconds,
+            capture_output=True,
+            check=True,
+        )
+    except CommandError as exc:
+        stderr = exc.stderr.strip()
+        raise click.ClickException(stderr or str(exc)) from exc
+    except TimeoutExpired as exc:
+        raise click.ClickException(f"Dump timed out after {timeout_seconds} seconds.") from exc
+
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        if output_file.suffix == ".gz":
+            with gzip.open(output_file, "wt", encoding="utf-8") as handle:
+                handle.write(result.stdout)
+        else:
+            output_file.write_text(result.stdout, encoding="utf-8")
+    except OSError as exc:
+        raise click.ClickException(f"Failed to write dump file: {output_file}") from exc
+
+    click.echo(f"Wrote dump to {output_file}")
+
+
+@click.command(name="restore")
+@click.option(
+    "--file",
+    "input_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    required=True,
+    help="Input dump file. Supports .sql and .gz files.",
+)
+@click.option("--user", default=None, help="Database user.")
+@click.option("--db", "database", default=None, help="Database name.")
+@click.option("--timeout", "timeout_seconds", default=120, show_default=True, type=int)
+def postgres_restore(
+    input_file: Path,
+    user: str | None,
+    database: str | None,
+    timeout_seconds: int,
+) -> None:
+    """Restore a PostgreSQL logical backup from a local file."""
+    _require_docker()
+    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"])
+
+    try:
+        if input_file.suffix == ".gz":
+            with gzip.open(input_file, "rt", encoding="utf-8") as handle:
+                sql = handle.read()
+        else:
+            sql = input_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise click.ClickException(f"Failed to read restore file: {input_file}") from exc
+
+    try:
+        result = subprocess.run(
+            cmd,
+            input=sql,
+            text=True,
+            capture_output=True,
+            timeout=timeout_seconds,
+            check=False,
+        )
+    except TimeoutExpired as exc:
+        raise click.ClickException(f"Restore timed out after {timeout_seconds} seconds.") from exc
+
+    if result.returncode != 0:
+        stderr = (result.stderr or "").strip()
+        raise click.ClickException(stderr or f"Restore failed with status {result.returncode}.")
+
+    click.echo(f"Restored {input_file} into {resolved_db}")
+
+
+@click.command(name="vacuum")
+@click.option("--user", default=None, help="Database user.")
+@click.option("--db", "database", default=None, help="Database name.")
+@click.option("--analyze/--no-analyze", default=True, show_default=True)
+@click.option("--timeout", "timeout_seconds", default=120, show_default=True, type=int)
+def postgres_vacuum(
+    user: str | None,
+    database: str | None,
+    analyze: bool,
+    timeout_seconds: int,
+) -> None:
+    """Run vacuumdb inside the PostgreSQL service container."""
+    _require_docker()
+    resolved_user, resolved_db = _postgres_identity(user=user, database=database)
+    cmd = _postgres_exec_base(tty=False)
+    cmd.extend(["vacuumdb", "-U", resolved_user])
+    if analyze:
+        cmd.append("-z")
+    cmd.append(resolved_db)
+
+    try:
+        result = run_command(
+            cmd,
+            timeout_seconds=timeout_seconds,
+            capture_output=True,
+            check=True,
+        )
+    except CommandError as exc:
+        stderr = exc.stderr.strip()
+        raise click.ClickException(stderr or str(exc)) from exc
+    except TimeoutExpired as exc:
+        raise click.ClickException(f"Vacuum timed out after {timeout_seconds} seconds.") from exc
+
+    if result.stdout:
+        click.echo(result.stdout, nl=False)

phlo_postgres-0.2.3/src/phlo_postgres/cli_plugin.py

@@ -0,0 +1,24 @@
+"""CLI plugin for PostgreSQL commands."""
+
+from __future__ import annotations
+
+import click
+
+from phlo.plugins.base import CliCommandPlugin, PluginMetadata
+
+from phlo_postgres.cli import postgres_group
+
+
+class PostgresCliPlugin(CliCommandPlugin):
+    """Register PostgreSQL CLI commands."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        return PluginMetadata(
+            name="postgres",
+            version="0.1.0",
+            description="CLI commands for PostgreSQL service access",
+        )
+
+    def get_cli_commands(self) -> list[click.Command]:
+        return [postgres_group]

phlo_postgres-0.2.3/src/phlo_postgres/plugin.py

@@ -0,0 +1,127 @@
+"""Postgres service plugin."""
+
+from __future__ import annotations
+
+from importlib import resources
+from typing import Any
+
+import yaml
+from phlo.capabilities import PublishTargetSpec, ResourceSpec
+from phlo.plugins import PluginMetadata, ResourceProviderPlugin, ServicePlugin
+
+from phlo_postgres.publish_target import PostgresPublishTarget
+from phlo_postgres.resource import PostgresResource
+
+
+class PostgresServicePlugin(ServicePlugin):
+    """Service plugin for Postgres."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for the Postgres service.
+
+        Returns:
+            PluginMetadata: Metadata describing the service plugin.
+        """
+        return PluginMetadata(
+            name="postgres",
+            version="0.1.0",
+            description="PostgreSQL database for metadata and operational storage",
+            author="Phlo Team",
+            tags=["core", "database", "postgres"],
+        )
+
+    @property
+    def service_definition(self) -> dict[str, Any]:
+        """Load the Postgres service definition from package data.
+
+        Returns:
+            dict[str, Any]: Parsed Docker Compose service definition.
+        """
+        service_path = resources.files("phlo_postgres").joinpath("service.yaml")
+        return yaml.safe_load(service_path.read_text(encoding="utf-8"))
+
+
+class PostgresExporterServicePlugin(ServicePlugin):
+    """Service plugin for Postgres Prometheus exporter."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for the Postgres exporter service.
+
+        Returns:
+            PluginMetadata: Metadata describing the exporter plugin.
+        """
+        return PluginMetadata(
+            name="postgres-exporter",
+            version="0.1.0",
+            description="Prometheus exporter for PostgreSQL metrics",
+            author="Phlo Team",
+            tags=["observability", "metrics", "postgres"],
+        )
+
+    @property
+    def service_definition(self) -> dict[str, Any]:
+        """Load the Postgres exporter service definition from package data.
+
+        Returns:
+            dict[str, Any]: Parsed Docker Compose service definition.
+        """
+        service_path = resources.files("phlo_postgres").joinpath("exporter_service.yaml")
+        return yaml.safe_load(service_path.read_text(encoding="utf-8"))
+
+
+class PostgresVolumeSetupServicePlugin(ServicePlugin):
+    """Service plugin for PostgreSQL bind-mount ownership bootstrap."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for the Postgres volume setup service."""
+        return PluginMetadata(
+            name="postgres-volume-setup",
+            version="0.1.0",
+            description="Initialize PostgreSQL data volume permissions",
+            author="Phlo Team",
+            tags=["core", "database", "postgres"],
+        )
+
+    @property
+    def service_definition(self) -> dict[str, Any]:
+        """Load the Postgres volume setup definition from package data."""
+        service_path = resources.files("phlo_postgres").joinpath("volume_setup.yaml")
+        return yaml.safe_load(service_path.read_text(encoding="utf-8"))
+
+
+class PostgresResourceProvider(ResourceProviderPlugin):
+    """Resource provider plugin that exposes the Postgres resource."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for the Postgres resource provider.
+
+        Returns:
+            PluginMetadata: Metadata describing the resource provider plugin.
+        """
+        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]: Registered resource specifications.
+        """
+        return [ResourceSpec(name="postgres", resource=PostgresResource())]
+
+    def get_publish_targets(self) -> list[PublishTargetSpec]:
+        """Return publish target capability specs exposed by this provider."""
+        return [
+            PublishTargetSpec(
+                name="postgres",
+                provider=PostgresPublishTarget(),
+                metadata={"target_system": "postgres", "role": "serving"},
+            )
+        ]

phlo_postgres-0.2.3/src/phlo_postgres/publish_target.py

@@ -0,0 +1,21 @@
+"""Publish target wrapper for Postgres serving outputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from phlo_postgres.resource import PostgresResource
+from phlo_postgres.settings import get_settings
+
+
+@dataclass
+class PostgresPublishTarget:
+    """Structured publish target for Postgres serving tables."""
+
+    resource: PostgresResource = field(default_factory=PostgresResource)
+    target_system: str = "postgres"
+
+    @property
+    def default_schema(self) -> str:
+        """Return the default serving schema for published mart tables."""
+        return get_settings().postgres_mart_schema