@weirdfingers/baseboards 0.2.0

package/templates/api/src/boards/database/connection.py

@@ -0,0 +1,252 @@
+"""
+Database connection management
+"""
+
+import os
+import threading
+from collections.abc import AsyncGenerator, Generator
+from contextlib import asynccontextmanager, contextmanager
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from ..config import settings
+from ..logging import get_logger
+
+logger = get_logger(__name__)
+
+# Global shared connection pools (proper FastAPI pattern)
+_engine = None
+_async_engine = None
+_session_local = None
+_async_session_local = None
+_initialized = False
+_init_lock = threading.Lock()  # Protect initialization from race conditions
+
+
+def get_database_url() -> str:
+    """Get database URL, checking environment variables first for test compatibility."""
+    # Always check environment first (for tests), then fall back to settings
+    db_url = os.getenv("BOARDS_DATABASE_URL")
+    if not db_url:
+        # For tests that set env vars after settings are loaded
+        if "BOARDS_DATABASE_URL" in os.environ:
+            db_url = os.environ["BOARDS_DATABASE_URL"]
+        else:
+            db_url = settings.database_url
+    return db_url
+
+
+def reset_database():
+    """Reset database connections (for tests)."""
+    global _engine, _async_engine, _session_local, _async_session_local, _initialized
+    _engine = None
+    _async_engine = None
+    _session_local = None
+    _async_session_local = None
+    _initialized = False
+
+
+async def test_database_connection() -> tuple[bool, str | None]:
+    """
+    Test the database connection and return helpful error messages.
+
+    Returns:
+        tuple: (success: bool, error_message: str | None)
+    """
+    if _async_engine is None:
+        return False, "Database engine not initialized"
+
+    try:
+        async with _async_engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+            return True, None
+    except Exception as e:
+        error_str = str(e)
+        error_type = type(e).__name__
+
+        # Provide helpful error messages based on the error type
+        if "does not exist" in error_str and "role" in error_str:
+            # This is the confusing error - could be database server not running
+            db_url = get_database_url()
+            # Extract database name from URL
+            db_name = db_url.split("/")[-1].split("?")[0]
+            return False, (
+                f"Cannot connect to database: {error_str}\n"
+                f"This usually means:\n"
+                f"  1. The database server is not running\n"
+                f"  2. The database '{db_name}' doesn't exist\n"
+                f"  3. The database user/role doesn't exist\n"
+                f"Please check your database connection and run migrations if needed."
+            )
+        elif "Connection refused" in error_str or "could not connect" in error_str:
+            return False, (
+                f"Cannot connect to database server: {error_str}\n"
+                f"The database server appears to be down or unreachable.\n"
+                f"Please check that PostgreSQL is running and accessible."
+            )
+        elif "password authentication failed" in error_str:
+            return False, (
+                f"Database authentication failed: {error_str}\n"
+                f"Please check your database credentials."
+            )
+        else:
+            return False, f"Database connection error ({error_type}): {error_str}"
+
+
+def init_database(database_url: str | None = None, force_reinit: bool = False):
+    """Initialize shared database connection pools.
+
+    Thread-safe initialization using a lock to prevent race conditions
+    when multiple threads attempt to initialize simultaneously.
+    """
+    global _engine, _async_engine, _session_local, _async_session_local, _initialized
+
+    # Fast path: already initialized, no lock needed
+    if _initialized and not force_reinit and database_url is None:
+        return
+
+    # Slow path: acquire lock for initialization
+    with _init_lock:
+        # Double-check after acquiring lock (another thread may have initialized)
+        if _initialized and not force_reinit and database_url is None:
+            return
+
+        # Get the database URL
+        db_url = database_url or get_database_url()
+
+        # Create sync engine
+        _engine = create_engine(
+            db_url,
+            pool_size=settings.database_pool_size,
+            max_overflow=settings.database_max_overflow,
+            echo=settings.sql_echo,
+        )
+        _session_local = sessionmaker(autocommit=False, autoflush=False, bind=_engine)
+
+        # Create async engine (if PostgreSQL)
+        if db_url.startswith("postgresql://"):
+            async_db_url = db_url.replace("postgresql://", "postgresql+asyncpg://")
+            _async_engine = create_async_engine(
+                async_db_url,
+                pool_size=settings.database_pool_size,
+                max_overflow=settings.database_max_overflow,
+                echo=settings.sql_echo,
+            )
+            _async_session_local = async_sessionmaker(
+                _async_engine,
+                class_=AsyncSession,
+                autocommit=False,
+                autoflush=False,
+            )
+
+        _initialized = True
+        logger.info("Database initialized", database_url=db_url)
+
+
+def get_engine():
+    """Get the shared SQLAlchemy engine."""
+    if _engine is None:
+        init_database()
+    return _engine
+
+
+def get_async_engine():
+    """Get the shared async SQLAlchemy engine."""
+    if _async_engine is None:
+        init_database()
+    return _async_engine
+
+
+@contextmanager
+def get_session() -> Generator[Session, None, None]:
+    """Get a database session (sync) from shared pool."""
+    if _session_local is None:
+        init_database()
+
+    if _session_local is None:
+        raise RuntimeError("Database not initialized")
+
+    session = _session_local()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+
+@asynccontextmanager
+async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
+    """Get a database session (async) from shared pool."""
+    if _async_session_local is None:
+        init_database()
+
+    if _async_session_local is None:
+        raise RuntimeError("Async database not available (PostgreSQL required)")
+
+    async with _async_session_local() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+
+
+# Dependency for FastAPI
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    """FastAPI dependency for database sessions."""
+    async with get_async_session() as session:
+        yield session
+
+
+# Test-specific database session context
+@asynccontextmanager
+async def get_test_db_session(database_url: str) -> AsyncGenerator[AsyncSession, None]:
+    """Get a database session for testing with explicit database URL."""
+    from sqlalchemy.ext.asyncio import (
+        AsyncSession,
+        async_sessionmaker,
+        create_async_engine,
+    )
+
+    from ..config import settings
+
+    # Convert to async URL for PostgreSQL
+    if database_url.startswith("postgresql://"):
+        async_url = database_url.replace("postgresql://", "postgresql+asyncpg://")
+    else:
+        async_url = database_url
+
+    # Create isolated engine for this session
+    engine = create_async_engine(
+        async_url,
+        pool_size=settings.database_pool_size,
+        max_overflow=settings.database_max_overflow,
+        echo=settings.debug,
+        isolation_level="AUTOCOMMIT",  # Ensure we can see committed schema changes
+    )
+
+    session_local = async_sessionmaker(
+        engine,
+        class_=AsyncSession,
+        autocommit=False,
+        autoflush=False,
+    )
+
+    async with session_local() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+            await engine.dispose()

