refactor(kuzu): Reflect KuzuDB deprecation and provide users with an exit route (migrating to another DB) - #1302
refactor(kuzu): Reflect KuzuDB deprecation and provide users with an exit route (migrating to another DB)#1302macunha1 wants to merge 7 commits into
Conversation
|
@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. |
|
👋 Thanks for contributing to CodeGraphContext! Since this PR was opened, |
|
Triage update: thank you for the thorough work here, @macunha1 — upstream KuzuDB's status is a real concern and this deserves a proper decision rather than a drive-by review. Flagging for @Shashankss1205: this PR proposes deprecating the Kùzu backend and giving users a migration path. Main currently still ships Kùzu as a first-class backend (with Ladybug as the successor lineage), so the call on direction needs to come from the project. Leaving open until that decision is made. |
…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.
- Modified config directory resolution to honor CGC_CONFIG_DIR and XDG_CONFIG_HOME, because MCP clients should not depend on the legacy ~/.codegraphcontext path. - Added separate data and cache roots so embedded databases and logs can live under XDG_DATA_HOME and XDG_CACHE_HOME. - Routed CLI configuration output to stderr so MCP startup logs do not compete with JSON-RPC stdout.
- Modified FalkorDB backend selection to fail loudly instead of falling back to LadybugDB, because an explicit local database choice should not create a second embedded store. - Updated service initialization so FalkorDB startup failures preserve the selected backend contract and surface the real worker error. - Fixed bundle import handling for LadybugDB internal IDs and properties so cross-backend migrations can load into FalkorDB without non-primitive property failures.
- restore explicit Kuzu backend selection - align tests after rebase - preserve upstream README during rebase
@Shashankss1205 done ✅ Rebased onto the latest
All good. Please let me know once the project direction is decided, or if you see the need for any more changes to the migration path or implementation in this PR. I can update it accordingly. |
- Constrain FastAPI, Starlette, and AnyIO so the workflow resolves a compatible TestClient stack across Python 3.12, 3.13, and 3.14. - Add the matching httpx dev dependency and make the test runner handle an unset PYTHONPATH without creating an empty import path.
|
Flagging this for a maintainer decision rather than reviewing it as a routine change. The PR is well-argued and the diff is coherent (24 files, mergeable, no conflicts). But it changes the product's supported-backend story — retiring KùzuDB as a runtime backend and providing a migration path — and that is a direction call for @Shashankss1205, not something to merge on technical correctness alone. The case you make is real and worth stating plainly for whoever decides:
Against it: KùzuDB is currently the zero-config default on Windows and the FalkorDB fallback, so this touches the default install path for a whole platform, and #1512 shows the simulator is already Kùzu/Ladybug-fragile in ways that would need to move with it. Two things that would help the decision regardless of outcome:
Holding rather than merging. |
|
Thanks for the very thorough write-up — the reasoning about carrying an archived upstream dependency is sound, and the migration guide plus Two things before this can land. 1. Three tests fail on a trial-merge onto (1140 pass.) The first two are expected fallout from the deprecation and just need updating to assert the new behaviour. The third points at something bigger — see below. 2. There's a second breaking change bundled in here that isn't in the PR description.
Today Beyond that, removing a documented backend is a product call rather than a code-review one, so I'm holding this for @Shashankss1205 to weigh in on the direction before merge — the implementation isn't the question here. Worth noting Please do fix the three tests in the meantime — that part is unambiguous. |
2 participants
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.