sqlnotify 0.1.0__py3-none-any.whl

sqlnotify/utils.py

@@ -0,0 +1,165 @@
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from .constants import MAX_SQLNOTIFY_IDENTIFER_BYTES, MAX_SQLNOTIFY_PAYLOAD_BYTES
+from .exceptions import SQLNotifyIdentifierSizeError, SQLNotifyPayloadSizeError
+
+
+def extract_database_url(engine: AsyncEngine | Engine) -> str:
+    """
+    Extract the database URL from an engine for use with asyncpg LISTEN.
+
+    Converts SQLAlchemy URL format to plain PostgreSQL URL suitable for asyncpg.
+
+    Args:
+        engine (Union[AsyncEngine, Engine]): SQLAlchemy Engine or AsyncEngine
+
+    Returns:
+        str: PostgreSQL connection URL suitable for asyncpg
+    """
+
+    url = engine.url.render_as_string(hide_password=False)
+
+    sqlite_drivers = ["+aiosqlite"]
+    postgres_drivers = ["+asyncpg", "+aiopg", "+psycopg2", "+psycopg", "+pg8000"]
+
+    if "sqlite" in url:
+        for driver in sorted(sqlite_drivers, key=len, reverse=True):
+            url = url.replace(f"sqlite{driver}", "sqlite")
+    elif "postgresql" in url:
+        for driver in sorted(postgres_drivers, key=len, reverse=True):
+            url = url.replace(f"postgresql{driver}", "postgresql")
+
+    return url
+
+
+def strip_database_query_params(db_url: str) -> str:
+    """
+    Strip query parameters from a PostgreSQL connection URL.
+
+    Args:
+        db_url (str): PostgreSQL connection URL
+
+    Returns:
+        str: Connection URL without query parameters
+
+    """
+
+    if "?" in db_url:
+        db_url = db_url.split("?", 1)[0]
+
+    return db_url
+
+
+def replace_spaces_with_underscores(name: str) -> str:
+    """
+    Replace spaces in a string with underscores.
+
+    Args:
+        name (str): Input string
+
+    Returns:
+        str: String with spaces replaced by underscores
+    """
+
+    return name.strip().replace(" ", "_")
+
+
+def validate_payload_size(payload_str: str, allow_overflow: bool = False) -> bool:
+    """
+    Validate payload size doesn't exceed PostgreSQL limit.
+
+    Args:
+        payload_str (str): JSON payload string
+        allow_overflow (bool): If True, returns False instead of raising exception
+
+    Returns:
+        bool: True if valid, False if overflow and allow_overflow=True
+
+    Raises:
+        SQLNotifyPayloadSizeError: If payload too large and allow_overflow=False
+    """
+
+    payload_bytes = len(payload_str.encode("utf-8"))
+
+    if payload_bytes > MAX_SQLNOTIFY_PAYLOAD_BYTES:
+        if allow_overflow:
+            return False
+
+        raise SQLNotifyPayloadSizeError(
+            f"Payload size {payload_bytes} bytes exceeds SQLNotify "
+            f"limit of {MAX_SQLNOTIFY_PAYLOAD_BYTES} bytes. "
+            f"Consider: (1) reducing extra_columns, (2) using use_overflow_table=True, "
+            f"or (3) sending only ID and fetching full data from database."
+        )
+
+    return True
+
+
+def hash_identifier(s: str, max_length: int = 20) -> str:
+    """
+    Hash an identifier string to a shorter unique string using SHA-256.
+
+    Uses cryptographic hashing to minimize collision probability while keeping
+    the output short enough for PostgreSQL identifier limits (63 bytes).
+
+    Args:
+        s (str): Input string to hash
+        max_length (int): Maximum length of output string (default: 20 chars = ~50 bytes)
+
+    Returns:
+        str: Hashed string value, significantly shorter than input with very low collision probability
+
+    Note:
+        While collisions are theoretically possible with any hash, SHA-256 truncated to 20 characters
+        (80 bits) provides ~1.2e24 possible values, making collisions extremely unlikely in practice.
+    """
+    import hashlib
+
+    hash_bytes = hashlib.sha256(s.encode("utf-8")).digest()
+
+    hex_hash = hash_bytes.hex()[:max_length]
+
+    return hex_hash
+
+
+def validate_identifier_size(
+    identifiers: list[str],
+    stop_on_first_error: bool = True,
+) -> bool:
+    """
+    Validate that PostgreSQL identifiers (e.g. channel, function, trigger names) do not exceed the byte limit.
+
+    Args:
+        identifiers (list[str]): The identifiers to validate
+        stop_on_first_error (bool): If True, raise on the first offending identifier. If False, collect
+            all offending identifiers and raise a combined error message listing them.
+
+    Returns:
+        bool: True if all identifiers are within limits
+
+    Raises:
+        SQLNotifyIdentifierSizeError: If one or more identifiers exceed the PostgreSQL byte limit
+    """
+
+    errors: list[str] = []
+
+    for identifier in identifiers:
+        identifier_bytes = len(identifier.encode("utf-8"))
+
+        if identifier_bytes > MAX_SQLNOTIFY_IDENTIFER_BYTES:
+            msg = (
+                f"Identifier '{identifier}' is {identifier_bytes} bytes, "
+                f"and exceeds limit of {MAX_SQLNOTIFY_IDENTIFER_BYTES} bytes."
+            )
+
+            if stop_on_first_error:
+                raise SQLNotifyIdentifierSizeError(msg)
+
+            errors.append(msg)
+
+    if errors:
+        combined = "; ".join(errors)
+        raise SQLNotifyIdentifierSizeError(combined)
+
+    return True

