django-cfg 1.5.14__py3-none-any.whl → 1.5.29__py3-none-any.whl

django_cfg/modules/django_client/core/ir/schema.py

@@ -103,6 +103,10 @@ class IRSchemaObject(BaseModel):
         default_factory=list,
         description="Required property names",
     )
+    additional_properties: IRSchemaObject | None = Field(
+        None,
+        description="Schema for additional properties (for dynamic keys in object, e.g., Record<string, T>)",
+    )
 
     # ===== Array Items =====
     items: IRSchemaObject | None = Field(
@@ -322,8 +326,11 @@ class IRSchemaObject(BaseModel):
             >>> IRSchemaObject(name="file", type="string", format="binary").typescript_type
             'File | Blob'
         """
+        # Handle $ref (e.g., CentrifugoConfig, User, etc.)
+        if self.ref:
+            base_type = self.ref
         # Handle binary type (file uploads)
-        if self.is_binary:
+        elif self.is_binary:
             base_type = "File | Blob"
         # Handle array type with proper item type resolution
         elif self.type == "array":
@@ -336,6 +343,13 @@ class IRSchemaObject(BaseModel):
                 base_type = f"Array<{item_type}>"
             else:
                 base_type = "Array<any>"
+        # Handle object with additionalProperties (e.g., Record<string, DatabaseConfig>)
+        elif self.type == "object" and self.additional_properties:
+            if self.additional_properties.ref:
+                value_type = self.additional_properties.ref
+            else:
+                value_type = self.additional_properties.typescript_type
+            base_type = f"Record<string, {value_type}>"
         else:
             type_map = {
                 "string": "string",

django_cfg/modules/django_client/core/parser/base.py

@@ -453,6 +453,17 @@ class BaseParser(ABC):
             else:
                 items = self._parse_schema(f"{name}.items", schema.items)
 
+        # Parse additionalProperties (for Record<string, T> types)
+        additional_properties = None
+        if schema.additionalProperties and not isinstance(schema.additionalProperties, bool):
+            if isinstance(schema.additionalProperties, ReferenceObject):
+                # Resolve reference (e.g., Record<string, DatabaseConfig>)
+                additional_properties = self._resolve_ref(schema.additionalProperties)
+            else:
+                additional_properties = self._parse_schema(
+                    f"{name}.additionalProperties", schema.additionalProperties
+                )
+
         # Create IR schema
         ir_schema = IRSchemaObject(
             name=name,
@@ -462,6 +473,7 @@ class BaseParser(ABC):
             nullable=self._detect_nullable(schema),
             properties=properties,
             required=schema.required or [],
+            additional_properties=additional_properties,
             items=items,
             enum=schema.enum,
             enum_var_names=schema.x_enum_varnames,

django_cfg/modules/django_client/management/commands/generate_client.py

@@ -586,6 +586,14 @@ class Command(AdminCommand):
 
             self.stdout.write(f"\n📦 Copying TypeScript clients to Next.js admin...")
 
+            # Clean api_output_path before copying (remove old generated files)
+            if api_output_path.exists():
+                self.stdout.write(f"  🧹 Cleaning API output directory: {api_output_path.relative_to(project_path)}")
+                shutil.rmtree(api_output_path)
+
+            # Recreate directory
+            api_output_path.mkdir(parents=True, exist_ok=True)
+
             # Copy each group (exclude 'cfg' for Next.js admin)
             copied_count = 0
             for group_dir in ts_source.iterdir():
@@ -601,11 +609,7 @@ class Command(AdminCommand):
 
                 target_dir = api_output_path / group_name
 
-                # Remove old
-                if target_dir.exists():
-                    shutil.rmtree(target_dir)
-
-                # Copy new
+                # Copy group directory
                 shutil.copytree(group_dir, target_dir)
                 copied_count += 1
 

django_cfg/modules/django_logging/django_logger.py

@@ -65,6 +65,32 @@ class DjangoLogger(BaseCfgModule):
 
     _loggers: Dict[str, logging.Logger] = {}
     _configured = False
+    _debug_mode: Optional[bool] = None  # Cached debug mode to avoid repeated config loads
+
+    @classmethod
+    def _get_debug_mode(cls) -> bool:
+        """
+        Get debug mode from config (cached).
+
+        Loads config only once and caches the result to avoid repeated config loads.
+        This is a performance optimization - config loading can be expensive.
+
+        Returns:
+            True if debug mode is enabled, False otherwise
+        """
+        if cls._debug_mode is not None:
+            return cls._debug_mode
+
+        # Load config once and cache
+        try:
+            from django_cfg.core.state import get_current_config
+            config = get_current_config()
+            cls._debug_mode = config.debug if config and hasattr(config, 'debug') else False
+        except Exception:
+            import os
+            cls._debug_mode = os.getenv('DEBUG', 'false').lower() in ('true', '1', 'yes')
+
+        return cls._debug_mode
 
     @classmethod
     def get_logger(cls, name: str = "django_cfg") -> logging.Logger:
@@ -92,13 +118,8 @@ class DjangoLogger(BaseCfgModule):
         # print(f"  Django logs: {logs_dir / 'django.log'}")
         # print(f"  Django-CFG logs: {djangocfg_logs_dir}/")
 
-        # Get debug mode
-        try:
-            from django_cfg.core.state import get_current_config
-            config = get_current_config()
-            debug = config.debug if config else False
-        except Exception:
-            debug = os.getenv('DEBUG', 'false').lower() in ('true', '1', 'yes')
+        # Get debug mode (cached - loaded once)
+        debug = cls._get_debug_mode()
 
         # Create handlers
         try:
@@ -111,9 +132,13 @@ class DjangoLogger(BaseCfgModule):
                 backupCount=30,  # Keep 30 days of logs
                 encoding='utf-8',
             )
-            django_handler.setLevel(logging.DEBUG if debug else logging.INFO)  # INFO+ in production, DEBUG in dev
+            # File handlers ALWAYS capture DEBUG in dev mode (for complete debugging history)
+            # In production, still use INFO+ to save disk space
+            django_handler.setLevel(logging.DEBUG if debug else logging.INFO)
 
-            # Console handler - WARNING+ always (less noise)
+            # Console handler - configurable noise level
+            # In dev: show DEBUG+ (full visibility)
+            # In production: show WARNING+ only (reduce noise)
             console_handler = logging.StreamHandler()
             console_handler.setLevel(logging.DEBUG if debug else logging.WARNING)
 
@@ -123,8 +148,10 @@ class DjangoLogger(BaseCfgModule):
             console_handler.setFormatter(formatter)
 
             # Configure root logger
+            # CRITICAL: Root logger must be DEBUG in dev mode to allow all messages through
+            # Handlers will filter based on their own levels, but logger must not block
             root_logger = logging.getLogger()
-            root_logger.setLevel(logging.DEBUG if debug else logging.INFO)  # INFO+ in production, DEBUG in dev
+            root_logger.setLevel(logging.DEBUG if debug else logging.INFO)
 
             # Clear existing handlers
             root_logger.handlers.clear()
@@ -149,9 +176,24 @@ class DjangoLogger(BaseCfgModule):
 
     @classmethod
     def _create_logger(cls, name: str) -> logging.Logger:
-        """Create logger with modular file handling for django-cfg loggers."""
+        """
+        Create logger with modular file handling for django-cfg loggers.
+
+        In dev/debug mode, loggers inherit DEBUG level from root logger,
+        ensuring all log messages reach file handlers regardless of explicit level settings.
+        """
         logger = logging.getLogger(name)
 
+        # In dev mode, ensure logger doesn't block DEBUG messages
+        # Logger inherits from root by default (propagate=True), which is set to DEBUG in dev
+        # This is crucial: logger level must be <= handler level, or messages get blocked
+        debug = cls._get_debug_mode()  # Use cached debug mode
+
+        # In dev mode, force DEBUG level on logger to ensure complete file logging
+        # Handlers will still filter console output (WARNING+), but files get everything (DEBUG+)
+        if debug and not logger.level:
+            logger.setLevel(logging.DEBUG)
+
         # If this is a django-cfg logger, add a specific file handler
         if name.startswith('django_cfg'):
             try:
@@ -181,15 +223,12 @@ class DjangoLogger(BaseCfgModule):
                     encoding='utf-8',
                 )
 
-                # Get debug mode
-                try:
-                    from django_cfg.core.state import get_current_config
-                    config = get_current_config()
-                    debug = config.debug if config else False
-                except Exception:
-                    debug = os.getenv('DEBUG', 'false').lower() in ('true', '1', 'yes')
+                # Get debug mode (cached - loaded once)
+                debug = cls._get_debug_mode()
 
-                file_handler.setLevel(logging.DEBUG if debug else logging.INFO)  # INFO+ in production, DEBUG in dev
+                # Module file handlers ALWAYS capture DEBUG in dev mode
+                # This ensures complete log history for debugging, independent of logger level
+                file_handler.setLevel(logging.DEBUG if debug else logging.INFO)
 
                 # Set format
                 formatter = logging.Formatter('[%(asctime)s] %(levelname)s in %(name)s [%(filename)s:%(lineno)d]: %(message)s')

django_cfg/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "django-cfg"
-version = "1.5.14"
+version = "1.5.29"
 description = "Modern Django framework with type-safe Pydantic v2 configuration, Next.js admin integration, real-time WebSockets, and 8 enterprise apps. Replace settings.py with validated models, 90% less code. Production-ready with AI agents, auto-generated TypeScript clients, and zero-config features."
 readme = "README.md"
 keywords = [ "django", "configuration", "pydantic", "settings", "type-safety", "pydantic-settings", "django-environ", "startup-validation", "ide-autocomplete", "nextjs-admin", "react-admin", "websocket", "centrifugo", "real-time", "typescript-generation", "ai-agents", "enterprise-django", "django-settings", "type-safe-config", "modern-django",]
@@ -26,13 +26,13 @@ text = "MIT"
 local = []
 django52 = [ "django>=5.2,<6.0",]
 ai = [ "pydantic-ai>=1.0.10,<2.0",]
-grpc = [ "grpcio>=1.50.0,<2.0", "grpcio-tools>=1.50.0,<2.0", "grpcio-reflection>=1.50.0,<2.0", "grpcio-health-checking>=1.50.0,<2.0", "protobuf>=5.0,<7.0",]
+grpc = [ "grpcio>=1.50.0,<2.0", "grpcio-tools>=1.50.0,<2.0", "grpcio-reflection>=1.50.0,<2.0", "grpcio-health-checking>=1.50.0,<2.0", "protobuf>=5.0,<7.0", "aiobreaker>=1.2.0,<2.0",]
 centrifugo = [ "cent>=5.0.0,<6.0", "websockets>=13.0,<15.0",]
 dev = [ "django>=5.2,<6.0", "pytest>=7.0", "pytest-django>=4.5", "pytest-cov>=4.0", "pytest-mock>=3.0", "factory-boy>=3.0", "fakeredis>=2.0", "black>=23.0", "isort>=5.0", "flake8>=5.0", "mypy>=1.0", "pre-commit>=3.0", "build>=1.0", "twine>=4.0", "tomlkit>=0.11", "questionary>=2.0", "rich>=13.0", "mkdocs>=1.5", "mkdocs-material>=9.0", "mkdocstrings[python]>=0.24", "redis>=5.0",]
 test = [ "django>=5.2,<6.0", "pytest>=7.0", "pytest-django>=4.5", "pytest-cov>=4.0", "pytest-mock>=3.0", "pytest-xdist>=3.0", "factory-boy>=3.0", "fakeredis>=2.0",]
 docs = [ "mkdocs>=1.5", "mkdocs-material>=9.0", "mkdocstrings[python]>=0.24", "pymdown-extensions>=10.0",]
 tasks = [ "redis>=5.0",]
-full = [ "django>=5.2,<6.0", "pytest>=7.0", "pytest-django>=4.5", "pytest-cov>=4.0", "pytest-mock>=3.0", "pytest-xdist>=3.0", "factory-boy>=3.0", "black>=23.0", "isort>=5.0", "flake8>=5.0", "mypy>=1.0", "pre-commit>=3.0", "build>=1.0", "twine>=4.0", "tomlkit>=0.11", "questionary>=2.0", "rich>=13.0", "mkdocs>=1.5", "mkdocs-material>=9.0", "mkdocstrings[python]>=0.24", "pymdown-extensions>=10.0", "redis>=5.0", "grpcio>=1.50.0,<2.0", "grpcio-tools>=1.50.0,<2.0", "grpcio-reflection>=1.50.0,<2.0", "grpcio-health-checking>=1.50.0,<2.0", "protobuf>=5.0,<7.0", "cent>=5.0.0,<6.0", "websockets>=13.0,<15.0", "django-rq>=3.0", "rq>=1.0", "rq-scheduler>=0.13", "hiredis>=2.0",]
+full = [ "django>=5.2,<6.0", "pytest>=7.0", "pytest-django>=4.5", "pytest-cov>=4.0", "pytest-mock>=3.0", "pytest-xdist>=3.0", "factory-boy>=3.0", "black>=23.0", "isort>=5.0", "flake8>=5.0", "mypy>=1.0", "pre-commit>=3.0", "build>=1.0", "twine>=4.0", "tomlkit>=0.11", "questionary>=2.0", "rich>=13.0", "mkdocs>=1.5", "mkdocs-material>=9.0", "mkdocstrings[python]>=0.24", "pymdown-extensions>=10.0", "redis>=5.0", "grpcio>=1.50.0,<2.0", "grpcio-tools>=1.50.0,<2.0", "grpcio-reflection>=1.50.0,<2.0", "grpcio-health-checking>=1.50.0,<2.0", "protobuf>=5.0,<7.0", "aiobreaker>=1.2.0,<2.0", "cent>=5.0.0,<6.0", "websockets>=13.0,<15.0", "django-rq>=3.0", "rq>=1.0", "rq-scheduler>=0.13", "hiredis>=2.0",]
 rq = [ "django-rq>=3.0", "rq>=1.0", "rq-scheduler>=0.13", "redis>=5.0", "hiredis>=2.0",]
 
 [project.urls]

django_cfg/templates/admin/index.html

@@ -179,8 +179,6 @@
                     iframeId = 'nextjs-dashboard-iframe-builtin';
                 } else if (tab === 'nextjs') {
                     iframeId = 'nextjs-dashboard-iframe-nextjs';
-                } else if (tab === 'docs') {
-                    iframeId = 'nextjs-dashboard-iframe-docs';
                 }
 
                 const iframe = document.getElementById(iframeId);
@@ -200,8 +198,6 @@
                     iframeId = 'nextjs-dashboard-iframe-builtin';
                 } else if (this.activeTab === 'nextjs') {
                     iframeId = 'nextjs-dashboard-iframe-nextjs';
-                } else if (this.activeTab === 'docs') {
-                    iframeId = 'nextjs-dashboard-iframe-docs';
                 }
 
                 const iframe = document.getElementById(iframeId);
@@ -298,17 +294,6 @@
                             <span class="hidden sm:inline">{% nextjs_external_admin_title %}</span>
                             <span class="sm:hidden">Admin</span>
                         </button>
-
-                        {% if is_development %}
-                        <button @click="switchTab('docs')"
-                                class="whitespace-nowrap py-4 px-2 border-b-2 font-medium text-sm flex items-center gap-2 transition-all duration-200"
-                                :class="activeTab === 'docs'
-                                    ? 'border-primary-600 text-primary-600 dark:border-primary-500 dark:text-primary-500'
-                                    : 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300 dark:text-gray-400 dark:hover:text-gray-300 dark:hover:border-gray-700'">
-                            <span class="material-icons text-base">description</span>
-                            <span>Docs</span>
-                        </button>
-                        {% endif %}
                             </nav>
 
                             <!-- Actions & Version -->
@@ -372,27 +357,6 @@
                     ></iframe>
                 </div>
             </div>
-
-            <!-- Docs Tab Content (Development Mode Only) -->
-            {% if is_development %}
-            <div x-show="activeTab === 'docs'" style="display: none;">
-                <div class="iframe-container">
-                    <div class="iframe-loading" id="iframe-loading-docs">
-                        <div class="spinner"></div>
-                        <p id="loading-text-docs">Loading documentation...</p>
-                    </div>
-
-                    <iframe
-                        id="nextjs-dashboard-iframe-docs"
-                        class="nextjs-dashboard-iframe"
-                        src="{% lib_docs_url %}"
-                        data-original-src="{% lib_docs_url %}"
-                        title="Documentation"
-                        sandbox="allow-same-origin allow-scripts allow-forms allow-popups allow-modals allow-storage-access-by-user-activation"
-                    ></iframe>
-                </div>
-            </div>
-            {% endif %}
         </div>
     {% endcomponent %}
 {% endblock %}
@@ -807,9 +771,6 @@
 
                 manager.register('nextjs-dashboard-iframe-builtin', 'iframe-loading-builtin');
                 manager.register('nextjs-dashboard-iframe-nextjs', 'iframe-loading-nextjs');
-                {% if is_development %}
-                manager.register('nextjs-dashboard-iframe-docs', 'iframe-loading-docs', { external: true });
-                {% endif %}
                 // console.log('[Django-CFG] Iframe registration completed');
             }
 

django_cfg/utils/pool_monitor.py

@@ -0,0 +1,320 @@
+"""
+Connection Pool Monitoring for Django-CFG.
+
+Provides utilities to monitor and inspect PostgreSQL connection pool status.
+Works with Django 5.1+ native connection pooling (psycopg3).
+
+Usage:
+    from django_cfg.utils.pool_monitor import PoolMonitor
+
+    # Get pool statistics
+    monitor = PoolMonitor()
+    stats = monitor.get_pool_stats()
+
+    # Check pool health
+    health = monitor.check_pool_health()
+
+    # Log pool status
+    monitor.log_pool_status()
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from django.conf import settings
+from django.db import connection
+
+from .smart_defaults import _detect_asgi_mode, get_pool_config
+
+logger = logging.getLogger('django_cfg.pool_monitor')
+
+
+class PoolMonitor:
+    """
+    Monitor and inspect database connection pool.
+
+    Provides methods to retrieve pool statistics, check health,
+    and log pool status for operational visibility.
+    """
+
+    def __init__(self, database_alias: str = 'default'):
+        """
+        Initialize pool monitor.
+
+        Args:
+            database_alias: Database alias to monitor (default: 'default')
+        """
+        self.database_alias = database_alias
+
+    def get_pool_stats(self) -> Optional[Dict[str, Any]]:
+        """
+        Get current connection pool statistics.
+
+        Returns:
+            Dict with pool statistics:
+            {
+                'pool_size': int,          # Current pool size
+                'pool_available': int,     # Available connections
+                'pool_min_size': int,      # Configured minimum size
+                'pool_max_size': int,      # Configured maximum size
+                'pool_timeout': int,       # Connection timeout
+                'is_asgi': bool,           # Deployment mode
+                'environment': str,        # Environment name
+                'backend': str,            # Database backend
+                'has_pool': bool,          # Whether pooling is enabled
+            }
+
+            Returns None if connection pooling is not configured.
+
+        Example:
+            >>> monitor = PoolMonitor()
+            >>> stats = monitor.get_pool_stats()
+            >>> print(f"Pool size: {stats['pool_size']}/{stats['pool_max_size']}")
+        """
+        try:
+            # Get database configuration
+            db_config = settings.DATABASES.get(self.database_alias, {})
+            backend = db_config.get('ENGINE', 'unknown')
+
+            # Check if PostgreSQL with pooling
+            if 'postgresql' not in backend:
+                logger.debug(f"Database {self.database_alias} is not PostgreSQL, pooling not available")
+                return None
+
+            pool_options = db_config.get('OPTIONS', {}).get('pool', {})
+            if not pool_options:
+                logger.debug(f"No pool configuration found for database {self.database_alias}")
+                return None
+
+            # Detect environment and mode
+            is_asgi = _detect_asgi_mode()
+            environment = getattr(settings, 'ENVIRONMENT', 'production')
+
+            # Get expected pool config
+            expected_config = get_pool_config(environment, is_asgi=is_asgi)
+
+            # Try to get actual pool statistics from psycopg3
+            pool_size = None
+            pool_available = None
+
+            try:
+                # Access underlying psycopg3 connection pool
+                # This requires psycopg3 with connection pooling
+                db_conn = connection.connection
+                if db_conn and hasattr(db_conn, 'pgconn'):
+                    pool = getattr(db_conn, 'pool', None)
+                    if pool:
+                        # psycopg3 ConnectionPool has these attributes
+                        pool_size = getattr(pool, 'size', None)
+                        pool_available = getattr(pool, 'available', None)
+            except Exception as e:
+                logger.debug(f"Could not retrieve live pool stats: {e}")
+
+            return {
+                'pool_size': pool_size,
+                'pool_available': pool_available,
+                'pool_min_size': pool_options.get('min_size', expected_config['min_size']),
+                'pool_max_size': pool_options.get('max_size', expected_config['max_size']),
+                'pool_timeout': pool_options.get('timeout', expected_config['timeout']),
+                'max_lifetime': pool_options.get('max_lifetime', 3600),
+                'max_idle': pool_options.get('max_idle', 600),
+                'is_asgi': is_asgi,
+                'environment': environment,
+                'backend': backend,
+                'has_pool': True,
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to get pool stats: {e}", exc_info=True)
+            return None
+
+    def check_pool_health(self) -> Dict[str, Any]:
+        """
+        Check connection pool health status.
+
+        Returns:
+            Dict with health information:
+            {
+                'healthy': bool,           # Overall health status
+                'status': str,             # 'healthy', 'warning', 'critical', 'unavailable'
+                'capacity_percent': float, # Pool capacity usage (0-100)
+                'issues': list,            # List of detected issues
+                'recommendations': list,   # Recommended actions
+            }
+
+        Health thresholds:
+            - < 70% capacity: Healthy
+            - 70-90% capacity: Warning
+            - > 90% capacity: Critical
+
+        Example:
+            >>> monitor = PoolMonitor()
+            >>> health = monitor.check_pool_health()
+            >>> if not health['healthy']:
+            ...     print(f"Issues: {', '.join(health['issues'])}")
+        """
+        stats = self.get_pool_stats()
+
+        if not stats or not stats['has_pool']:
+            return {
+                'healthy': True,  # No pool = no problem (using regular connections)
+                'status': 'unavailable',
+                'capacity_percent': 0.0,
+                'issues': ['Connection pooling not configured'],
+                'recommendations': ['Consider enabling connection pooling for production'],
+            }
+
+        issues = []
+        recommendations = []
+        healthy = True
+        status = 'healthy'
+
+        # Calculate capacity if live stats available
+        capacity_percent = 0.0
+        if stats['pool_size'] is not None and stats['pool_max_size']:
+            capacity_percent = (stats['pool_size'] / stats['pool_max_size']) * 100
+
+            # Check capacity thresholds
+            if capacity_percent >= 90:
+                status = 'critical'
+                healthy = False
+                issues.append(f"Pool capacity critical: {capacity_percent:.1f}% used")
+                recommendations.append("Increase DB_POOL_MAX_SIZE or scale database")
+            elif capacity_percent >= 70:
+                status = 'warning'
+                issues.append(f"Pool capacity high: {capacity_percent:.1f}% used")
+                recommendations.append("Monitor pool usage and consider increasing max_size")
+
+        # Check if min_size is reasonable
+        min_size = stats['pool_min_size']
+        max_size = stats['pool_max_size']
+
+        if min_size >= max_size * 0.9:
+            issues.append(f"Min size ({min_size}) too close to max size ({max_size})")
+            recommendations.append("Reduce DB_POOL_MIN_SIZE for better resource management")
+
+        # Check timeout
+        timeout = stats['pool_timeout']
+        if timeout > 30:
+            issues.append(f"Pool timeout high: {timeout}s")
+            recommendations.append("Long timeouts may indicate slow queries or insufficient pool size")
+
+        # Check ASGI vs WSGI pool sizing
+        is_asgi = stats['is_asgi']
+        mode = 'ASGI' if is_asgi else 'WSGI'
+
+        expected_config = get_pool_config(stats['environment'], is_asgi=is_asgi)
+        if max_size < expected_config['max_size'] * 0.5:
+            issues.append(f"Pool size low for {mode} mode")
+            recommendations.append(f"Consider increasing to {expected_config['max_size']} for {mode}")
+
+        return {
+            'healthy': healthy and len(issues) == 0,
+            'status': status,
+            'capacity_percent': capacity_percent,
+            'issues': issues,
+            'recommendations': recommendations,
+        }
+
+    def log_pool_status(self, level: str = 'info') -> None:
+        """
+        Log current pool status to Django logger.
+
+        Args:
+            level: Log level ('debug', 'info', 'warning', 'error')
+
+        Example:
+            >>> monitor = PoolMonitor()
+            >>> monitor.log_pool_status(level='info')
+        """
+        stats = self.get_pool_stats()
+
+        if not stats:
+            logger.debug(f"No pool statistics available for database {self.database_alias}")
+            return
+
+        health = self.check_pool_health()
+
+        log_func = getattr(logger, level, logger.info)
+
+        mode = 'ASGI' if stats['is_asgi'] else 'WSGI'
+        status_emoji = {
+            'healthy': '✅',
+            'warning': '⚠️',
+            'critical': '🔴',
+            'unavailable': '⚪',
+        }.get(health['status'], '❓')
+
+        log_message = (
+            f"[Pool Monitor] {status_emoji} Status: {health['status'].upper()} | "
+            f"Mode: {mode} | Env: {stats['environment']} | "
+            f"Pool: {stats['pool_size'] or '?'}/{stats['pool_max_size']} | "
+            f"Capacity: {health['capacity_percent']:.1f}%"
+        )
+
+        log_func(log_message)
+
+        if health['issues']:
+            for issue in health['issues']:
+                logger.warning(f"[Pool Monitor] Issue: {issue}")
+
+        if health['recommendations']:
+            for rec in health['recommendations']:
+                logger.info(f"[Pool Monitor] Recommendation: {rec}")
+
+    def get_pool_info_dict(self) -> Dict[str, Any]:
+        """
+        Get complete pool information as a dictionary.
+
+        Combines statistics and health check into a single dict.
+        Useful for API responses or structured logging.
+
+        Returns:
+            Dict with complete pool information including stats and health.
+
+        Example:
+            >>> monitor = PoolMonitor()
+            >>> info = monitor.get_pool_info_dict()
+            >>> print(json.dumps(info, indent=2))
+        """
+        stats = self.get_pool_stats()
+        health = self.check_pool_health()
+
+        if not stats:
+            return {
+                'available': False,
+                'reason': 'Connection pooling not configured',
+            }
+
+        return {
+            'available': True,
+            'statistics': stats,
+            'health': health,
+            'timestamp': self._get_timestamp(),
+        }
+
+    @staticmethod
+    def _get_timestamp() -> str:
+        """Get current timestamp in ISO format."""
+        from datetime import datetime
+        return datetime.utcnow().isoformat() + 'Z'
+
+
+# Convenience function for quick pool status check
+def get_pool_status(database_alias: str = 'default') -> Dict[str, Any]:
+    """
+    Convenience function to quickly get pool status.
+
+    Args:
+        database_alias: Database alias to check (default: 'default')
+
+    Returns:
+        Dict with pool information (same as PoolMonitor.get_pool_info_dict())
+
+    Example:
+        >>> from django_cfg.utils.pool_monitor import get_pool_status
+        >>> status = get_pool_status()
+        >>> print(status['health']['status'])
+    """
+    monitor = PoolMonitor(database_alias=database_alias)
+    return monitor.get_pool_info_dict()