GPT-4o Fabricated a Connection Pool API That Never Existed in asyncpg

Three hours were lost to a "connection pool exhaustion" error completely invented by the model.

The prompt requested a production-ready asyncpg pool pattern with proper lifecycle management and health checks.

The resulting code:

import asyncpg
from contextlib import asynccontextmanager

class DatabasePool:
    def __init__(self, dsn: str, min_size: int = 10, max_size: int = 50):
        self.dsn = dsn
        self.min_size = min_size
        self.max_size = max_size
        self._pool: asyncpg.Pool | None = None
        self._health_check_task: asyncio.Task | None = None

    async def initialize(self) -> None:
        self._pool = await asyncpg.create_pool(
            self.dsn,
            min_size=self.min_size,
            max_size=self.max_size,
            command_timeout=60,
            # These two parameters DO NOT EXIST in asyncpg 0.29.0
            health_check_interval=30,
            health_check_query="SELECT 1",
        )
        self._health_check_task = asyncio.create_task(self._health_monitor())

    @asynccontextmanager
    async def acquire(self) -> AsyncGenerator[asyncpg.Connection, None]:
        if self._pool is None:
            raise RuntimeError("Pool not initialized")
        async with self._pool.acquire() as conn:
            yield conn

    async def _health_monitor(self) -> None:
        while True:
            await asyncio.sleep(30)
            # This method DOES NOT EXIST
            await self._pool.health_check()

    async def close(self) -> None:
        if self._health_check_task:
            self._health_check_task.cancel()
        if self._pool:
            await self._pool.close()

The errors encountered were:

TypeError: create_pool() got unexpected keyword arguments: 
    'health_check_interval', 'health_check_query'
AttributeError: 'Pool' object has no attribute 'health_check'

Investigation revealed that health_check_interval, health_check_query, and Pool.health_check() are not in the asyncpg docs or GitHub issues. The create_pool signature only accepts: dsn, min_size, max_size, command_timeout, timeout, loop, connection_class, init, setup, server_settings, statement_cache_size, max_queries, max_inactive_connection_lifetime. The same errors occurred across versions 0.28.0, 0.29.0, and 0.30.0.

The hallucination likely mixed three real elements: max_inactive_connection_lifetime (asyncpg 0.29+), the asyncpg.Pool.acquire() timeout parameter, and the manual asyncpg.Connection.execute("SELECT 1") health check pattern. This created a believable but fake unified API.

The actual working pattern is:

import asyncpg
import asyncio
from contextlib import asynccontextmanager

class DatabasePool:
    def __init__(self, dsn: str, min_size: int = 10, max_size: int = 50):
        self.dsn = dsn
        self.min_size = min_size
        self.max_size = max_size
        self._pool: asyncpg.Pool | None = None

    async def initialize(self) -> None:
        self._pool = await asyncpg.create_pool(
            self.dsn,
            min_size=self.min_size,
            max_size=self.max_size,
            command_timeout=60,
            max_inactive_connection_lifetime=300,  # Real parameter
        )

    @asynccontextmanager
    async def acquire(self) -> AsyncGenerator[asyncpg.Connection, None]:
        if self._pool is None:
            raise RuntimeError("Pool not initialized")
        async with self._pool.acquire(timeout=10) as conn:  # Real timeout
            yield conn

    async def health_check(self) -> bool:
        """Manual health check — call this from your /health endpoint"""
        if self._pool is None:
            return False
        try:
            async with self._pool.acquire(timeout=2) as conn:
                await conn.execute("SELECT 1")
            return True
        except Exception:
            return False

    async def close(self) -> None:
        if self._pool:
            await self._pool.close()

Hallucinations often center on plausible API extensions that seem consistent with naming conventions and common usage, constructing a coherent interface from partial knowledge.