plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/__init__.py

@@ -0,0 +1,120 @@
+from .registry import models_registry, register_model  # noqa  Create the registry first
+from . import (
+    preflight,  # noqa  Imported for side effects (registers preflight checks)
+)
+
+# Imports that would create circular imports if sorted
+from .base import Model
+from .constraints import CheckConstraint, UniqueConstraint
+from .db import IntegrityError, get_connection
+from .deletion import CASCADE, DO_NOTHING, PROTECT, RESTRICT, SET, SET_DEFAULT, SET_NULL
+from .enums import IntegerChoices, TextChoices
+from .fields import (
+    BigIntegerField,
+    BinaryField,
+    BooleanField,
+    CharField,
+    DateField,
+    DateTimeField,
+    DecimalField,
+    DurationField,
+    EmailField,
+    FloatField,
+    GenericIPAddressField,
+    IntegerField,
+    PositiveBigIntegerField,
+    PositiveIntegerField,
+    PositiveSmallIntegerField,
+    PrimaryKeyField,
+    SmallIntegerField,
+    TextField,
+    TimeField,
+    URLField,
+    UUIDField,
+)
+from .fields.json import JSONField
+from .fields.timezones import TimeZoneField
+from .fields.related import (
+    ForeignKeyField,
+    ManyToManyField,
+)
+from .fields.reverse_descriptors import (
+    ReverseForeignKey,
+    ReverseManyToMany,
+)
+from .indexes import Index
+from .options import Options
+from .query import QuerySet
+from .query_utils import Q
+from . import types
+
+# This module exports the user-facing API for defining model classes,
+# with a secondary focus on the most common query utilities like Q.
+# Advanced query-time features (aggregates, expressions, etc.) should be
+# imported from their specific modules (e.g., plain.postgres.aggregates).
+__all__ = [
+    # From constraints
+    "CheckConstraint",
+    "UniqueConstraint",
+    # From enums
+    "IntegerChoices",
+    "TextChoices",
+    # From fields
+    "BigIntegerField",
+    "BinaryField",
+    "BooleanField",
+    "CharField",
+    "DateField",
+    "DateTimeField",
+    "DecimalField",
+    "DurationField",
+    "EmailField",
+    "FloatField",
+    "GenericIPAddressField",
+    "IntegerField",
+    "PositiveBigIntegerField",
+    "PositiveIntegerField",
+    "PositiveSmallIntegerField",
+    "PrimaryKeyField",
+    "SmallIntegerField",
+    "TextField",
+    "TimeField",
+    "URLField",
+    "UUIDField",
+    # From fields.json
+    "JSONField",
+    # From fields.timezones
+    "TimeZoneField",
+    # From indexes
+    "Index",
+    # From deletion
+    "CASCADE",
+    "DO_NOTHING",
+    "PROTECT",
+    "RESTRICT",
+    "SET",
+    "SET_DEFAULT",
+    "SET_NULL",
+    # From options
+    "Options",
+    # From query
+    "QuerySet",
+    # From query_utils
+    "Q",
+    # From base
+    "Model",
+    # From fields.related
+    "ForeignKeyField",
+    "ManyToManyField",
+    # From fields.reverse_descriptors
+    "ReverseForeignKey",
+    "ReverseManyToMany",
+    # From db
+    "get_connection",
+    "IntegrityError",
+    # From registry
+    "register_model",
+    "models_registry",
+    # Typed field imports
+    "types",
+]

plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -0,0 +1,78 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Database & Models
+
+## Field Imports
+
+Import fields via `from plain.postgres import types` and annotate with Python types:
+
+```python
+from plain.postgres import types
+
+name: str = types.CharField(max_length=100)
+car: Car = types.ForeignKeyField("Car", on_delete=postgres.CASCADE)
+```
+
+Do NOT import field classes directly from `plain.postgres` or `plain.postgres.fields`.
+
+## Schema Changes
+
+When creating new models or modifying existing model fields/relationships, always enter plan mode first. Database schema is hard to change after the fact, so get the design right before writing code.
+
+In your plan, present:
+
+- Proposed schema as a table (model, field, type, constraints)
+- Relationship cardinality (1:1, 1:N, M:N)
+- Key decisions: nullable vs default, indexing, cascade behavior
+- Whether the data could live on an existing model instead of a new one
+
+Get approval before writing any model code or generating migrations.
+
+## Migrations
+
+- `uv run plain makemigrations` — create migrations (`--dry-run` to preview, `--check` for CI)
+- `uv run plain migrate --backup` — apply migrations
+- `uv run plain migrations list` — view status (not `migrate --list`)
+- Before committing, consolidate multiple uncommitted migrations into one:
+  delete the intermediate files, run `migrations prune --yes` to clean stale DB records,
+  run `makemigrations` fresh, then `migrate --fake` to mark it applied
+- Use `migrations squash` only for already-committed/deployed migrations — never for dev cleanup
+- Only write migrations by hand for custom data migrations
+
+Run `uv run plain docs postgres --section migrations` for full workflow details.
+
+## Querying
+
+Use `Model.query` to build querysets (e.g., `User.query.filter(is_active=True)`).
+
+- Use `select_related()` for FK access in loops, `prefetch_related()` for reverse/M2N
+- Use `.annotate(Count(...))` instead of calling `.count()` per row
+- Fetch all data in the view — templates should never trigger queries
+- Use `.exists()` not `.count() > 0`, `.count()` not `len(qs)`
+- Use `bulk_create`/`bulk_update` for batch ops, `.update()`/`.delete()` for mass ops
+- Use `.values_list()` when you only need specific columns
+- Wrap multi-step writes in `transaction.atomic()`
+- Always paginate list queries — unbounded querysets get slower as data grows
+
+Run `uv run plain docs postgres --section querying` for full patterns with code examples.
+
+## Schema Design
+
+- Index fields used in `.filter()` and `.order_by()`
+- Use `UniqueConstraint` in constraints, not `unique=True` on fields
+- Choose `on_delete` deliberately: CASCADE for children, PROTECT for referenced data
+- No `allow_null` on string fields — use `default=""`
+
+Run `uv run plain docs postgres --section constraints` for full patterns with code examples.
+
+## Differences from Django
+
+- Use `Model.query` not `Model.objects`
+- Import fields from `plain.postgres.types` not `plain.postgres.fields` — and don't import field classes directly from `plain.postgres`
+- Use `model_options = postgres.Options(...)` not `class Meta`
+- Fields don't accept `unique=True` — use `UniqueConstraint` in constraints
+- Never format raw SQL strings — always use parameterized queries
+- Migrations are forward-only — no reverse migrations. `RunPython` takes a single callable (no `reverse_code` or `noop`). The callable signature is `fn(models, schema_editor)`, not `fn(apps, schema_editor)`