package/templates/api/src/boards/database/models.py

@@ -0,0 +1,19 @@
+# type: ignore[reportMissingImports]
+
+"""
+Compatibility shim: re-export models from boards.dbmodels
+This file remains to avoid breaking existing imports like `from boards.database.models import ...`.
+"""
+
+from boards.dbmodels import (  # noqa: F401
+    Base,
+    BoardMembers,
+    Boards,
+    CreditTransactions,
+    Generations,
+    LoraModels,
+    ProviderConfigs,
+    Tenants,
+    Users,
+    target_metadata,
+)

package/templates/api/src/boards/database/seed_data.py

@@ -0,0 +1,182 @@
+"""
+Reusable seed data functions for database initialization.
+
+This module provides functions to seed initial data into the database,
+including tenants, users, and other setup-time functionality.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..config import settings
+from ..dbmodels import Tenants
+from ..logging import get_logger
+
+logger = get_logger(__name__)
+
+
+async def ensure_tenant(
+    db: AsyncSession,
+    *,
+    tenant_id: UUID | None = None,
+    name: str | None = None,
+    slug: str | None = None,
+    settings_dict: dict[str, Any] | None = None,
+) -> UUID:
+    """
+    Ensure a tenant exists in the database.
+
+    This function creates a tenant if it doesn't exist, or returns the
+    existing tenant's ID if it does.
+
+    Args:
+        db: Database session
+        tenant_id: UUID for the tenant (if None, auto-generated)
+        name: Tenant name (defaults to env var or "Default Tenant")
+        slug: Tenant slug (defaults to env var or "default")
+        settings_dict: Optional tenant settings/metadata
+
+    Returns:
+        UUID of the tenant (existing or newly created)
+    """
+    # Use environment variables with fallbacks
+    if name is None:
+        name = os.getenv("BOARDS_TENANT_NAME", "Default Tenant")
+
+    if slug is None:
+        slug = os.getenv("BOARDS_TENANT_SLUG", settings.default_tenant_slug)
+
+    if settings_dict is None:
+        settings_dict = {}
+
+    # Check if tenant already exists by slug
+    stmt = select(Tenants).where(Tenants.slug == slug)
+    result = await db.execute(stmt)
+    existing_tenant = result.scalar_one_or_none()
+
+    if existing_tenant:
+        logger.debug(
+            "Tenant already exists",
+            tenant_id=str(existing_tenant.id),
+            slug=slug,
+            name=existing_tenant.name,
+        )
+        return existing_tenant.id
+
+    # Create new tenant
+    new_tenant = Tenants(
+        name=name,
+        slug=slug,
+        settings=settings_dict,
+    )
+
+    # Set specific ID if provided
+    if tenant_id:
+        new_tenant.id = tenant_id
+
+    db.add(new_tenant)
+    await db.commit()
+    await db.refresh(new_tenant)
+
+    logger.info(
+        "Created new tenant",
+        tenant_id=str(new_tenant.id),
+        slug=slug,
+        name=name,
+    )
+
+    return new_tenant.id
+
+
+async def ensure_default_tenant(db: AsyncSession) -> UUID:
+    """
+    Ensure the default tenant exists for single-tenant or no-auth mode.
+
+    This is a convenience function that uses environment variables
+    or defaults to create/get the default tenant.
+
+    Args:
+        db: Database session
+
+    Returns:
+        UUID of the default tenant
+    """
+    return await ensure_tenant(db)
+
+
+async def seed_initial_data(db: AsyncSession) -> None:
+    """
+    Seed all initial data required for the application.
+
+    This function can be extended to seed additional data like:
+    - Default provider configurations
+    - Initial admin users
+    - Sample boards or generations
+    - Default credit allocations
+
+    Args:
+        db: Database session
+    """
+    logger.info("Starting database seeding")
+
+    # Always ensure default tenant exists in non-multi-tenant mode
+    if not settings.multi_tenant_mode:
+        tenant_id = await ensure_default_tenant(db)
+        logger.info("Ensured default tenant exists", tenant_id=str(tenant_id))
+
+    # Add more seed operations here as needed
+    # For example:
+    # await ensure_default_providers(db, tenant_id)
+    # await ensure_admin_user(db, tenant_id)
+
+    logger.info("Database seeding completed")
+
+
+async def seed_tenant_with_data(
+    db: AsyncSession,
+    *,
+    tenant_name: str,
+    tenant_slug: str,
+    tenant_settings: dict[str, Any] | None = None,
+    include_sample_data: bool = False,
+) -> UUID:
+    """
+    Create a new tenant with optional sample data.
+
+    This function is useful for:
+    - Multi-tenant setup
+    - Creating demo tenants
+    - Testing different tenant configurations
+
+    Args:
+        db: Database session
+        tenant_name: Display name for the tenant
+        tenant_slug: Unique slug for the tenant
+        tenant_settings: Optional tenant-specific settings
+        include_sample_data: Whether to create sample boards/generations
+
+    Returns:
+        UUID of the created tenant
+    """
+    tenant_id = await ensure_tenant(
+        db,
+        name=tenant_name,
+        slug=tenant_slug,
+        settings_dict=tenant_settings,
+    )
+
+    if include_sample_data:
+        # Future: Add sample boards, users, generations
+        logger.info(
+            "Would create sample data for tenant",
+            tenant_id=str(tenant_id),
+            note="Sample data creation not yet implemented",
+        )
+
+    return tenant_id