Normalize Redis connection handling and CLI URL resolution (#576)

# Summary

This PR makes Redis connection behavior more consistent across the SDK
and CLI. It fixes cases where different surfaces created Redis clients
differently, dropped connection kwargs, or treated internally-created
clients as externally owned.

On the SDK side, `from_existing()` paths for `SearchIndex`,
`AsyncSearchIndex`, and `SemanticRouter` now consistently prefer a
caller-provided client, preserve normalized connection kwargs, and
correctly mark internally-created clients as owned so disconnect
behavior works as expected. The shared kwargs splitting used by these
entry points is now centralized in `redisvl/redis/connection.py` so
internal _-prefixed kwargs do not leak into Redis
client construction.

This PR also routes more connection creation through
`RedisConnectionFactory` instead of ad hoc client creation. That
includes cache and SQL helper paths, and it fixes several extension
surfaces that were passing connection kwargs incorrectly into
SearchIndex.

On the CLI side, Redis URL resolution is simplified and made more
predictable. The helper now cleanly resolves between explicit `--url`,
explicit connection flags, `REDIS_URL`, and the local default, while
also avoiding malformed URL assembly and accidental empty-auth behavior.
The CLI entrypoints were simplified accordingly.

The net effect is a smaller and more uniform connection model: explicit
clients are respected, factory-based connection behavior is reused
across surfaces, reconnect/disconnect semantics are correct, and the CLI
no longer has several connection-resolution edge cases that previously
produced the wrong URL.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches core connection creation/ownership paths across `SearchIndex`,
caches, routers, and CLI URL parsing; behavior changes could affect how
clients are constructed and when connections are closed.
> 
> **Overview**
> **Normalizes Redis connection behavior across the SDK and CLI.** CLI
commands now resolve Redis endpoints deterministically (explicit `--url`
> explicit flags > `REDIS_URL` > localhost defaults), properly
URL-encode auth, and only override env URLs with SSL via scheme
rewriting.
> 
> **Unifies client creation and ownership semantics.**
`SearchIndex.from_existing`/`AsyncSearchIndex.from_existing` and
`SemanticRouter.from_existing` now prefer caller-provided clients,
split/forward only connection kwargs to `RedisConnectionFactory`, track
whether internally-created clients are owned (so `disconnect()` closes
them), and ensure temporary clients are closed on load failures. Several
extensions (`SemanticCache`, message histories, router init) now pass
`connection_kwargs` explicitly (instead of splatting), and SQL query
helper/client creation is routed through `RedisConnectionFactory`.
> 
> Adds unit tests covering CLI URL precedence/encoding and connection
normalization (client preference, kwargs forwarding, and
ownership/cleanup).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
517d281. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: tylerhutcherson

redisvl/cli/index.py

@@ -97,18 +97,13 @@ def destroy(self, args: Namespace):
 
     def _connect_to_index(self, args: Namespace) -> SearchIndex:
         # connect to redis
-        try:
-            redis_url = create_redis_url(args)
-            conn = RedisConnectionFactory.get_redis_connection(redis_url=redis_url)
-        except ValueError:
-            print("Must set REDIS_URL environment variable or provide host and port")
-            exit(1)
+        redis_url = create_redis_url(args)
 
         if args.index:
             schema = IndexSchema.from_dict({"index": {"name": args.index}})
             index = SearchIndex(schema=schema, redis_url=redis_url)
         elif args.schema:
-            index = SearchIndex.from_yaml(args.schema, redis_client=conn)
+            index = SearchIndex.from_yaml(args.schema, redis_url=redis_url)
         else:
             print("Index name or schema must be provided")
             exit(1)

redisvl/cli/stats.py

@@ -60,13 +60,7 @@ def stats(self, args: Namespace):
 
     def _connect_to_index(self, args: Namespace) -> SearchIndex:
         # connect to redis
-        try:
-            redis_url = create_redis_url(args)
-        except ValueError:
-            logger.error(
-                "Must set REDIS_ADDRESS environment variable or provide host and port"
-            )
-            exit(0)
+        redis_url = create_redis_url(args)
 
         if args.index:
             schema = IndexSchema.from_dict({"index": {"name": args.index}})

redisvl/cli/utils.py

@@ -1,29 +1,77 @@
 import os
 from argparse import ArgumentParser, Namespace
+from typing import Optional
+from urllib.parse import quote, urlparse, urlunparse
 
+from redisvl.redis.constants import REDIS_URL_ENV_VAR
 from redisvl.utils.log import get_logger
 
 logger = get_logger("[RedisVL]")
+DEFAULT_REDIS_HOST = "localhost"
+DEFAULT_REDIS_PORT = 6379
+
+
+def _has_explicit_connection_options(args: Namespace) -> bool:
+    return any(
+        (
+            getattr(args, "host", None) is not None,
+            getattr(args, "port", None) is not None,
+            bool(getattr(args, "user", None)),
+            bool(getattr(args, "password", None)),
+        )
+    )
+
+
+def _get_auth_credentials(args: Namespace) -> tuple[Optional[str], Optional[str]]:
+    return getattr(args, "user", None) or None, getattr(args, "password", None) or None
+
+
+def _build_redis_url(args: Namespace) -> str:
+    scheme = "rediss" if getattr(args, "ssl", False) else "redis"
+    host = getattr(args, "host", None)
+    if host is None:
+        host = DEFAULT_REDIS_HOST
+
+    port = getattr(args, "port", None)
+    if port is None:
+        port = DEFAULT_REDIS_PORT
+    user, password = _get_auth_credentials(args)
+
+    auth = ""
+    if user:
+        auth = quote(user, safe="")
+        if password:
+            auth += f":{quote(password, safe='')}"
+        auth += "@"
+    elif password:
+        auth = f":{quote(password, safe='')}@"
+
+    return f"{scheme}://{auth}{host}:{port}"
+
+
+def _apply_ssl_scheme(url: str) -> str:
+    parsed_url = urlparse(url)
+    if parsed_url.scheme == "rediss":
+        return url
+    return urlunparse(parsed_url._replace(scheme="rediss"))
 
 
 def create_redis_url(args: Namespace) -> str:
-    env_address = os.getenv("REDIS_URL")
+    if args.url:
+        return args.url
+    if _has_explicit_connection_options(args):
+        return _build_redis_url(args)
+
+    env_address = os.getenv(REDIS_URL_ENV_VAR)
     if env_address:
-        logger.info(f"Using Redis address from environment variable, REDIS_URL")
+        logger.info(
+            f"Using Redis address from environment variable, {REDIS_URL_ENV_VAR}"
+        )
+        if getattr(args, "ssl", False):
+            return _apply_ssl_scheme(env_address)
         return env_address
-    elif args.url:
-        return args.url
-    else:
-        url = "redis://"
-        if args.ssl:
-            url += "rediss://"
-        if args.user:
-            url += args.user
-            if args.password:
-                url += ":" + args.password
-            url += "@"
-        url += args.host + ":" + str(args.port)
-        return url
+
+    return _build_redis_url(args)
 
 
 def add_index_parsing_options(parser: ArgumentParser) -> ArgumentParser:
@@ -32,9 +80,15 @@ def add_index_parsing_options(parser: ArgumentParser) -> ArgumentParser:
         "-s", "--schema", help="Path to schema file", type=str, required=False
     )
     parser.add_argument("-u", "--url", help="Redis URL", type=str, required=False)
