feat(index): owns_client for explicit Redis client ownership handover

[vishal-bala]

Motivation

#660 reports that SearchIndex.set_client() keeps client ownership, so an index closes a client the caller still owns. Two earlier pull requests tried to repair the ownership logic inside set_client() and both were closed: the method has carried a DeprecationWarning since v0.4.0 and the project has shipped 23 further minor versions without removing it, so patching it adds machinery to a code path nobody should be on. The agreed fix is removal.

This is the first of three stacked pull requests doing that. It removes nothing. It puts in place the one thing callers lose when set_client() goes — a supported way to hand an index a client it should close — and clears the internal callers that would otherwise complicate the removal diffs. The two branches above it delete the deprecated index API and the deprecated connection-factory API.

Changes

A public owns_client, replacing a private keyword

An index closed only a client it created itself, and callers needing to override that passed a private _owns_redis_client keyword or wrote the attribute afterwards. The MCP server did the latter, which never worked as intended: _register_client_finalizer gates on the flag, so a post-construction flip lands after registration has already declined and no finalizer is ever created. That server was relying entirely on its explicit disconnect(), with no safety net if a binding runtime were ever dropped.

owns_client states ownership once, at construction, before the finalizer is registered. It replaces the private keyword rather than sitting beside it, so there is one spelling and no precedence question.

# hand over a client you created; the index will close it
index = SearchIndex(schema, redis_client=client, owns_client=True)

# keep a client the index would otherwise close; closing it is now yours
index = SearchIndex(schema, redis_url=url, owns_client=False)

The default is unchanged: an index owns a client it created and never closes one you passed. Note the default follows from who created the client, not from which argument you used — get_redis_connection falls back to REDIS_URL, so an index built with no connection arguments at all also creates and owns one.

Async cache clients no longer warn, and no longer race

BaseCache._get_async_redis_client called get_async_redis_connection, which warns unconditionally, so anyone who built a cache from a redis_url and awaited a cache method saw a DeprecationWarning for an API they never called. A suite-wide filterwarnings entry in pyproject.toml had been hiding it. The method now uses _get_aredis_connection and the filter is gone.

That move introduced an await inside the lazy-init guard, which made check-then-set non-atomic and let two concurrent callers each build a client, orphaning the first with its pool never released. The lazy path is now wrapped in the same double-checked lock AsyncSearchIndex._get_client already uses over the same factory. The regression test fails without the lock.

Migration modules read the client that actually exists

The four modules under redisvl/migration/ read index.client, which is None until the client is lazily created, and each handled that differently: one raised, two recorded an error, one degraded to an empty key sample that then made the key-sample check vacuously true. All four build their index through from_existing, which always yields a client, so none of it was reachable. They now read through the lazy accessors and the dead guards are gone.

Smaller changes

• The deprecation decorators promised removal "in the next major release". Every release so far has been 0.x and breaking changes ship on minor bumps here, so they now say "in a future release".
• disconnect() was documented as "Disconnect from the Redis database" on two classes and not at all on the async one, and its log line claimed the index did not own a client it had in fact created. Both corrected, and owns_client is documented on from_existing too.
• owns_client is coerced with bool(): the finalizer gate tests truthiness while disconnect tested is False, so a falsy non-bool made the two paths disagree.
• The retired _owns_redis_client keyword is now rejected with a TypeError. Underscore-prefixed keywords are forwarded verbatim by _split_from_existing_kwargs, so it would otherwise be dropped in silence and leak the connection it used to control.

Notes

SemanticRouter.from_existing merged {**init_kwargs, **index_kwargs} with index_kwargs second, so it discarded an explicit owns_client=False while SearchIndex.from_existing honoured it. All three public from_existing entry points now agree, and the rule is that an explicit value beats the ownership the library would otherwise infer. The consequence worth knowing: from_existing(name, redis_url=..., owns_client=False) produces a client nobody closes. The caller keeps a handle via .client, so it is an escape hatch rather than a leak, but there is no good reason to ask for it.

