pgsqlasync2fast-fastapi 0.1.0__py3-none-any.whl

pgsqlasync2fast_fastapi/__init__.py

@@ -0,0 +1,49 @@
+"""
+pgsqlasync2fast-fastapi - Simple and fast PostgreSQL async module for FastAPI
+
+A comprehensive PostgreSQL async module for FastAPI with multi-database support,
+automatic database creation, and Pydantic settings configuration.
+
+Features:
+- Multiple database connection support
+- Async database operations with SQLAlchemy
+- Database creation utilities with superuser support
+- Connection pooling and health checks
+- FastAPI integration with dependencies
+- Lazy engine creation for optimal resource usage
+"""
+
+from .__version__ import __version__
+from .connection import DatabaseManager, get_manager
+from .database import create_database, database_exists, drop_database, list_databases
+from .dependencies import (
+    get_db_engine,
+    get_db_manager,
+    get_db_session,
+    shutdown_database,
+    startup_database,
+)
+from .settings import DatabaseConnectionSettings, DatabaseSettings, settings
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main classes
+    "DatabaseManager",
+    "get_manager",
+    # Settings
+    "DatabaseSettings",
+    "DatabaseConnectionSettings",
+    "settings",
+    # FastAPI dependencies
+    "get_db_manager",
+    "get_db_engine",
+    "get_db_session",
+    "startup_database",
+    "shutdown_database",
+    # Database utilities
+    "database_exists",
+    "create_database",
+    "drop_database",
+    "list_databases",
+]

pgsqlasync2fast_fastapi/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pgsqlasync2fast_fastapi/connection.py

@@ -0,0 +1,196 @@
+"""
+Database connection and engine management
+"""
+
+from typing import AsyncGenerator, Dict, Optional
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, create_async_engine
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlalchemy import text
+
+from .settings import DatabaseSettings, settings
+
+
+class DatabaseManager:
+    """
+    Manages multiple async database engines and sessions.
+    
+    This class provides:
+    - Lazy engine creation (engines created only when first accessed)
+    - Multiple named connections support
+    - Session factory for each connection
+    - Connection health checks
+    - Cleanup utilities
+    """
+
+    def __init__(self, config: DatabaseSettings):
+        """
+        Initialize the database manager.
+        
+        Args:
+            config: Database settings configuration
+        """
+        self.config = config
+        self._engines: Dict[str, AsyncEngine] = {}
+        self._session_makers: Dict[str, async_sessionmaker[AsyncSession]] = {}
+
+    def get_engine(self, connection_name: Optional[str] = None) -> AsyncEngine:
+        """
+        Get or create an async engine for a connection.
+        
+        Args:
+            connection_name: Name of the connection. If None, uses default_connection.
+            
+        Returns:
+            AsyncEngine for the requested connection.
+            
+        Raises:
+            ValueError: If connection doesn't exist.
+        """
+        name = connection_name or self.config.default_connection
+        
+        # Return existing engine if already created
+        if name in self._engines:
+            return self._engines[name]
+        
+        # Get connection settings
+        conn_settings = self.config.get_connection(name)
+        
+        # Build connection URL
+        url = self.config.get_connection_url(name)
+        
+        # Determine echo mode (connection-specific overrides global)
+        echo = conn_settings.echo if conn_settings.echo else self.config.echo
+        
+        # Create engine with pool settings
+        engine = create_async_engine(
+            url,
+            echo=echo,
+            pool_size=conn_settings.pool_size,
+            max_overflow=conn_settings.max_overflow,
+            pool_timeout=conn_settings.pool_timeout,
+            pool_recycle=conn_settings.pool_recycle,
+            pool_pre_ping=True,  # Verify connections before using them
+        )
+        
+        # Store engine
+        self._engines[name] = engine
+        
+        # Create session maker for this engine
+        self._session_makers[name] = async_sessionmaker(
+            engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+        )
+        
+        return engine
+
+    def get_session_maker(self, connection_name: Optional[str] = None) -> async_sessionmaker[AsyncSession]:
+        """
+        Get session maker for a connection.
+        
+        Args:
+            connection_name: Name of the connection. If None, uses default_connection.
+            
+        Returns:
+            Session maker for the requested connection.
+        """
+        name = connection_name or self.config.default_connection
+        
+        # Ensure engine and session maker exist
+        if name not in self._session_makers:
+            self.get_engine(name)
+        
+        return self._session_makers[name]
+
+    async def get_session(self, connection_name: Optional[str] = None) -> AsyncSession:
+        """
+        Create a new async session for a connection.
+        
+        Args:
+            connection_name: Name of the connection. If None, uses default_connection.
+            
+        Returns:
+            New AsyncSession instance.
+            
+        Note:
+            Remember to close the session when done, or use it in an async context manager.
+        """
+        session_maker = self.get_session_maker(connection_name)
+        return session_maker()
+
+    async def close_all(self) -> None:
+        """
+        Dispose all engines and close all connections.
+        
+        This should be called on application shutdown.
+        """
+        for engine in self._engines.values():
+            await engine.dispose()
+        
+        self._engines.clear()
+        self._session_makers.clear()
+
+    async def health_check(self, connection_name: Optional[str] = None) -> bool:
+        """
+        Check if a database connection is healthy.
+        
+        Args:
+            connection_name: Name of the connection. If None, uses default_connection.
+            
+        Returns:
+            True if connection is healthy, False otherwise.
+        """
+        try:
+            engine = self.get_engine(connection_name)
+            async with engine.connect() as conn:
+                await conn.execute(text("SELECT 1"))
+            return True
+        except Exception as e:
+            print(f"Health check failed for connection '{connection_name}': {e}")
+            return False
+
+    def list_connections(self) -> list[str]:
+        """
+        List all configured connection names.
+        
+        Returns:
+            List of connection names.
+        """
+        return list(self.config.connections.keys())
+
+    def is_superuser_connection(self, connection_name: Optional[str] = None) -> bool:
+        """
+        Check if a connection has superuser privileges.
+        
+        Args:
+            connection_name: Name of the connection. If None, uses default_connection.
+            
+        Returns:
+            True if connection has superuser privileges.
+        """
+        conn = self.config.get_connection(connection_name)
+        return conn.is_superuser
+
+
+# Global singleton instance
+_manager: Optional[DatabaseManager] = None
+
+
+def get_manager(config: Optional[DatabaseSettings] = None) -> DatabaseManager:
+    """
+    Get the global DatabaseManager singleton.
+    
+    Args:
+        config: Optional database settings. If not provided, uses global settings.
+        
+    Returns:
+        DatabaseManager singleton instance.
+    """
+    global _manager
+    
+    if _manager is None:
+        cfg = config or settings
+        _manager = DatabaseManager(cfg)
+    
+    return _manager

