Add probe option to connect without a responding server

Version detection moves to first read, so an early connection works again.

Author: florinutz

CHANGES.rst

@@ -2,6 +2,14 @@
 Changes for crate
 =================
 
+Unreleased
+==========
+
+- Added ``connect(..., probe=False)``, which creates a connection without
+  contacting the servers. The lowest server version is then resolved when it
+  is first read. Use it when the cluster may not respond yet, for example in
+  tests and during startup.
+
 2026/09/17 2.3.0
 ================
 - Added ``DefaultTypeConverter`` support that decodes ``DataType.UUID``

docs/by-example/connection.rst

@@ -21,6 +21,14 @@ This section sets up a connection object, and inspects some of its attributes.
     >>> connection.lowest_server_version.version
     (2, 0, 0)
 
+With ``probe=False``, the connection is created without contacting any server.
+The lowest server version is then resolved when it is first read, and reports
+``0.0.0`` for as long as no server answers::
+
+    >>> connection = connect(client=ClientMocked(), probe=False)
+    >>> connection.lowest_server_version.version
+    (2, 0, 0)
+
 cursor()
 ========
 

src/crate/client/connection.py

@@ -53,6 +53,7 @@ def __init__(
         time_zone=None,
         jwt_token=None,
         compress: Union[int, bool] = 8192,
+        probe: bool = True,
     ):
         """
         :param servers:
@@ -139,6 +140,13 @@ def __init__(
             ``False`` disables compression entirely.
             ``True`` compresses every request regardless of size.
             An integer compresses only when the payload exceeds that many bytes.
+        :param probe:
+            (optional, defaults to ``True``)
+            Contact the servers while the connection is created, and raise
+            ``ConnectionError`` when none of them responds.
+            With ``False``, creating the connection performs no request, and
+            the server version is resolved when it is first read. An
+            unreachable cluster then fails on the first statement.
         """  # noqa: E501
 
         self._converter = converter
@@ -168,9 +176,30 @@ def __init__(
                 jwt_token=jwt_token,
                 compress=compress,
             )
-        self.lowest_server_version = self._lowest_server_version()
+        self._version_cache: Union[Version, None] = None
+        if probe:
+            self._version_cache = self._lowest_server_version()
         self._closed = False
 
+    @property
+    def lowest_server_version(self) -> Version:
+        """
+        The lowest CrateDB version among the servers of this connection.
+
+        Without a version from the servers, comparisons against it still work,
+        and report the servers as older than any released CrateDB.
+        """
+        if self._version_cache is not None:
+            return self._version_cache
+        version = self._lowest_server_version(strict=False)
+        if version > Version("0.0.0"):
+            self._version_cache = version
+        return version
+
+    @lowest_server_version.setter
+    def lowest_server_version(self, version: Version) -> None:
+        self._version_cache = version
+
     def cursor(self, **kwargs) -> Cursor:
         """
         Return a new Cursor Object using the connection.
@@ -208,7 +237,7 @@ def get_blob_container(self, container_name):
         """
         return BlobContainer(container_name, self)
 
-    def _lowest_server_version(self):
+    def _lowest_server_version(self, strict: bool = True) -> Version:
         lowest = None
         servers = self.client.active_servers
         connection_errors = []
@@ -223,7 +252,7 @@ def _lowest_server_version(self):
                 continue
             if not lowest or version < lowest:
                 lowest = version
-        if connection_errors and not lowest:
+        if strict and connection_errors and not lowest:
             raise ConnectionError("; ".join(str(e) for e in connection_errors))
         return lowest or Version("0.0.0")
 

tests/client/test_connection.py

@@ -65,6 +65,27 @@ def test_lowest_server_version():
     assert (1, 0, 3) == connection.lowest_server_version.version
 
 
+def test_connect_without_probe_does_not_need_a_server():
+    """
+    Verify `probe=False` creates a connection without contacting any server.
+    """
+    connection = connect("localhost:44441", probe=False)
+    assert (0, 0, 0) == connection.lowest_server_version.version
+
+
+def test_lowest_server_version_resolved_on_first_read():
+    """
+    Verify the server version is resolved when read, not when connecting.
+    """
+    client = Client(servers="localhost:4200")
+    client.server_infos = lambda server: (None, None, "5.5.2")
+
+    connection = connect(client=client, probe=False)
+    assert connection._version_cache is None
+    assert (5, 5, 2) == connection.lowest_server_version.version
+    assert (5, 5, 2) == connection._version_cache.version
+
+
 def test_connection_closes_access():
     """
     Verify that a connection closes on exit and that it also closes