plain/postgres/aggregates.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from plain.postgres.exceptions import FieldError, FullResultSet
+from plain.postgres.expressions import (
+    Func,
+    ResolvableExpression,
+    Star,
+    Value,
+)
+from plain.postgres.fields import IntegerField
+from plain.postgres.functions.comparison import Coalesce
+from plain.postgres.functions.mixins import NumericOutputFieldMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from plain.postgres.connection import DatabaseConnection
+    from plain.postgres.expressions import Expression
+    from plain.postgres.query_utils import Q
+    from plain.postgres.sql.compiler import SQLCompiler
+
+
+__all__ = [
+    "Aggregate",
+    "Avg",
+    "Count",
+    "Max",
+    "Min",
+    "StdDev",
+    "Sum",
+    "Variance",
+]
+
+
+class Aggregate(Func):
+    template = "%(function)s(%(distinct)s%(expressions)s)"
+    contains_aggregate = True
+    name = None
+    filter_template = "%s FILTER (WHERE %%(filter)s)"
+    window_compatible = True
+    allow_distinct = False
+    empty_result_set_value = None
+
+    def __init__(
+        self,
+        *expressions: Any,
+        distinct: bool = False,
+        filter: Q | Expression | None = None,
+        default: Any = None,
+        **extra: Any,
+    ) -> None:
+        if distinct and not self.allow_distinct:
+            raise TypeError(f"{self.__class__.__name__} does not allow distinct.")
+        if default is not None and self.empty_result_set_value is not None:
+            raise TypeError(f"{self.__class__.__name__} does not allow default.")
+        self.distinct = distinct
+        self.filter = filter
+        self.default = default
+        super().__init__(*expressions, **extra)
+
+    def get_source_fields(self) -> list[Any]:
+        # Don't return the filter expression since it's not a source field.
+        return [e._output_field_or_none for e in super().get_source_expressions()]
+
+    def get_source_expressions(self) -> list[Expression]:
+        source_expressions = super().get_source_expressions()
+        if self.filter:
+            return source_expressions + [self.filter]
+        return source_expressions
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        exprs_list = list(exprs)
+        self.filter = self.filter and exprs_list.pop()
+        super().set_source_expressions(exprs_list)
+
+    def resolve_expression(  # type: ignore[override]
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Expression:
+        # Aggregates are not allowed in UPDATE queries, so ignore for_save
+        c = super().resolve_expression(query, allow_joins, reuse, summarize)
+        if c.filter is not None:
+            c.filter = c.filter.resolve_expression(query, allow_joins, reuse, summarize)
+        if not summarize:
+            # Call Aggregate.get_source_expressions() to avoid
+            # returning self.filter and including that in this loop.
+            expressions = super(Aggregate, c).get_source_expressions()
+            for index, expr in enumerate(expressions):
+                if expr.contains_aggregate:
+                    before_resolved = self.get_source_expressions()[index]
+                    name = (
+                        before_resolved.name
+                        if hasattr(before_resolved, "name")
+                        else repr(before_resolved)
+                    )
+                    raise FieldError(
+                        f"Cannot compute {c.name}('{name}'): '{name}' is an aggregate"
+                    )
+        if (default := c.default) is None:
+            return c
+        if isinstance(default, ResolvableExpression):
+            default = default.resolve_expression(query, allow_joins, reuse, summarize)
+            if default._output_field_or_none is None:
+                default.output_field = c._output_field_or_none
+        else:
+            default = Value(default, c._output_field_or_none)
+        c.default = None  # Reset the default argument before wrapping.
+        coalesce = Coalesce(c, default, output_field=c._output_field_or_none)
+        coalesce.is_summary = c.is_summary
+        return coalesce
+
+    @property
+    def default_alias(self) -> str:
+        expressions = self.get_source_expressions()
+        if len(expressions) == 1 and hasattr(expressions[0], "name"):
+            if self.name is None:
+                raise TypeError("Aggregate subclasses must define a name")
+            return f"{expressions[0].name}__{self.name.lower()}"
+        raise TypeError("Complex expressions require an alias")
+
+    def get_group_by_cols(self) -> list[Any]:
+        return []
+
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: DatabaseConnection,
+        function: str | None = None,
+        template: str | None = None,
+        arg_joiner: str | None = None,
+        **extra_context: Any,
+    ) -> tuple[str, list[Any]]:
+        extra_context["distinct"] = "DISTINCT " if self.distinct else ""
+        if self.filter is not None:
+            # Use FILTER clause for aggregates when filter is specified
+            try:
+                filter_sql, filter_params = self.filter.as_sql(compiler, connection)  # type: ignore[union-attr]
+            except FullResultSet:
+                pass
+            else:
+                filter_template = self.filter_template % extra_context.get(
+                    "template", template or self.template
+                )
+                sql, params = super().as_sql(
+                    compiler,
+                    connection,
+                    function=function,
+                    template=filter_template,
+                    arg_joiner=arg_joiner,
+                    filter=filter_sql,
+                    **extra_context,
+                )
+                return sql, [*params, *filter_params]
+        return super().as_sql(
+            compiler,
+            connection,
+            function=function,
+            template=template,
+            arg_joiner=arg_joiner,
+            **extra_context,
+        )
+
+    def _get_repr_options(self) -> dict[str, Any]:
+        options = super()._get_repr_options()
+        if self.distinct:
+            options["distinct"] = self.distinct
+        if self.filter:
+            options["filter"] = self.filter
+        return options
+
+
+class Avg(NumericOutputFieldMixin, Aggregate):
+    function = "AVG"
+    name = "Avg"
+    allow_distinct = True
+
+
+class Count(Aggregate):
+    function = "COUNT"
+    name = "Count"
+    output_field = IntegerField()
+    allow_distinct = True
+    empty_result_set_value = 0
+
+    def __init__(
+        self, expression: Any, filter: Q | Expression | None = None, **extra: Any
+    ) -> None:
+        if expression == "*":
+            expression = Star()
+        if isinstance(expression, Star) and filter is not None:
+            raise ValueError("Star cannot be used with filter. Please specify a field.")
+        super().__init__(expression, filter=filter, **extra)
+
+
+class Max(Aggregate):
+    function = "MAX"
+    name = "Max"
+
+
+class Min(Aggregate):
+    function = "MIN"
+    name = "Min"
+
+
+class StdDev(NumericOutputFieldMixin, Aggregate):
+    name = "StdDev"
+
+    def __init__(self, expression: Any, sample: bool = False, **extra: Any) -> None:
+        self.function = "STDDEV_SAMP" if sample else "STDDEV_POP"
+        super().__init__(expression, **extra)
+
+    def _get_repr_options(self) -> dict[str, Any]:
+        return {**super()._get_repr_options(), "sample": self.function == "STDDEV_SAMP"}
+
+
+class Sum(Aggregate):
+    function = "SUM"
+    name = "Sum"
+    allow_distinct = True
+
+
+class Variance(NumericOutputFieldMixin, Aggregate):
+    name = "Variance"
+
+    def __init__(self, expression: Any, sample: bool = False, **extra: Any) -> None:
+        self.function = "VAR_SAMP" if sample else "VAR_POP"
+        super().__init__(expression, **extra)
+
+    def _get_repr_options(self) -> dict[str, Any]:
+        return {**super()._get_repr_options(), "sample": self.function == "VAR_SAMP"}

