refactor(kuzu): Reflect KuzuDB deprecation and provide users with an exit route (migrating to another DB)#1302
Open
macunha1 wants to merge 4 commits into
Open
refactor(kuzu): Reflect KuzuDB deprecation and provide users with an exit route (migrating to another DB)#1302macunha1 wants to merge 4 commits into
macunha1 wants to merge 4 commits into
Conversation
…ckend
KuzuDB is deprecated upstream; LadybugDB takes over as the default
embedded backend on all platforms, keeping the zero-config experience.
- Removes database_kuzu.py and all kuzu-specific tests and fixtures
- kuzu pip dependency removed from pyproject.toml
- Fallback chain is now: FalkorDB Lite -> LadybugDB -> Neo4j
- Explicit kuzudb selection (CGC_RUNTIME_DB_TYPE=kuzudb, --db kuzudb,
cgc config db kuzudb) now raises an error instead of silently routing
to the deprecated backend
- KuzuCoordinator (website Supabase realtime tunnel) renamed
CGCCoordinator; class never used KuzuDB - name was a misnomer
…ckets redis-py 8 defaults to RESP3, which triggers a maintenance-notifications handshake on every connection. The handshake requires a TCP host attribute to determine the endpoint type. Unix-socket connections set host=None, which passes hasattr(conn, "host") but then raises inside _enable_maintenance_notifications when it checks the value. Fix: pass protocol=2 to FalkorDB(...) to force RESP2. The guard at connection.py checks get_protocol() != 2 before attempting the handshake, so RESP2 skips it entirely. FalkorDB graph operations are RESP2-compatible and unaffected.
KuzuDB is deprecated and can't be installed on Python 3.14+. The repository was archived and can't/won't get updates to fix that, so let's KuzuDB deprecate as a runtime backend and implement a migration path for users running on KuzuDB. Add a legacy migration helper that detects old KuzuDB stores, exports them into a temporary CGC bundle, and imports that bundle into the backend the user selected. If no backend is configured, migration follows the resolved default backend. Document the Docker-based migration path for installing KuzuDB in an older temporary Python environment, and update docs so KuzuDB is described as migration-only. Add unit coverage for source discovery, missing Kuzu installs, non-empty target guards, bundle creation, row normalization, configured target selection, and the runtime backend deprecation path.
- Add factory-level migration tests for LadybugDB, FalkorDB, remote FalkorDB, Neo4j, and Nornic so legacy Kuzu data follows the resolved backend instead of an accidental hard-coded target. - Cover the FalkorDB-to-Ladybug fallback path so a broken embedded FalkorDB setup still migrates into the adjusted LadybugDB store path. - Cover the zero-config LadybugDB path after KuzuDB removal so the default replacement backend keeps migration behavior visible in tests. - Add `bundle merge` to the canonical CLI command matrix because the command exists in the source inventory and was missing from executable CLI coverage. - Enable `ALLOW_DB_DELETION` in the CLI test fixture so the stubbed delete command remains testable without changing production deletion safeguards.
|
@macunha1 is attempting to deploy a commit to the shashankss1205's projects Team on Vercel. A member of the Team first needs to authorize it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this is worth considering?
CGC currently treats KuzuDB as a normal runtime backend, but KuzuDB is deprecated: it was archived upstream and its Python package no longer installs cleanly on newer Python versions such as Python 3.14. As archived repos are read-only, we can't fix that. That turns Kuzu into an adoption blocker: a user can hit a packaging failure before they ever get to the value of CGC itself.
This exit path is, unfortunately, inevitable. The practical question is whether we make that path explicit and supported, or whether users discover it through broken installs. This PR proposes the cleaner route: keep KuzuDB data reachable through migration, but stop depending on KuzuDB as an active runtime backend.
The product story becomes cleaner for new users:
That direction lets us keep the "works locally, works with agents, works with teams" message without carrying an archived database dependency in the main install path.
What changed
This branch moves KuzuDB from "supported backend" to "deprecated legacy migration source":
falkordb,ladybugdb,falkordb-remote,neo4j, andnornic.Why this route
The alternative is to keep treating KuzuDB as an equal backend and try to work around its already limited state. That may buy short-term compatibility, but it leaves CGC tied to an archived upstream dependency and makes future Python support difficult. Since the deprecation pressure already exists, delaying KuzuDB migration does not avoid the exit.
This route keeps the useful part of KuzuDB support (protecting existing user data) while removing the part that creates ongoing install risk. It also makes the backend matrix easier to communicate:
That feels like the right product tradeoff: less dependency risk for new adoption, without leaving behind existing data and users.
User-facing impact
For new users, installation and setup should be more predictable because the default path no longer depends on an archived package. They will never have to worry about KuzuDB
For existing KuzuDB users, the recommended path is migration. CGC detects legacy KuzuDB stores, exports them through the bundle flow, and imports them into the configured supported backend when the target is empty. The docs also explain the Docker-based migration path for environments where KuzuDB only works under an older Python image. This makes the deprecation visible and gives users a controlled exit path before newer Python environments make that decision for them.
Validation
The branch adds and updates tests for:
Scope
Try and deprecate KuzuDB as a production runtime backend, with a narrow intent: acknowledge that KuzuDB was archived, won't be supported anymore, and consequently should also be deprecated in CGC's supported runtime surface. Reduce CGC installation and maintenance risk, and give existing KuzuDB data a clear exit path into supported backends.