Cache clients now issue CLIENT SETINFO when they are created, so they finally report their library name like every other RedisVL client. The same change means an unreachable server surfaces ConnectionError at client creation rather than at the first command. A ResponseError there is still swallowed, so a restricted ACL that forbids CLIENT SETINFO is unaffected.

Handing the same client to two indexes with owns_client=True registers two finalizers on it, so collecting the first closes the pool under the second. Do not do this. The redis-py documentation is explicit that closing one client which shares a ConnectionPool silently invalidates the connections every other client using it holds, so the consequence is silent failure rather than reconnection. Ownership belongs to exactly one holder.

The migration modules now reach into another package's private accessors. That is deliberate staging: the root cause is .client being Optional, which cannot be fixed until connect() and set_client() are gone. Branch 03 makes .client non-optional and reverts these call sites to the public property.

BaseCache still derives its own ownership flag with no keyword override and registers no finalizer, so there is no cache equivalent of this handover. That asymmetry is intentional here and recorded in a comment; nothing in the library needs to hand a cache a client it should close.

Release Notes

SearchIndex and AsyncSearchIndex accept a new owns_client argument controlling whether the index closes the Redis client when it is disconnected or garbage collected. By default an index closes only a client it created itself and never closes one passed as redis_client, which is unchanged. Pass owns_client=True to hand over a client you created, or owns_client=False to keep one the index would otherwise close.

A cache built from a redis_url now raises ConnectionError when its async client is created rather than at the first command, so an unreachable server surfaces earlier than before.

---

Note

Medium Risk
Changes Redis client ownership and lazy-init concurrency for indexes and caches; incorrect owns_client use can close shared clients or leave connections open, though defaults preserve prior behavior.

Overview
Introduces a public owns_client flag on SearchIndex and AsyncSearchIndex so callers can declare at construction whether the index should close the Redis client on disconnect() or GC. The private _owns_redis_client keyword is rejected with TypeError; from_existing paths (including SemanticRouter and MCP) now pass owns_client consistently, with an explicit value overriding inferred ownership.

BaseCache._get_async_redis_client now awaits _get_aredis_connection (no deprecation warning) and uses a double-checked asyncio.Lock so concurrent lazy creation shares one client. The pytest filterwarnings hide for that warning is removed.

Migration and validation code stops reading index.client (often None before lazy init) and uses _get_client() / _redis_client instead, dropping redundant null checks.

Deprecation helper text changes from “next major release” to “in a future release”; disconnect() docs and ownership logging are clarified.

^{Reviewed by Cursor Bugbot for commit 29c37b1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 29c37b1. Configure here.}

[cursor]

Cache lock breaks cross-loop reconnect

Medium Severity

The new _async_client_lock is created in __init__ and reused for the life of the cache. On Python 3.10–3.13 an asyncio.Lock binds to the loop that first acquires it, so after adisconnect() clears _async_redis_client, a later lazy reconnect on a new loop (a second asyncio.run(), a new pytest-asyncio loop, Jupyter) raises RuntimeError instead of opening a new client.

Additional Locations (1)

• redisvl/extensions/cache/base.py#L142-L144

 

^{Reviewed by Cursor Bugbot for commit 29c37b1. Configure here.}

[cursor]

None owns_client leaks factory client

Low Severity

from_existing uses setdefault("owns_client", True) (and SemanticRouter’s "owns_client" not in init_kwargs check) to mark a factory-created client as owned. An explicit owns_client=None still counts as present, so __init__ infers ownership from the already-built redis_client and leaves _owns_redis_client false. The documented default when the method created the client is to close it; that client is then closed by nobody.

Additional Locations (2)

• redisvl/index/index.py#L2413-L2414
• redisvl/extensions/router/semantic.py#L202-L204

 

^{Reviewed by Cursor Bugbot for commit 29c37b1. Configure here.}