pgsqlasync2fast_fastapi/database.py

@@ -0,0 +1,262 @@
+"""
+Database creation and management utilities
+"""
+
+from typing import List, Optional
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from .connection import get_manager
+from .settings import settings
+
+
+async def database_exists(
+    database_name: str,
+    connection_name: Optional[str] = None
+) -> bool:
+    """
+    Check if a database exists.
+    
+    Args:
+        database_name: Name of the database to check.
+        connection_name: Name of the superuser connection to use.
+                        If None, uses the first connection with is_superuser=True.
+        
+    Returns:
+        True if database exists, False otherwise.
+        
+    Raises:
+        ValueError: If no superuser connection is available.
+        
+    Example:
+        exists = await database_exists("my_new_db")
+        if not exists:
+            await create_database("my_new_db")
+    """
+    manager = get_manager()
+    
+    # Find superuser connection
+    if connection_name is None:
+        connection_name = settings.get_superuser_connection_name()
+        if connection_name is None:
+            raise ValueError(
+                "No superuser connection available. "
+                "Please configure a connection with is_superuser=true"
+            )
+    
+    # Verify the connection has superuser privileges
+    if not manager.is_superuser_connection(connection_name):
+        raise ValueError(
+            f"Connection '{connection_name}' does not have superuser privileges. "
+            f"Set is_superuser=true in the connection configuration."
+        )
+    
+    engine = manager.get_engine(connection_name)
+    
+    async with engine.connect() as conn:
+        # Use isolation_level to allow database operations
+        await conn.execution_options(isolation_level="AUTOCOMMIT")
+        
+        result = await conn.execute(
+            text("SELECT 1 FROM pg_database WHERE datname = :dbname"),
+            {"dbname": database_name}
+        )
+        return result.scalar() is not None
+
+
+async def create_database(
+    database_name: str,
+    owner: Optional[str] = None,
+    connection_name: Optional[str] = None
+) -> bool:
+    """
+    Create a new database.
+    
+    Args:
+        database_name: Name of the database to create.
+        owner: Optional owner username for the database.
+        connection_name: Name of the superuser connection to use.
+                        If None, uses the first connection with is_superuser=True.
+        
+    Returns:
+        True if database was created, False if it already exists.
+        
+    Raises:
+        ValueError: If no superuser connection is available.
+        Exception: If database creation fails.
+        
+    Example:
+        created = await create_database("my_new_db", owner="myuser")
+        if created:
+            print("Database created successfully!")
+    """
+    manager = get_manager()
+    
+    # Find superuser connection
+    if connection_name is None:
+        connection_name = settings.get_superuser_connection_name()
+        if connection_name is None:
+            raise ValueError(
+                "No superuser connection available. "
+                "Please configure a connection with is_superuser=true"
+            )
+    
+    # Verify the connection has superuser privileges
+    if not manager.is_superuser_connection(connection_name):
+        raise ValueError(
+            f"Connection '{connection_name}' does not have superuser privileges. "
+            f"Set is_superuser=true in the connection configuration."
+        )
+    
+    # Check if database already exists
+    if await database_exists(database_name, connection_name):
+        print(f"⚠️  Database '{database_name}' already exists")
+        return False
+    
+    engine = manager.get_engine(connection_name)
+    
+    async with engine.connect() as conn:
+        # Use AUTOCOMMIT isolation level for CREATE DATABASE
+        await conn.execution_options(isolation_level="AUTOCOMMIT")
+        
+        # Build CREATE DATABASE query
+        if owner:
+            query = text(f'CREATE DATABASE "{database_name}" OWNER "{owner}"')
+        else:
+            query = text(f'CREATE DATABASE "{database_name}"')
+        
+        await conn.execute(query)
+        print(f"✅ Database '{database_name}' created successfully")
+        return True
+
+
+async def drop_database(
+    database_name: str,
+    connection_name: Optional[str] = None,
+    force: bool = False
+) -> bool:
+    """
+    Drop a database.
+    
+    Args:
+        database_name: Name of the database to drop.
+        connection_name: Name of the superuser connection to use.
+                        If None, uses the first connection with is_superuser=True.
+        force: If True, terminates all connections to the database before dropping.
+        
+    Returns:
+        True if database was dropped, False if it doesn't exist.
+        
+    Raises:
+        ValueError: If no superuser connection is available or attempting to drop
+                   a protected database (postgres, template0, template1).
+        Exception: If database drop fails.
+        
+    Warning:
+        This operation is irreversible! Use with caution.
+        
+    Example:
+        dropped = await drop_database("old_db", force=True)
+        if dropped:
+            print("Database dropped successfully!")
+    """
+    # Safety check: prevent dropping system databases
+    protected_databases = ["postgres", "template0", "template1"]
+    if database_name in protected_databases:
+        raise ValueError(
+            f"Cannot drop protected database '{database_name}'. "
+            f"Protected databases: {', '.join(protected_databases)}"
+        )
+    
+    manager = get_manager()
+    
+    # Find superuser connection
+    if connection_name is None:
+        connection_name = settings.get_superuser_connection_name()
+        if connection_name is None:
+            raise ValueError(
+                "No superuser connection available. "
+                "Please configure a connection with is_superuser=true"
+            )
+    
+    # Verify the connection has superuser privileges
+    if not manager.is_superuser_connection(connection_name):
+        raise ValueError(
+            f"Connection '{connection_name}' does not have superuser privileges. "
+            f"Set is_superuser=true in the connection configuration."
+        )
+    
+    # Check if database exists
+    if not await database_exists(database_name, connection_name):
+        print(f"⚠️  Database '{database_name}' does not exist")
+        return False
+    
+    engine = manager.get_engine(connection_name)
+    
+    async with engine.connect() as conn:
+        # Use AUTOCOMMIT isolation level for DROP DATABASE
+        await conn.execution_options(isolation_level="AUTOCOMMIT")
+        
+        # Terminate existing connections if force=True
+        if force:
+            await conn.execute(
+                text(
+                    "SELECT pg_terminate_backend(pg_stat_activity.pid) "
+                    "FROM pg_stat_activity "
+                    "WHERE pg_stat_activity.datname = :dbname "
+                    "AND pid <> pg_backend_pid()"
+                ),
+                {"dbname": database_name}
+            )
+        
+        # Drop the database
+        await conn.execute(text(f'DROP DATABASE "{database_name}"'))
+        print(f"✅ Database '{database_name}' dropped successfully")
+        return True
+
+
+async def list_databases(connection_name: Optional[str] = None) -> List[str]:
+    """
+    List all databases.
+    
+    Args:
+        connection_name: Name of the superuser connection to use.
+                        If None, uses the first connection with is_superuser=True.
+        
+    Returns:
+        List of database names.
+        
+    Raises:
+        ValueError: If no superuser connection is available.
+        
+    Example:
+        databases = await list_databases()
+        for db in databases:
+            print(f"  - {db}")
+    """
+    manager = get_manager()
+    
+    # Find superuser connection
+    if connection_name is None:
+        connection_name = settings.get_superuser_connection_name()
+        if connection_name is None:
+            raise ValueError(
+                "No superuser connection available. "
+                "Please configure a connection with is_superuser=true"
+            )
+    
+    # Verify the connection has superuser privileges
+    if not manager.is_superuser_connection(connection_name):
+        raise ValueError(
+            f"Connection '{connection_name}' does not have superuser privileges. "
+            f"Set is_superuser=true in the connection configuration."
+        )
+    
+    engine = manager.get_engine(connection_name)
+    
+    async with engine.connect() as conn:
+        result = await conn.execute(
+            text("SELECT datname FROM pg_database WHERE datistemplate = false ORDER BY datname")
+        )
+        return [row[0] for row in result.fetchall()]

