feat(core): introduce GraphDB / QueryResult protocols for backend swap#17
Merged
Conversation
First step in the Kuzu -> DuckDB migration: a thin protocol layer
so future backends slot in without touching call sites.
What lands:
- codegraph/core/protocol.py: two runtime-checkable Protocols.
- QueryResult: has_next(), get_next(), get_column_names() — the
exact surface every caller in cgh uses today.
- GraphDB: execute(query, params) -> QueryResult, close().
Cypher today, SQL when DuckDB lands.
- codegraph/core/db_kuzu.py: KuzuGraphDB + KuzuQueryResult adapters.
Thin passthroughs. KuzuGraphDB.raw exposes the inner Connection so
Kuzu-specific helpers (federation, ...) keep working until the
swap finishes.
- codegraph/core/db.py: get_connection() and get_readonly_connection()
now return a GraphDB (concretely a KuzuGraphDB today). Singleton
caching unchanged. The raw kuzu.Database refs stay so
reset_connection() can still call close() explicitly — Kuzu's file
lock outlives the GC otherwise.
- tests/test_core/test_db_protocol.py: 7 tests pinning the contract.
Confirms KuzuGraphDB is a GraphDB at runtime, execute() returns a
QueryResult, params are forwarded, and the .raw escape hatch is in
place for the migration window.
Zero behaviour change: 235 (was) + 7 (new) = 242 tests green, all
MCP tools work, indexer works.
What this UNblocks (future PRs):
feature/duckdb-schema DuckDB DDL + DuckDBGraphDB behind CGH_DB env var
feature/duckdb-queries Port MCP tools one file at a time
feature/duckdb-federation ATTACH-based federation
release/0.5.0 Flip default to DuckDB, deprecate Kuzu
release/0.6.0 Remove Kuzu code + dependency entirely
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.
Summary
First PR in the Kuzu → DuckDB migration. Introduces `GraphDB` and `QueryResult` Protocols + a thin Kuzu adapter so future backends can slot in without touching call sites.
What lands
Zero behaviour change
What this unblocks