plain/postgres/backups/cli.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+import click
+
+from .core import DatabaseBackups, get_git_branch
+
+
+@click.group("backups")
+def cli() -> None:
+    """Local database backups"""
+    pass
+
+
+@cli.command("list")
+@click.option(
+    "--branch",
+    "branch",
+    is_flag=False,
+    flag_value="__current__",
+    default=None,
+    help="Filter by branch (defaults to current branch if flag used without value)",
+)
+def list_backups(branch: str | None) -> None:
+    """List database backups"""
+    backups_handler = DatabaseBackups()
+    backups = backups_handler.find_backups()
+
+    # Resolve branch filter
+    if branch == "__current__":
+        branch = get_git_branch()
+
+    # Filter by branch if specified
+    if branch:
+        backups = [b for b in backups if b.metadata.get("git_branch") == branch]
+
+    if not backups:
+        if branch:
+            click.secho(f"No backups found for branch '{branch}'", fg="yellow")
+        else:
+            click.secho("No backups found", fg="yellow")
+        return
+
+    # Calculate column widths
+    name_width = max(len(b.name) for b in backups)
+    source_width = max(len(b.metadata.get("source") or "-") for b in backups)
+
+    # Print header
+    click.secho(
+        f"{'NAME':<{name_width}}  {'SOURCE':<{source_width}}  {'SIZE':<10}  BRANCH",
+        dim=True,
+    )
+
+    # Print rows
+    for backup in backups:
+        backup_file = backup.path / "default.backup"
+        if backup_file.exists():
+            size = os.path.getsize(backup_file)
+            size_str = f"{size / 1024 / 1024:.2f} MB"
+        else:
+            size_str = "-"
+        metadata = backup.metadata
+        source = metadata.get("source") or "-"
+        git_branch = metadata.get("git_branch") or "-"
+
+        click.echo(
+            f"{backup.name:<{name_width}}  {source:<{source_width}}  {size_str:<10}  {git_branch}"
+        )
+
+
+@cli.command("create")
+@click.option("--pg-dump", default="pg_dump", envvar="PG_DUMP")
+@click.argument("backup_name", default="")
+def create_backup(backup_name: str, pg_dump: str) -> None:
+    """Create a database backup"""
+    backups_handler = DatabaseBackups()
+
+    if not backup_name:
+        backup_name = time.strftime("%Y%m%d_%H%M%S")
+
+    try:
+        backup_dir = backups_handler.create(
+            backup_name,
+            source="manual",
+            pg_dump=pg_dump,
+        )
+    except Exception as e:
+        click.secho(str(e), fg="red")
+        exit(1)
+
+    click.secho(f"Backup created in {backup_dir.relative_to(Path.cwd())}", fg="green")
+
+
+@cli.command("restore")
+@click.option("--latest", is_flag=True)
+@click.option("--pg-restore", default="pg_restore", envvar="PG_RESTORE")
+@click.argument("backup_name", default="")
+def restore_backup(backup_name: str, latest: bool, pg_restore: str) -> None:
+    """Restore a database backup"""
+    backups_handler = DatabaseBackups()
+
+    if backup_name and latest:
+        raise click.UsageError("Only one of --latest or backup_name is allowed")
+
+    if not backup_name and not latest:
+        raise click.UsageError("Backup name or --latest is required")
+
+    if not backup_name and latest:
+        backup_name = backups_handler.find_backups()[0].name
+
+    click.secho(f"Restoring backup {backup_name}...", bold=True)
+
+    try:
+        backups_handler.restore(
+            backup_name,
+            pg_restore=pg_restore,
+        )
+    except Exception as e:
+        click.secho(str(e), fg="red")
+        exit(1)
+    click.echo(f"Backup {backup_name} restored successfully.")
+
+
+@cli.command("delete")
+@click.argument("backup_name")
+def delete_backup(backup_name: str) -> None:
+    """Delete a database backup"""
+    backups_handler = DatabaseBackups()
+    try:
+        backups_handler.delete(backup_name)
+    except Exception as e:
+        click.secho(str(e), fg="red")
+        return
+    click.secho(f"Backup {backup_name} deleted", fg="green")
+
+
+@cli.command("clear")
+@click.confirmation_option(prompt="Are you sure you want to delete all backups?")
+def clear_backups() -> None:
+    """Clear all database backups"""
+    backups_handler = DatabaseBackups()
+    backups = backups_handler.find_backups()
+    for backup in backups:
+        backup.delete()
+    click.secho("All backups deleted", fg="green")

