prismiq 0.1.0__py3-none-any.whl

prismiq/persistence/saved_query_store.py

@@ -0,0 +1,336 @@
+"""PostgreSQL-backed saved query storage with tenant isolation."""
+
+from __future__ import annotations
+
+import builtins
+import json
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import (
+    Boolean,
+    Column,
+    MetaData,
+    String,
+    Table,
+    delete,
+    insert,
+    select,
+    update,
+)
+from sqlalchemy.dialects.postgresql import JSONB, TIMESTAMP, UUID
+
+from prismiq.types import QueryDefinition, SavedQuery, SavedQueryCreate, SavedQueryUpdate
+
+if TYPE_CHECKING:
+    from asyncpg import Pool  # type: ignore[import-not-found]
+
+_logger = logging.getLogger(__name__)
+
+# SQLAlchemy Table definition for saved queries (used for query generation)
+# quote=True ensures all identifiers are double-quoted in generated SQL
+_metadata = MetaData()
+_saved_queries_table = Table(
+    "prismiq_saved_queries",
+    _metadata,
+    Column("id", UUID, primary_key=True, quote=True),
+    Column("tenant_id", String(255), nullable=False, quote=True),
+    Column("name", String(255), nullable=False, quote=True),
+    Column("description", String, nullable=True, quote=True),
+    Column("query", JSONB, nullable=False, quote=True),
+    Column("owner_id", String(255), nullable=True, quote=True),
+    Column("is_shared", Boolean, nullable=False, quote=True),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False, quote=True),
+    Column("updated_at", TIMESTAMP(timezone=True), nullable=False, quote=True),
+    quote=True,
+)
+
+
+class SavedQueryStore:
+    """PostgreSQL-backed saved query storage with tenant isolation.
+
+    All operations are scoped to a tenant_id for multi-tenant security.
+    Supports per-tenant PostgreSQL schema isolation via schema_name
+    parameter.
+    """
+
+    def __init__(self, pool: Pool) -> None:
+        """Initialize SavedQueryStore.
+
+        Args:
+            pool: asyncpg connection pool
+        """
+        self._pool = pool
+
+    async def _set_search_path(self, conn: Any, schema_name: str | None) -> None:
+        """Set PostgreSQL search_path for schema isolation.
+
+        Uses session-scoped set_config so the search_path persists across
+        statements on the same connection.
+
+        Args:
+            conn: asyncpg connection
+            schema_name: Schema name to use, or None for default (public)
+        """
+        if schema_name:
+            # Build search_path value with safely quoted schema identifier
+            # Double any embedded double-quotes to escape them in the identifier
+            escaped_schema = schema_name.replace('"', '""')
+            search_path_value = f'"{escaped_schema}", "public"'
+            _logger.debug("[saved_query_store] Setting search_path to: %s", search_path_value)
+            await conn.fetchval("SELECT set_config('search_path', $1, false)", search_path_value)
+        else:
+            _logger.debug('[saved_query_store] Setting search_path to: "public"')
+            await conn.fetchval("SELECT set_config('search_path', $1, false)", '"public"')
+
+    async def list(
+        self,
+        tenant_id: str,
+        user_id: str | None = None,
+        schema_name: str | None = None,
+    ) -> builtins.list[SavedQuery]:
+        """List saved queries for a tenant.
+
+        Returns queries owned by the user or shared with all users. If
+        user_id is None, returns all queries for the tenant.
+
+        Args:
+            tenant_id: Tenant ID for isolation.
+            user_id: Optional user ID to filter by access.
+            schema_name: PostgreSQL schema name for per-tenant schema isolation.
+        """
+        t = _saved_queries_table
+        stmt = select(t).where(t.c.tenant_id == tenant_id)
+
+        if user_id:
+            # Return user's queries and shared queries
+            from sqlalchemy import or_
+
+            stmt = stmt.where(
+                or_(
+                    t.c.owner_id == user_id,
+                    t.c.is_shared.is_(True),
+                    t.c.owner_id.is_(None),
+                )
+            )
+
+        stmt = stmt.order_by(t.c.name.asc())
+
+        sql, params = self._compile_query(stmt)
+        async with self._pool.acquire() as conn:
+            await self._set_search_path(conn, schema_name)
+            rows = await conn.fetch(sql, *params)
+            return [self._row_to_saved_query(row) for row in rows]
+
+    async def get(
+        self,
+        query_id: str,
+        tenant_id: str,
+        schema_name: str | None = None,
+    ) -> SavedQuery | None:
+        """Get a saved query by ID with tenant check.
+
+        Args:
+            query_id: The saved query ID.
+            tenant_id: Tenant ID for isolation.
+            schema_name: PostgreSQL schema name for per-tenant schema isolation.
+        """
+        t = _saved_queries_table
+        stmt = select(t).where(
+            t.c.id == uuid.UUID(query_id),
+            t.c.tenant_id == tenant_id,
+        )
+
+        sql, params = self._compile_query(stmt)
+        async with self._pool.acquire() as conn:
+            await self._set_search_path(conn, schema_name)
+            row = await conn.fetchrow(sql, *params)
+            if not row:
+                return None
+            return self._row_to_saved_query(row)
+
+    async def create(
+        self,
+        data: SavedQueryCreate,
+        tenant_id: str,
+        owner_id: str | None = None,
+        schema_name: str | None = None,
+    ) -> SavedQuery:
+        """Create a new saved query.
+
+        Args:
+            data: Saved query creation data.
+            tenant_id: Tenant ID for isolation.
+            owner_id: Optional owner ID.
+            schema_name: PostgreSQL schema name for per-tenant schema isolation.
+        """
+        query_id = uuid.uuid4()
+        now = datetime.now(timezone.utc)
+
+        t = _saved_queries_table
+        stmt = (
+            insert(t)
+            .values(
+                id=query_id,
+                tenant_id=tenant_id,
+                name=data.name,
+                description=data.description,
+                query=json.dumps(data.query.model_dump()),
+                owner_id=owner_id,
+                is_shared=data.is_shared,
+                created_at=now,
+                updated_at=now,
+            )
+            .returning(*t.c)
+        )
+
+        sql, params = self._compile_query(stmt)
+        async with self._pool.acquire() as conn:
+            await self._set_search_path(conn, schema_name)
+            row = await conn.fetchrow(sql, *params)
+            return self._row_to_saved_query(row)
+
+    async def update(
+        self,
+        query_id: str,
+        data: SavedQueryUpdate,
+        tenant_id: str,
+        user_id: str | None = None,
+        schema_name: str | None = None,
+    ) -> SavedQuery | None:
+        """Update a saved query.
+
+        Only the owner can update a query.
+
+        Args:
+            query_id: The saved query ID to update.
+            data: Update data.
+            tenant_id: Tenant ID for isolation.
+            user_id: User ID for ownership check.
+            schema_name: PostgreSQL schema name for per-tenant schema isolation.
+        """
+        # Collect fields to update
+        values: dict[str, Any] = {}
+
+        if data.name is not None:
+            values["name"] = data.name
+
+        if data.description is not None:
+            values["description"] = data.description
+
+        if data.query is not None:
+            values["query"] = json.dumps(data.query.model_dump())
+
+        if data.is_shared is not None:
+            values["is_shared"] = data.is_shared
+
+        if not values:
+            # No updates provided, just return current query
+            return await self.get(query_id, tenant_id, schema_name)
+
+        # Always update the timestamp
+        values["updated_at"] = datetime.now(timezone.utc)
+
+        t = _saved_queries_table
+        stmt = (
+            update(t)
+            .where(
+                t.c.id == uuid.UUID(query_id),
+                t.c.tenant_id == tenant_id,
+            )
+            .values(**values)
+            .returning(*t.c)
+        )
+
+        # Only owner can update
+        if user_id:
+            stmt = stmt.where(t.c.owner_id == user_id)
+
+        sql, params = self._compile_query(stmt)
+        async with self._pool.acquire() as conn:
+            await self._set_search_path(conn, schema_name)
+            row = await conn.fetchrow(sql, *params)
+            if not row:
+                return None
+            return self._row_to_saved_query(row)
+
+    async def delete(
+        self,
+        query_id: str,
+        tenant_id: str,
+        user_id: str | None = None,
+        schema_name: str | None = None,
+    ) -> bool:
+        """Delete a saved query.
+
+        Only the owner can delete a query.
+
+        Args:
+            query_id: The saved query ID to delete.
+            tenant_id: Tenant ID for isolation.
+            user_id: User ID for ownership check.
+            schema_name: PostgreSQL schema name for per-tenant schema isolation.
+        """
+        t = _saved_queries_table
+        stmt = delete(t).where(
+            t.c.id == uuid.UUID(query_id),
+            t.c.tenant_id == tenant_id,
+        )
+
+        if user_id:
+            stmt = stmt.where(t.c.owner_id == user_id)
+
+        sql, params = self._compile_query(stmt)
+        async with self._pool.acquire() as conn:
+            await self._set_search_path(conn, schema_name)
+            result = await conn.execute(sql, *params)
+            return result == "DELETE 1"
+
+    def _row_to_saved_query(self, row: Any) -> SavedQuery:
+        """Convert a database row to a SavedQuery model."""
+        query_data = row["query"]
+        if isinstance(query_data, str):
+            query_data = json.loads(query_data)
+
+        return SavedQuery(
+            id=str(row["id"]),
+            name=row["name"],
+            description=row.get("description"),
+            query=QueryDefinition(**query_data),
+            tenant_id=row["tenant_id"],
+            owner_id=row.get("owner_id"),
+            is_shared=row.get("is_shared", False),
+            created_at=row["created_at"].isoformat() if row.get("created_at") else None,
+            updated_at=row["updated_at"].isoformat() if row.get("updated_at") else None,
+        )
+
+    @staticmethod
+    def _compile_query(stmt: Any) -> tuple[str, builtins.list[Any]]:
+        """Compile a SQLAlchemy statement for asyncpg execution.
+
+        Converts SQLAlchemy Core statements to SQL strings with positional
+        parameters ($1, $2, etc.) compatible with asyncpg.
+
+        Args:
+            stmt: SQLAlchemy Core statement (select, insert, etc.)
+
+        Returns:
+            Tuple of (sql_string, list_of_parameters)
+        """
+        from sqlalchemy.dialects import postgresql
+
+        dialect = postgresql.dialect(paramstyle="numeric")
+        compiled = stmt.compile(dialect=dialect, compile_kwargs={"literal_binds": False})
+        sql = str(compiled)
+
+        # Extract parameters in the order they appear in the SQL
+        # The compiled.positiontup gives param names in order for positional dialects
+        if hasattr(compiled, "positiontup") and compiled.positiontup:
+            params = [compiled.params[name] for name in compiled.positiontup]
+        else:
+            # Fallback: params dict should be ordered in Python 3.7+
+            params = list(compiled.params.values())
+
+        return sql, params

