fix: add timeout to pool acquire() to prevent deadlocks

When all connections are checked out, pool.acquire() now times out
using self._timeout instead of blocking forever. Raises
ConnectionError with a descriptive message on timeout.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqliteclient/pool.py

@@ -74,7 +74,15 @@ async def acquire(self) -> AsyncIterator[DqliteConnection]:
 
         # Wait for one if at max
         if conn is None:
-            conn = await self._pool.get()
+            try:
+                conn = await asyncio.wait_for(
+                    self._pool.get(), timeout=self._timeout
+                )
+            except TimeoutError:
+                raise DqliteConnectionError(
+                    f"Timed out waiting for a connection from the pool "
+                    f"(max_size={self._max_size}, timeout={self._timeout}s)"
+                ) from None
 
         try:
             # Verify connection is still good

tests/test_pool.py

@@ -32,7 +32,6 @@ async def test_acquire_when_closed(self) -> None:
             async with pool.acquire():
                 pass
 
-
     async def test_cancellation_does_not_leak_connection(self) -> None:
         """Cancelling a task that holds a connection should clean it up."""
         import asyncio
@@ -66,6 +65,25 @@ async def hold_connection():
         mock_conn.close.assert_called()
         assert pool._size < initial_size
 
+    async def test_acquire_timeout_when_pool_exhausted(self) -> None:
+        """acquire() should timeout, not block forever, when pool is exhausted."""
+        pool = ConnectionPool(["localhost:9001"], max_size=1, timeout=0.1)
+
+        mock_conn = MagicMock()
+        mock_conn.is_connected = True
+        mock_conn.connect = AsyncMock()
+        mock_conn.close = AsyncMock()
+
+        with patch.object(pool._cluster, "connect", return_value=mock_conn):
+            await pool.initialize()
+
+        # Check out the only connection
+        async with pool.acquire():
+            # Try to acquire another - should timeout
+            with pytest.raises(DqliteConnectionError, match="[Tt]imed out"):
+                async with pool.acquire():
+                    pass
+
 
 class TestConnectionPoolIntegration:
     """Integration tests requiring mocked connections."""