-    parser.add_argument("--host", help="Redis host", type=str, default="localhost")
-    parser.add_argument("-p", "--port", help="Redis port", type=int, default=6379)
-    parser.add_argument("--user", help="Redis username", type=str, default="default")
+    parser.add_argument("--host", help="Redis host", type=str, default=None)
+    parser.add_argument("-p", "--port", help="Redis port", type=int, default=None)
+    parser.add_argument("--user", help="Redis username", type=str, default=None)
     parser.add_argument("--ssl", help="Use SSL", action="store_true")
-    parser.add_argument("-a", "--password", help="Redis password", type=str, default="")
+    parser.add_argument(
+        "-a",
+        "--password",
+        help="Redis password",
+        type=str,
+        default=None,
+    )
     return parser

redisvl/extensions/cache/base.py

@@ -5,7 +5,7 @@
 """
 
 from collections.abc import Mapping
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
 
 from redis import Redis  # For backwards compatibility in type checking
 from redis.cluster import RedisCluster
@@ -113,9 +113,12 @@ def _get_redis_client(self) -> SyncRedisClient:
         """
         if self._redis_client is None:
             # Create new Redis client
-            url = self.redis_kwargs["redis_url"]
-            kwargs = self.redis_kwargs["connection_kwargs"]
-            self._redis_client = Redis.from_url(url, **kwargs)  # type: ignore
+            url = cast(Optional[str], self.redis_kwargs["redis_url"])
+            kwargs = cast(Dict[str, Any], self.redis_kwargs["connection_kwargs"])
+            self._redis_client = RedisConnectionFactory.get_redis_connection(
+                redis_url=url,
+                **kwargs,
+            )
         return self._redis_client
 
     async def _get_async_redis_client(self) -> AsyncRedisClient:
@@ -132,15 +135,12 @@ async def _get_async_redis_client(self) -> AsyncRedisClient:
                     client
                 )
             else:
-                url = str(self.redis_kwargs["redis_url"])
-                kwargs = self.redis_kwargs.get("connection_kwargs", {})
-                if not isinstance(kwargs, Mapping):
-                    raise TypeError(
-                        "Expected `connection_kwargs` to be a dictionary (e.g. {'decode_responses': True}), "
-                        f"but got type: {type(kwargs).__name__}"
-                    )
+                url = cast(Optional[str], self.redis_kwargs["redis_url"])
+                kwargs = cast(Dict[str, Any], self.redis_kwargs["connection_kwargs"])
                 self._async_redis_client = (
-                    RedisConnectionFactory.get_async_redis_connection(url, **kwargs)
+                    RedisConnectionFactory.get_async_redis_connection(
+                        redis_url=url, **kwargs
+                    )
                 )
         return self._async_redis_client
 

redisvl/extensions/cache/llm/semantic.py

@@ -141,7 +141,7 @@ def __init__(
             schema=schema,
             redis_client=self._redis_client,
             redis_url=self.redis_kwargs["redis_url"],
-            **self.redis_kwargs["connection_kwargs"],
+            connection_kwargs=self.redis_kwargs["connection_kwargs"] or None,
         )
         self._aindex = None
 
@@ -211,7 +211,7 @@ async def _get_async_index(self) -> AsyncSearchIndex:
                 schema=self._index.schema,
                 redis_client=async_client,
                 redis_url=self.redis_kwargs["redis_url"],
-                **self.redis_kwargs["connection_kwargs"],
+                connection_kwargs=self.redis_kwargs["connection_kwargs"] or None,
             )
         return self._aindex
 

redisvl/extensions/message_history/message_history.py

@@ -61,7 +61,7 @@ def __init__(
             schema=schema,
             redis_client=redis_client,
             redis_url=redis_url,
-            **connection_kwargs,
+            connection_kwargs=connection_kwargs or None,
         )
 
         self._index.create(overwrite=False)

redisvl/extensions/message_history/semantic_history.py

@@ -103,7 +103,7 @@ def __init__(
             schema=schema,
             redis_client=redis_client,
             redis_url=redis_url,
-            **connection_kwargs,
+            connection_kwargs=connection_kwargs or None,
         )
 
         # Check for existing message history index

redisvl/extensions/router/semantic.py

@@ -18,7 +18,7 @@
 from redisvl.index import SearchIndex
 from redisvl.query import FilterQuery, VectorRangeQuery
 from redisvl.query.filter import Tag
-from redisvl.redis.connection import RedisConnectionFactory
+from redisvl.redis.connection import RedisConnectionFactory, _split_from_existing_kwargs
 from redisvl.redis.utils import convert_bytes, hashify, make_dict
 from redisvl.types import SyncRedisClient
 from redisvl.utils.log import get_logger