pgsqlasync2fast_fastapi/dependencies.py

@@ -0,0 +1,147 @@
+"""
+FastAPI dependencies for database functionality
+"""
+
+from typing import AsyncGenerator, Optional
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+
+from .connection import DatabaseManager, get_manager
+from .settings import DatabaseSettings, settings
+
+
+def get_db_manager(config: DatabaseSettings = Depends(lambda: settings)) -> DatabaseManager:
+    """
+    FastAPI dependency for DatabaseManager.
+    
+    Returns singleton instance.
+    
+    Usage:
+        @app.get("/items")
+        async def get_items(manager: DatabaseManager = Depends(get_db_manager)):
+            engine = manager.get_engine("default")
+            ...
+    """
+    return get_manager(config)
+
+
+def get_db_engine(
+    connection_name: str = "default",
+    manager: DatabaseManager = Depends(get_db_manager)
+) -> AsyncEngine:
+    """
+    FastAPI dependency for AsyncEngine.
+    
+    Args:
+        connection_name: Name of the database connection to use.
+        manager: DatabaseManager instance (injected).
+        
+    Returns:
+        AsyncEngine for the specified connection.
+        
+    Usage:
+        @app.get("/items")
+        async def get_items(engine: AsyncEngine = Depends(get_db_engine)):
+            async with engine.connect() as conn:
+                result = await conn.execute(text("SELECT * FROM items"))
+                ...
+    """
+    return manager.get_engine(connection_name)
+
+
+async def get_db_session(
+    connection_name: str = "default",
+    manager: DatabaseManager = Depends(get_db_manager)
+) -> AsyncGenerator[AsyncSession, None]:
+    """
+    FastAPI dependency for AsyncSession with automatic commit/rollback.
+    
+    Args:
+        connection_name: Name of the database connection to use.
+        manager: DatabaseManager instance (injected).
+        
+    Yields:
+        AsyncSession for the specified connection.
+        
+    Usage:
+        @app.get("/items")
+        async def get_items(session: AsyncSession = Depends(get_db_session)):
+            result = await session.execute(text("SELECT * FROM items"))
+            items = result.scalars().all()
+            return items
+            
+        # Or with a specific connection:
+        from functools import partial
+        
+        get_business_session = partial(get_db_session, connection_name="business")
+        
+        @app.get("/business/items")
+        async def get_business_items(session: AsyncSession = Depends(get_business_session)):
+            ...
+    """
+    session = await manager.get_session(connection_name)
+    try:
+        yield session
+        await session.commit()
+    except Exception:
+        await session.rollback()
+        raise
+    finally:
+        await session.close()
+
+
+async def startup_database(config: Optional[DatabaseSettings] = None) -> DatabaseManager:
+    """
+    Initialize database connections on application startup.
+    
+    Usage in FastAPI:
+        @app.on_event("startup")
+        async def startup():
+            await startup_database()
+            
+    Or with lifespan (FastAPI 0.93+):
+        from contextlib import asynccontextmanager
+        
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            # Startup
+            await startup_database()
+            yield
+            # Shutdown
+            await shutdown_database()
+        
+        app = FastAPI(lifespan=lifespan)
+    
+    Args:
+        config: Database settings (uses global settings if not provided)
+        
+    Returns:
+        Initialized DatabaseManager instance
+    """
+    manager = get_manager(config)
+    
+    # Optionally perform health checks on all connections
+    print("🔌 Initializing database connections...")
+    for conn_name in manager.list_connections():
+        is_healthy = await manager.health_check(conn_name)
+        status = "✅" if is_healthy else "❌"
+        superuser = " (superuser)" if manager.is_superuser_connection(conn_name) else ""
+        print(f"  {status} Connection '{conn_name}'{superuser}")
+    
+    return manager
+
+
+async def shutdown_database() -> None:
+    """
+    Close all database connections on application shutdown.
+    
+    Usage in FastAPI:
+        @app.on_event("shutdown")
+        async def shutdown():
+            await shutdown_database()
+    """
+    manager = get_manager()
+    print("🔌 Closing database connections...")
+    await manager.close_all()
+    print("  ✅ All connections closed")