prismiq/persistence/schema.sql

@@ -0,0 +1,95 @@
+-- Prismiq metadata tables
+-- Created in customer's database alongside their data tables
+
+-- Dashboards
+CREATE TABLE IF NOT EXISTS prismiq_dashboards (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id VARCHAR(255) NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    layout JSONB NOT NULL DEFAULT '{"columns": 12, "rowHeight": 50, "margin": [10, 10]}',
+    filters JSONB NOT NULL DEFAULT '[]',
+    owner_id VARCHAR(255),
+    is_public BOOLEAN NOT NULL DEFAULT FALSE,
+    allowed_viewers TEXT[] NOT NULL DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT unique_dashboard_name_per_tenant UNIQUE (tenant_id, name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_dashboards_tenant_id ON prismiq_dashboards(tenant_id);
+CREATE INDEX IF NOT EXISTS idx_dashboards_owner_id ON prismiq_dashboards(tenant_id, owner_id);
+
+-- Widgets
+CREATE TABLE IF NOT EXISTS prismiq_widgets (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    dashboard_id UUID NOT NULL REFERENCES prismiq_dashboards(id) ON DELETE CASCADE,
+    type VARCHAR(50) NOT NULL,
+    title VARCHAR(255) NOT NULL,
+    query JSONB,  -- Null for text widgets
+    position JSONB NOT NULL,  -- {x, y, w, h}
+    config JSONB NOT NULL DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_widgets_dashboard_id ON prismiq_widgets(dashboard_id);
+
+-- Saved queries for reuse
+CREATE TABLE IF NOT EXISTS prismiq_saved_queries (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id VARCHAR(255) NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    query JSONB NOT NULL,
+    owner_id VARCHAR(255),
+    is_shared BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT unique_query_name_per_tenant UNIQUE (tenant_id, name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_saved_queries_tenant ON prismiq_saved_queries(tenant_id);
+
+-- Pinned dashboards for context-based quick access
+CREATE TABLE IF NOT EXISTS prismiq_pinned_dashboards (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id VARCHAR(255) NOT NULL,
+    user_id VARCHAR(255) NOT NULL,
+    dashboard_id UUID NOT NULL REFERENCES prismiq_dashboards(id) ON DELETE CASCADE,
+    context VARCHAR(100) NOT NULL,
+    position INTEGER NOT NULL DEFAULT 0,
+    pinned_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT unique_pin_per_context UNIQUE (tenant_id, user_id, dashboard_id, context)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pinned_tenant_user_context ON prismiq_pinned_dashboards(tenant_id, user_id, context);
+CREATE INDEX IF NOT EXISTS idx_pinned_dashboard ON prismiq_pinned_dashboards(dashboard_id);
+
+-- Function to update updated_at timestamp
+CREATE OR REPLACE FUNCTION prismiq_update_timestamp()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Triggers for auto-updating timestamps
+DROP TRIGGER IF EXISTS prismiq_dashboards_updated ON prismiq_dashboards;
+CREATE TRIGGER prismiq_dashboards_updated
+    BEFORE UPDATE ON prismiq_dashboards
+    FOR EACH ROW EXECUTE FUNCTION prismiq_update_timestamp();
+
+DROP TRIGGER IF EXISTS prismiq_widgets_updated ON prismiq_widgets;
+CREATE TRIGGER prismiq_widgets_updated
+    BEFORE UPDATE ON prismiq_widgets
+    FOR EACH ROW EXECUTE FUNCTION prismiq_update_timestamp();
+
+DROP TRIGGER IF EXISTS prismiq_saved_queries_updated ON prismiq_saved_queries;
+CREATE TRIGGER prismiq_saved_queries_updated
+    BEFORE UPDATE ON prismiq_saved_queries
+    FOR EACH ROW EXECUTE FUNCTION prismiq_update_timestamp();

prismiq/persistence/setup.py

@@ -0,0 +1,222 @@
+"""Database setup utilities for Prismiq tables."""
+
+from __future__ import annotations
+
+import logging
+import re
+from functools import cache
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from asyncpg import Pool  # type: ignore[import-not-found]
+    from sqlalchemy import Connection
+
+logger = logging.getLogger(__name__)
+
+# Valid schema name pattern: starts with letter/underscore, alphanumeric thereafter
+_SCHEMA_NAME_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+# Reserved PostgreSQL schemas that should not be used for tenant data
+_RESERVED_SCHEMAS = frozenset({"public", "information_schema", "pg_catalog", "pg_toast"})
+
+
+class TableCreationError(Exception):
+    """Raised when Prismiq tables cannot be created."""
+
+    pass
+
+
+def _validate_schema_name(schema_name: str) -> None:
+    """Validate schema name for safety and correctness.
+
+    Args:
+        schema_name: PostgreSQL schema name to validate
+
+    Raises:
+        ValueError: If schema name is invalid or reserved
+    """
+    if not schema_name:
+        raise ValueError("schema_name cannot be empty. Use None for default schema.")
+
+    if not _SCHEMA_NAME_PATTERN.match(schema_name):
+        raise ValueError(
+            f"Invalid schema name '{schema_name}'. Schema names must start with "
+            f"a letter or underscore and contain only alphanumeric characters."
+        )
+
+    if schema_name.lower() in _RESERVED_SCHEMAS:
+        raise ValueError(
+            f"Cannot use reserved schema '{schema_name}'. "
+            f"Use a tenant-specific schema name instead."
+        )
+
+
+@cache
+def _get_schema_sql() -> str:
+    """Load SQL from adjacent schema.sql file (lazy, cached).
+
+    Raises:
+        RuntimeError: If schema.sql file is missing (corrupted installation)
+    """
+    schema_path = Path(__file__).parent / "schema.sql"
+    try:
+        return schema_path.read_text()
+    except FileNotFoundError:
+        raise RuntimeError(
+            f"Prismiq schema.sql not found at {schema_path}. "
+            f"This indicates a corrupted package installation. "
+            f"Try reinstalling: pip install --force-reinstall prismiq"
+        ) from None
+
+
+async def ensure_tables(pool: Pool) -> None:
+    """Create Prismiq metadata tables if they don't exist.
+
+    This is idempotent - safe to call multiple times.
+    Uses CREATE TABLE IF NOT EXISTS for all tables.
+
+    Note: This creates tables in the current search_path schema.
+    For multi-tenant schema isolation, use ensure_tables_sync() with
+    SQLAlchemy, or set search_path before calling this function.
+
+    Args:
+        pool: asyncpg connection pool
+
+    Raises:
+        TableCreationError: If table creation fails
+    """
+    try:
+        async with pool.acquire() as conn:
+            await conn.execute(_get_schema_sql())
+        logger.info("Prismiq tables created/verified successfully")
+    except Exception as e:
+        error_msg = str(e)
+        logger.error(f"Failed to create Prismiq tables: {error_msg}")
+        raise TableCreationError(
+            f"Failed to create Prismiq tables. "
+            f"Check database permissions and connectivity. Original error: {error_msg}"
+        ) from e
+
+
+async def drop_tables(pool: Pool) -> None:
+    """Drop all Prismiq metadata tables.
+
+    WARNING: This will delete all dashboard and widget data.
+    Use with caution - primarily for testing.
+
+    Args:
+        pool: asyncpg connection pool
+    """
+    async with pool.acquire() as conn:
+        await conn.execute(
+            """
+            DROP TABLE IF EXISTS prismiq_pinned_dashboards CASCADE;
+            DROP TABLE IF EXISTS prismiq_widgets CASCADE;
+            DROP TABLE IF EXISTS prismiq_dashboards CASCADE;
+            DROP TABLE IF EXISTS prismiq_saved_queries CASCADE;
+            DROP FUNCTION IF EXISTS prismiq_update_timestamp CASCADE;
+        """
+        )
+
+
+async def table_exists(pool: Pool, table_name: str) -> bool:
+    """Check if a Prismiq table exists.
+
+    Args:
+        pool: asyncpg connection pool
+        table_name: Name of the table to check
+
+    Returns:
+        True if table exists, False otherwise
+    """
+    async with pool.acquire() as conn:
+        result = await conn.fetchval(
+            """
+            SELECT EXISTS (
+                SELECT FROM information_schema.tables
+                WHERE table_name = $1
+            )
+            """,
+            table_name,
+        )
+        return bool(result)
+
+
+# NOTE: Synchronous I/O exception for Alembic/migration use.
+# Alembic migrations are inherently synchronous, so this helper intentionally
+# uses sync I/O. This is the accepted exception to the async-only guideline.
+# For async application code, use ensure_tables() instead.
+def ensure_tables_sync(connection: Connection, schema_name: str | None = None) -> None:
+    """Create Prismiq tables in specified schema (synchronous).
+
+    For use with SQLAlchemy sync engines in multi-tenant systems. This function
+    creates all Prismiq tables using the declarative models from models.py.
+
+    This is the recommended approach for:
+    - Alembic migrations with schema-based multi-tenancy
+    - Programmatic table creation during tenant provisioning
+    - Integration with existing SQLAlchemy-based applications
+
+    Args:
+        connection: SQLAlchemy sync connection
+        schema_name: PostgreSQL schema name (e.g., "tenant_123"). If provided,
+            tables are created in this schema using schema_translate_map.
+            If None, tables are created in the default schema.
+
+    Raises:
+        ValueError: If schema_name is invalid or uses a reserved schema
+        TableCreationError: If table creation fails
+
+    Example:
+        from sqlalchemy import create_engine
+        from prismiq import ensure_tables_sync
+
+        engine = create_engine("postgresql://user:pass@localhost/db")
+
+        # Create in default schema
+        with engine.connect() as conn:
+            ensure_tables_sync(conn)
+            conn.commit()
+
+        # Create in tenant-specific schema
+        with engine.connect() as conn:
+            ensure_tables_sync(conn, schema_name="tenant_123")
+            conn.commit()
+    """
+    from prismiq.persistence.models import PrismiqBase
+
+    target_schema = schema_name or "default schema"
+
+    # Validate schema name if provided
+    if schema_name is not None:
+        _validate_schema_name(schema_name)
+
+    try:
+        if schema_name:
+            # Use schema_translate_map for multi-tenant support
+            connection = connection.execution_options(schema_translate_map={None: schema_name})
+
+        logger.info(f"Creating Prismiq tables in {target_schema}")
+        PrismiqBase.metadata.create_all(connection)
+        logger.info(f"Prismiq tables created/verified in {target_schema}")
+
+    except ValueError:
+        # Re-raise validation errors as-is
+        raise
+    except Exception as e:
+        error_msg = str(e)
+        logger.error(f"Failed to create Prismiq tables in {target_schema}: {error_msg}")
+
+        # Provide actionable error messages for common issues
+        if "schema" in error_msg.lower() and "does not exist" in error_msg.lower():
+            raise TableCreationError(
+                f"Schema '{schema_name}' does not exist. "
+                f"Create the schema before calling ensure_tables_sync()."
+            ) from e
+
+        raise TableCreationError(
+            f"Failed to create Prismiq tables in {target_schema}. "
+            f"Check database permissions and schema existence. "
+            f"Original error: {error_msg}"
+        ) from e