@@ -72,6 +72,7 @@ def __init__(
                 for the redis client. Defaults to empty {}.
         """
         dtype = kwargs.pop("dtype", None)
+        index_kwargs = kwargs.pop("_index_kwargs", None)
 
         # Validate a provided vectorizer or set the default
         if vectorizer:
@@ -104,7 +105,13 @@ def __init__(
             redis_client=redis_client,
         )
 
-        self._initialize_index(redis_client, redis_url, overwrite, **connection_kwargs)
+        self._initialize_index(
+            redis_client,
+            redis_url,
+            overwrite,
+            connection_kwargs=connection_kwargs or None,
+            index_kwargs=index_kwargs,
+        )
 
         self._index.client.json().set(f"{self.name}:route_config", f".", self.to_dict())  # type: ignore
 
@@ -117,27 +124,57 @@ def from_existing(
         **kwargs,
     ) -> "SemanticRouter":
         """Return SemanticRouter instance from existing index."""
-        if redis_url:
+        init_kwargs, connection_kwargs = _split_from_existing_kwargs(
+            dict(kwargs),
+            nested_connection_keys=("connection_kwargs",),
+        )
+        lib_name = init_kwargs.get("lib_name")
+        index_kwargs: Dict[str, Any] = {}
+        created_redis_client = False
+
+        if redis_client:
+            # Just validate client type and set lib name
+            RedisConnectionFactory.validate_sync_redis(redis_client, lib_name)
+            index_kwargs["_client_validated"] = True
+        else:
+            factory_kwargs = {**connection_kwargs}
+            if lib_name is not None:
+                factory_kwargs["lib_name"] = lib_name
             redis_client = RedisConnectionFactory.get_redis_connection(
                 redis_url=redis_url,
-                **kwargs,
-            )
-        elif redis_client:
-            # Just validate client type and set lib name
-            RedisConnectionFactory.validate_sync_redis(redis_client)
-        if redis_client is None:
-            raise ValueError(
-                "Creating Redis client failed. Please check the redis_url and connection_kwargs."
+                **factory_kwargs,
             )
+            index_kwargs["_client_validated"] = True
+            index_kwargs["_owns_redis_client"] = True
+            if lib_name is not None:
+                index_kwargs["lib_name"] = lib_name
+            created_redis_client = True
 
-        router_dict = redis_client.json().get(f"{name}:route_config")
+        try:
+            router_dict = redis_client.json().get(f"{name}:route_config")
+        except Exception:
+            if created_redis_client and redis_client is not None:
+                redis_client.close()
+            raise
         if not isinstance(router_dict, dict):
+            if created_redis_client and redis_client is not None:
+                redis_client.close()
             raise ValueError(
                 f"No valid router config found for {name}. Received: {router_dict!r}"
             )
-        return cls.from_dict(
-            router_dict, redis_url=redis_url, redis_client=redis_client
-        )
+        resolved_redis_url = redis_url if created_redis_client else None
+        try:
+            return cls.from_dict(
+                router_dict,
+                redis_url=resolved_redis_url,
+                redis_client=redis_client,
+                connection_kwargs=connection_kwargs or None,
+                _index_kwargs={**init_kwargs, **index_kwargs} or None,
+            )
+        except Exception:
+            if created_redis_client and redis_client is not None:
+                redis_client.close()
+            raise
 
     @deprecated_argument("dtype")
     def _initialize_index(
@@ -146,7 +183,8 @@ def _initialize_index(
         redis_url: str = "redis://localhost:6379",
         overwrite: bool = False,
         dtype: str = "float32",
-        **connection_kwargs,
+        connection_kwargs: Optional[Dict[str, Any]] = None,
+        index_kwargs: Optional[Dict[str, Any]] = None,
     ):
         """Initialize the search index and handle Redis connection."""
 
@@ -158,7 +196,8 @@ def _initialize_index(
             schema=schema,
             redis_client=redis_client,
             redis_url=redis_url,
-            **connection_kwargs,
+            connection_kwargs=connection_kwargs,
+            **(index_kwargs or {}),
         )
 
         # Check for existing router index