sqlnotify/watcher.py

@@ -0,0 +1,72 @@
+import logging
+from typing import Any
+
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import Mapper
+
+from .constants import PACKAGE_NAME
+from .exceptions import SQLNotifyConfigurationError
+from .types import Operation
+from .utils import hash_identifier, replace_spaces_with_underscores, validate_identifier_size
+
+
+class Watcher:
+    """
+    Configuration class for SQLNotify Watcher
+    """
+
+    def __init__(
+        self,
+        model: type,
+        operation: Operation,
+        extra_columns: list[str] | None,
+        trigger_columns: list[str] | None,
+        primary_keys: list[str],
+        channel_label: str | None = None,
+        use_overflow_table: bool = False,
+        logger: logging.Logger | None = None,
+    ):
+        self.model = model
+        self.operation = operation
+        self.extra_columns = extra_columns or []
+        self.trigger_columns = trigger_columns
+        self.primary_keys = primary_keys
+        self.channel_label = channel_label
+        self.use_overflow_table = use_overflow_table
+        self._logger = logger
+
+        try:
+            sa_mapper: Mapper[Any] = sa_inspect(model)
+            self.table_name = (
+                sa_mapper.local_table.name  # type: ignore[attr-defined]
+                or model.__table__.name  # type: ignore[attr-defined]
+                or model.__tablename__  # type: ignore[attr-defined]
+                or model.__name__.lower()
+            )
+            self.schema_name = sa_mapper.local_table.schema or getattr(model, "__table_args__", {}).get(
+                "schema", "public"
+            )
+        except Exception as e:
+            if self._logger:
+                self._logger.error(
+                    f"Error inspecting model '{model.__name__}': {str(e)}",
+                    exc_info=True,
+                )
+
+            raise SQLNotifyConfigurationError(
+                f"Failed to inspect model '{model.__name__}'. Ensure it's a valid SQLAlchemy or SQLModel model"
+            ) from e
+
+        self.channel_name = f"{PACKAGE_NAME}_{self.schema_name}_{self.table_name}_{self.operation.value}"
+        if self.channel_label:
+            self.channel_name = f"{PACKAGE_NAME}_{replace_spaces_with_underscores(self.channel_label)}"
+
+        hashed_channel_name = hash_identifier(self.channel_name)
+
+        self.function_name = f"notify_{hashed_channel_name}"
+        self.trigger_name = f"trigger_{hashed_channel_name}"
+
+        validate_identifier_size([self.channel_name, self.function_name, self.trigger_name])
+
+        if self.use_overflow_table:
+            self.overflow_table_name = f"{PACKAGE_NAME}_overflow"