Update docs with new changes

Author: bgunebakan

CHANGES.rst

@@ -2,6 +2,13 @@
 Changes for crate
 =================
 
+Unreleased
+================
+
+- Breaking change: ``connect()`` now raises ``ConnectionError`` immediately if
+no configured server node responds. Changed connection behaviour to fail early 
+if the database cluster does not respond.
+
 2026/06/17 2.2.1
 ================
 
@@ -28,8 +35,6 @@ Changes for crate
   ``%(name)s`` placeholders and converts them to positional ``?`` markers
   client-side. Positional parameters using ``?`` continue to work unchanged.
 
-- Changed connection behaviour to fail early if the database cluster does not respond
-
 2026/03/09 2.1.2
 ================
 

docs/connect.rst

@@ -73,13 +73,32 @@ You can pass in as many node URLs as you like.
 
 .. TIP::
 
-    For every query, the client will attempt to connect to each node in sequence
+    When ``connect()`` is called, the client contacts each node to check
+    availability and determine the lowest server version. If no node responds,
+    a ``ConnectionError`` is raised immediately.
+
+    For every subsequent query, the client will attempt each node in sequence
     until a successful connection is made. Nodes are moved to the end of the
     list each time they are tried.
 
     Over multiple query executions, this behaviour functions as client-side
     *round-robin* load balancing. (This is analogous to `round-robin DNS`_.)
 
+.. NOTE::
+
+    Wrap ``connect()`` in a ``try/except`` block to handle an unreachable
+    cluster gracefully:
+
+    .. code-block:: python
+
+        from crate import client
+        from crate.client.exceptions import ConnectionError
+
+        try:
+            connection = client.connect(["node-1:4200", "node-2:4200"])
+        except ConnectionError as e:
+            print(f"Could not reach CrateDB cluster: {e}")
+
 .. _connection-options:
 
 Connection options