plain/postgres/backups/clients.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from plain.exceptions import ImproperlyConfigured
+
+if TYPE_CHECKING:
+    from plain.postgres.connection import DatabaseConnection
+
+
+class PostgresBackupClient:
+    def __init__(self, connection: DatabaseConnection) -> None:
+        self.connection = connection
+
+    def get_env(self) -> dict[str, str]:
+        settings_dict = self.connection.settings_dict
+        options = settings_dict.get("OPTIONS", {})
+        env: dict[str, str] = {}
+
+        if password := settings_dict.get("PASSWORD"):
+            env["PGPASSWORD"] = str(password)
+
+        # Map OPTIONS keys to their corresponding environment variables.
+        option_env_vars = {
+            "passfile": "PGPASSFILE",
+            "sslmode": "PGSSLMODE",
+            "sslrootcert": "PGSSLROOTCERT",
+            "sslcert": "PGSSLCERT",
+            "sslkey": "PGSSLKEY",
+        }
+        for option_key, env_var in option_env_vars.items():
+            if value := options.get(option_key):
+                env[env_var] = str(value)
+
+        return env
+
+    def _get_conn_args(self) -> list[str]:
+        """Build common connection CLI args from settings."""
+        settings_dict = self.connection.settings_dict
+        args: list[str] = []
+        if user := settings_dict.get("USER"):
+            args += ["-U", user]
+        if host := settings_dict.get("HOST"):
+            args += ["-h", host]
+        if port := settings_dict.get("PORT"):
+            args += ["-p", str(port)]
+        return args
+
+    def _run(self, cmd: str | list[str], *, shell: bool = False) -> None:
+        subprocess.run(
+            cmd, env={**os.environ, **self.get_env()}, check=True, shell=shell
+        )
+
+    def create_backup(self, backup_path: Path, *, pg_dump: str = "pg_dump") -> None:
+        settings_dict = self.connection.settings_dict
+        dbname = settings_dict.get("DATABASE")
+        if not dbname:
+            raise ImproperlyConfigured("POSTGRES_DATABASE is required in settings")
+
+        args = pg_dump.split() + self._get_conn_args()
+        args += ["-Fc", dbname]
+
+        # Pipe through gzip for compression
+        args += ["|", "gzip", ">", str(backup_path)]
+        self._run(" ".join(args), shell=True)
+
+    def restore_backup(
+        self, backup_path: Path, *, pg_restore: str = "pg_restore", psql: str = "psql"
+    ) -> None:
+        settings_dict = self.connection.settings_dict
+        dbname = settings_dict.get("DATABASE")
+        if not dbname:
+            raise ImproperlyConfigured("POSTGRES_DATABASE is required in settings")
+
+        conn_args = self._get_conn_args()
+
+        # Drop and recreate the database via template1
+        drop_create_cmds = [
+            f"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '{dbname}' AND pid <> pg_backend_pid()",
+            f'DROP DATABASE IF EXISTS "{dbname}"',
+            f'CREATE DATABASE "{dbname}"',
+        ]
+        for sql in drop_create_cmds:
+            self._run(psql.split() + conn_args + ["-d", "template1", "-c", sql])
+
+        # Restore into the fresh database
+        args = pg_restore.split() + conn_args + ["-d", dbname]
+
+        # Pipe through gunzip for decompression
+        args = ["gunzip", "<", str(backup_path), "|"] + args
+        self._run(" ".join(args), shell=True)