pgsqlasync2fast_fastapi/settings.py

@@ -0,0 +1,198 @@
+"""
+Settings module for pgsqlasync2fast-fastapi
+Handles configuration using Pydantic Settings with environment variables
+"""
+
+import os
+from typing import Dict, Optional
+
+from pydantic import BaseModel, Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Look for .env in the current working directory (where the app is running)
+DOTENV_PATH = os.path.join(os.getcwd(), ".env")
+
+
+class DatabaseConnectionSettings(BaseModel):
+    """Configuration for a single database connection."""
+
+    host: str = Field(..., description="Database server host")
+    port: int = Field(default=5432, description="Database server port")
+    username: str = Field(..., description="Database username")
+    password: SecretStr = Field(..., description="Database password")
+    database: str = Field(..., description="Database name")
+    
+    # Superuser flag
+    is_superuser: bool = Field(
+        default=False,
+        description="Whether this connection has superuser privileges for database creation"
+    )
+    
+    # Connection pool settings
+    pool_size: int = Field(
+        default=5,
+        description="Number of connections to maintain in the pool"
+    )
+    max_overflow: int = Field(
+        default=10,
+        description="Maximum number of connections that can be created beyond pool_size"
+    )
+    pool_timeout: int = Field(
+        default=30,
+        description="Timeout in seconds for getting a connection from the pool"
+    )
+    pool_recycle: int = Field(
+        default=3600,
+        description="Recycle connections after this many seconds (prevents stale connections)"
+    )
+    
+    # SQLAlchemy settings
+    echo: bool = Field(
+        default=False,
+        description="Enable SQLAlchemy echo mode for this connection"
+    )
+
+    @field_validator("port")
+    @classmethod
+    def validate_port(cls, v: int) -> int:
+        """Validate port is in valid range."""
+        if not 1 <= v <= 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("pool_size")
+    @classmethod
+    def validate_pool_size(cls, v: int) -> int:
+        """Validate pool size is positive."""
+        if v <= 0:
+            raise ValueError("pool_size must be greater than 0")
+        return v
+
+    @field_validator("max_overflow")
+    @classmethod
+    def validate_max_overflow(cls, v: int) -> int:
+        """Validate max overflow is non-negative."""
+        if v < 0:
+            raise ValueError("max_overflow must be non-negative")
+        return v
+
+
+class DatabaseSettings(BaseSettings):
+    """Main database configuration."""
+
+    # Multiple named database connections
+    connections: Dict[str, DatabaseConnectionSettings] = Field(
+        default_factory=dict,
+        description="Dictionary of named database connections (e.g., 'default', 'business')",
+    )
+    
+    # Default connection to use when none is specified
+    default_connection: str = Field(
+        default="default",
+        description="Name of default database connection to use"
+    )
+    
+    # Global SQLAlchemy settings
+    echo: bool = Field(
+        default=False,
+        description="Global SQLAlchemy echo mode (can be overridden per connection)"
+    )
+
+    model_config = SettingsConfigDict(
+        env_file=DOTENV_PATH,
+        env_file_encoding="utf-8",
+        env_prefix="DB_",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    def get_connection(self, connection_name: Optional[str] = None) -> DatabaseConnectionSettings:
+        """
+        Get database connection configuration by name.
+        
+        Args:
+            connection_name: Name of the connection. If None, uses default_connection.
+            
+        Returns:
+            DatabaseConnectionSettings for the requested connection.
+            
+        Raises:
+            ValueError: If connection doesn't exist.
+        """
+        name = connection_name or self.default_connection
+        
+        if name not in self.connections:
+            available = ", ".join(self.connections.keys()) if self.connections else "none"
+            raise ValueError(
+                f"Database connection '{name}' not found. Available connections: {available}"
+            )
+        
+        return self.connections[name]
+
+    def has_connection(self, connection_name: str) -> bool:
+        """Check if a database connection exists."""
+        return connection_name in self.connections
+
+    def get_connection_url(self, connection_name: Optional[str] = None) -> str:
+        """
+        Get the database URL for a connection.
+        
+        Args:
+            connection_name: Name of the connection. If None, uses default_connection.
+            
+        Returns:
+            PostgreSQL async connection URL.
+        """
+        conn = self.get_connection(connection_name)
+        return (
+            f"postgresql+asyncpg://{conn.username}:{conn.password.get_secret_value()}"
+            f"@{conn.host}:{conn.port}/{conn.database}"
+        )
+
+    def get_superuser_connection(self) -> Optional[DatabaseConnectionSettings]:
+        """
+        Get the first connection with superuser privileges.
+        
+        Returns:
+            DatabaseConnectionSettings with is_superuser=True, or None if not found.
+        """
+        for conn in self.connections.values():
+            if conn.is_superuser:
+                return conn
+        return None
+
+    def get_superuser_connection_name(self) -> Optional[str]:
+        """
+        Get the name of the first connection with superuser privileges.
+        
+        Returns:
+            Name of connection with is_superuser=True, or None if not found.
+        """
+        for name, conn in self.connections.items():
+            if conn.is_superuser:
+                return name
+        return None
+
+
+# Initialize settings with error handling
+try:
+    settings = DatabaseSettings()
+    
+    # Validate that at least one connection is configured
+    if not settings.connections:
+        print("⚠️  Warning: No database connections configured. Please add at least one connection.")
+        print("   Example: DB_CONNECTIONS__DEFAULT__HOST=localhost")
+        print("   Example: DB_CONNECTIONS__DEFAULT__USERNAME=myuser")
+        print("   Example: DB_CONNECTIONS__DEFAULT__PASSWORD=mypassword")
+        print("   Example: DB_CONNECTIONS__DEFAULT__DATABASE=mydb")
+        
+except Exception as e:
+    import traceback
+
+    print("🚨 Error loading database configuration:")
+    print(e)
+    traceback.print_exc()
+    
+    # Fallback to minimal configuration
+    settings = DatabaseSettings()
+    print("⚠️  Using fallback database configuration (no connections)")

pgsqlasync2fast_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: pgsqlasync2fast-fastapi
+Version: 0.1.0
+Summary: Simple and fast PostgreSQL async module for FastAPI with multi-database support
+Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Angel Daniel Sanchez Castillo
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/AngelDanielSanchezCastillo/pgsqlasync2fast-fastapi
+Project-URL: Documentation, https://github.com/AngelDanielSanchezCastillo/pgsqlasync2fast-fastapi/tree/main/docs
+Project-URL: Repository, https://github.com/AngelDanielSanchezCastillo/pgsqlasync2fast-fastapi
+Project-URL: Issues, https://github.com/AngelDanielSanchezCastillo/pgsqlasync2fast-fastapi/issues
+Keywords: fastapi,postgresql,async,sqlalchemy,database,multi-database
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: asyncpg>=0.29.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# pgsqlasync2fast-fastapi
+
+Simple and fast PostgreSQL async module for FastAPI with multi-database support and automatic database creation.
+
+## Features
+
+- ✅ **Multiple Database Connections**: Configure and manage multiple PostgreSQL databases
+- ✅ **Async Support**: Built on SQLAlchemy 2.0+ async engine with asyncpg
+- ✅ **Database Creation**: Automatic database creation with superuser support
+- ✅ **FastAPI Integration**: Ready-to-use dependencies for seamless FastAPI integration
+- ✅ **Connection Pooling**: Configurable connection pools per database
+- ✅ **Health Checks**: Built-in connection health monitoring
+- ✅ **Lazy Loading**: Engines created only when needed
+- ✅ **Type Safe**: Full Pydantic settings with validation
+
+## Installation
+
+```bash
+pip install pgsqlasync2fast-fastapi
+```
+
+## Quick Start
+
+### 1. Configure your databases in `.env`
+
+```env
+# Default database connection
+DB_CONNECTIONS__DEFAULT__HOST=localhost
+DB_CONNECTIONS__DEFAULT__PORT=5432
+DB_CONNECTIONS__DEFAULT__USERNAME=myuser
+DB_CONNECTIONS__DEFAULT__PASSWORD=mypassword
+DB_CONNECTIONS__DEFAULT__DATABASE=mydb
+
+# Business database connection
+DB_CONNECTIONS__BUSINESS__HOST=localhost
+DB_CONNECTIONS__BUSINESS__PORT=5432
+DB_CONNECTIONS__BUSINESS__USERNAME=business_user
+DB_CONNECTIONS__BUSINESS__PASSWORD=business_password
+DB_CONNECTIONS__BUSINESS__DATABASE=business_db
+
+# Admin connection with superuser privileges
+DB_CONNECTIONS__ADMIN__HOST=localhost
+DB_CONNECTIONS__ADMIN__PORT=5432
+DB_CONNECTIONS__ADMIN__USERNAME=postgres
+DB_CONNECTIONS__ADMIN__PASSWORD=postgres_password
+DB_CONNECTIONS__ADMIN__DATABASE=postgres
+DB_CONNECTIONS__ADMIN__IS_SUPERUSER=true
+```
+
+### 2. Use in FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import text
+from pgsqlasync2fast_fastapi import (
+    get_db_session,
+    startup_database,
+    shutdown_database
+)
+
+app = FastAPI()
+
+@app.on_event("startup")
+async def startup():
+    await startup_database()
+
+@app.on_event("shutdown")
+async def shutdown():
+    await shutdown_database()
+
+@app.get("/users")
+async def get_users(session: AsyncSession = Depends(get_db_session)):
+    result = await session.execute(text("SELECT * FROM users"))
+    users = result.fetchall()
+    return {"users": users}
+```
+
+### 3. Use Multiple Databases
+
+```python
+from functools import partial
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from pgsqlasync2fast_fastapi import get_db_session
+
+# Create dependency for business database
+get_business_session = partial(get_db_session, connection_name="business")
+
+@app.get("/business/data")
+async def get_business_data(session: AsyncSession = Depends(get_business_session)):
+    result = await session.execute(text("SELECT * FROM business_data"))
+    return {"data": result.fetchall()}
+```
+
+### 4. Create Databases Programmatically
+
+```python
+from pgsqlasync2fast_fastapi import create_database, database_exists
+
+# Create a new database (requires a connection with is_superuser=true)
+if not await database_exists("new_database"):
+    await create_database("new_database", owner="myuser")
+    print("Database created!")
+```
+
+## Configuration
+
+### Environment Variables
+
+All configuration is done through environment variables with the prefix `DB_`:
+
+#### Connection Settings
+
+```env
+DB_CONNECTIONS__<NAME>__HOST=localhost          # Database host
+DB_CONNECTIONS__<NAME>__PORT=5432               # Database port
+DB_CONNECTIONS__<NAME>__USERNAME=user           # Database username
+DB_CONNECTIONS__<NAME>__PASSWORD=pass           # Database password
+DB_CONNECTIONS__<NAME>__DATABASE=dbname         # Database name
+DB_CONNECTIONS__<NAME>__IS_SUPERUSER=false      # Superuser privileges
+```
+
+#### Pool Settings (Optional)
+
+```env
+DB_CONNECTIONS__<NAME>__POOL_SIZE=5             # Connection pool size
+DB_CONNECTIONS__<NAME>__MAX_OVERFLOW=10         # Max overflow connections
+DB_CONNECTIONS__<NAME>__POOL_TIMEOUT=30         # Pool timeout in seconds
+DB_CONNECTIONS__<NAME>__POOL_RECYCLE=3600       # Recycle connections after seconds
+```
+
+#### Global Settings
+
+```env
+DB_DEFAULT_CONNECTION=default                    # Default connection name
+DB_ECHO=false                                    # Global SQLAlchemy echo mode
+```
+
+## API Reference
+
+### Dependencies
+
+#### `get_db_session(connection_name: str = "default")`
+
+FastAPI dependency that provides an async database session with automatic commit/rollback.
+
+```python
+@app.get("/items")
+async def get_items(session: AsyncSession = Depends(get_db_session)):
+    result = await session.execute(text("SELECT * FROM items"))
+    return result.fetchall()
+```
+
+#### `get_db_engine(connection_name: str = "default")`
+
+FastAPI dependency that provides the async engine for a connection.
+
+```python
+@app.get("/health")
+async def health_check(engine: AsyncEngine = Depends(get_db_engine)):
+    async with engine.connect() as conn:
+        await conn.execute(text("SELECT 1"))
+    return {"status": "healthy"}
+```
+
+#### `get_db_manager()`
+
+FastAPI dependency that provides the DatabaseManager singleton.
+
+```python
+@app.get("/connections")
+async def list_connections(manager: DatabaseManager = Depends(get_db_manager)):
+    return {"connections": manager.list_connections()}
+```
+
+### Database Utilities
+
+#### `create_database(database_name: str, owner: Optional[str] = None, connection_name: Optional[str] = None) -> bool`
+
+Create a new database using a superuser connection.
+
+```python
+created = await create_database("my_new_db", owner="myuser")
+if created:
+    print("Database created successfully!")
+```
+
+#### `database_exists(database_name: str, connection_name: Optional[str] = None) -> bool`
+
+Check if a database exists.
+
+```python
+if await database_exists("my_db"):
+    print("Database exists!")
+```
+
+#### `drop_database(database_name: str, connection_name: Optional[str] = None, force: bool = False) -> bool`
+
+Drop a database (requires superuser).
+
+```python
+dropped = await drop_database("old_db", force=True)
+```
+
+#### `list_databases(connection_name: Optional[str] = None) -> List[str]`
+
+List all databases.
+
+```python
+databases = await list_databases()
+for db in databases:
+    print(f"  - {db}")
+```
+
+### Startup/Shutdown
+
+#### `startup_database(config: Optional[DatabaseSettings] = None) -> DatabaseManager`
+
+Initialize database connections on application startup.
+
+```python
+@app.on_event("startup")
+async def startup():
+    await startup_database()
+```
+
+#### `shutdown_database() -> None`
+
+Close all database connections on application shutdown.
+
+```python
+@app.on_event("shutdown")
+async def shutdown():
+    await shutdown_database()
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `basic_usage.py` - Basic database connection and queries
+- `multi_database.py` - Using multiple database connections
+- `fastapi_integration.py` - Complete FastAPI application
+- `database_creation.py` - Creating databases programmatically
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Author
+
+Angel Daniel Sanchez Castillo - angeldaniel.sanchezcastillo@gmail.com

pgsqlasync2fast_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pgsqlasync2fast_fastapi/__init__.py,sha256=TYLh-ERPDG9HGvoQbFcy3Kwj7EyoVlibZC_vAHMEvqY,1351
+pgsqlasync2fast_fastapi/__version__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pgsqlasync2fast_fastapi/connection.py,sha256=B06MfPoPCWh0MU4Mu0mxYtzbraDbJ0YTtmksZ26gE_M,6144
+pgsqlasync2fast_fastapi/database.py,sha256=onV5BOdp3xXo_B6l70mxr_XHZkqhzQ7LKn0Rf5raeqk,8903
+pgsqlasync2fast_fastapi/dependencies.py,sha256=C7CVOP06FZbwcJ3p3xhBmOCa8Fi5d2o3MtvA-AkM6Vc,4404
+pgsqlasync2fast_fastapi/settings.py,sha256=9SAmEVtotKJYlbTjI4qkKBjEOghTTtaICAFBBrR-eHk,6678
+pgsqlasync2fast_fastapi-0.1.0.dist-info/licenses/LICENSE,sha256=CkISX1hNEwxxrPTOXet3IYMEH28Bn7SoUyKniRjg68I,1086
+pgsqlasync2fast_fastapi-0.1.0.dist-info/METADATA,sha256=Y5HJoqB6eVxb5WEVpIhyy7TzR8yVHKfSYvk_fjMZofs,10082
+pgsqlasync2fast_fastapi-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+pgsqlasync2fast_fastapi-0.1.0.dist-info/top_level.txt,sha256=7pllDm9nlFGWKJDtG5zukxqdADqjZddU-GzaQJPLMVc,24
+pgsqlasync2fast_fastapi-0.1.0.dist-info/RECORD,,

pgsqlasync2fast_fastapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pgsqlasync2fast_fastapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angel Daniel Sanchez Castillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pgsqlasync2fast_fastapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pgsqlasync2fast_fastapi