Where Is the Code Review Graph Data Stored? Understanding graph.db Locations and Configuration

The Code Review Graph stores its entire knowledge base in a SQLite database file named graph.db, typically located in a hidden .code-review-graph folder at the root of the repository being analyzed.

When working with the tirth8205/code-review-graph open-source tool, understanding exactly where your graph data persists is essential for CI/CD pipelines, backup strategies, and multi-environment deployments. The project utilizes a local SQLite database to store all nodes, edges, and metadata, with the GraphStore class managing file creation and connection handling. This guide explains the default storage locations, implementation details from the source code, and how to override paths programmatically or via CLI.

Default Storage Location

By default, the Code Review Graph creates a hidden directory named .code-review-graph at the root of your project. Inside this folder, the system maintains a single SQLite file called graph.db that contains the entire knowledge graph structure.

This location is determined when the GraphStore class is instantiated without an explicit path override. The engine automatically handles directory creation if it does not exist, ensuring the parent folders are prepared before establishing the database connection.

Implementation Details in graph.py

The storage mechanism is implemented in code_review_graph/graph.py, where the GraphStore class encapsulates all database operations.

Directory Creation Logic

When initializing a GraphStore instance, the constructor receives a db_path argument and ensures the parent directory structure exists:

self.db_path = Path(db_path)
self.db_path.parent.mkdir(parents=True, exist_ok=True)  # Creates .code-review-graph

This logic appears at lines 185–191 of code_review_graph/graph.py. The exist_ok=True parameter prevents errors if the .code-review-graph folder already exists from a previous run.

SQLite Connection Initialization

Immediately after directory preparation, the class establishes a connection to the SQLite file with specific concurrency and isolation settings:

self._conn = sqlite3.connect(str(self.db_path), timeout=30,
                             check_same_thread=False, isolation_level=None)

As implemented at lines 191–194, this connection remains open for the lifetime of the GraphStore object, handling all CRUD operations for nodes, edges, and metadata within that single graph.db file.

Customizing the Code Review Graph Storage Path

While the default location works for local development, you often need to specify alternative paths for testing, ephemeral CI environments, or centralized storage.

Command Line Interface Override

When using the CLI tool, you can override the default location using the --graph-db flag (or similar, depending on the exact CLI entry point definition). This allows you to place the database outside the repository root or on mounted volumes.

Programmatic Configuration

For Python scripts and test suites, pass an explicit path directly to the GraphStore constructor:

from pathlib import Path
from code_review_graph.graph import GraphStore

# Default location usage

default_db = Path(".code-review-graph") / "graph.db"
store = GraphStore(default_db)
print(store.get_all_files())
store.close()

This pattern creates the database in your current working directory under the hidden folder, matching the CLI behavior.

Temporary Storage for Testing

For unit tests or ephemeral analysis, instantiate GraphStore with a temporary path to avoid polluting the working directory:

from tempfile import TemporaryDirectory
from pathlib import Path
from code_review_graph.graph import GraphStore

with TemporaryDirectory() as tmpdir:
    custom_db = Path(tmpdir) / "test_graph.db"
    store = GraphStore(custom_db)
    
    # Your graph operations here...

    # store.upsert_node(node_info)

    
    store.close()

This approach is used throughout the project's test suite (see tests/test_graph.py) to ensure isolated test environments.

Accessing Raw SQLite Data

Advanced users can access the underlying SQLite connection for direct queries or debugging. The GraphStore exposes the connection object via store._conn:

store = GraphStore(".code-review-graph/graph.db")
conn = store._conn  # Direct SQLite connection

# Example: Count nodes by type

cursor = conn.execute(
    "SELECT kind, COUNT(*) AS cnt FROM nodes GROUP BY kind"
)
for row in cursor:
    print(f"{row['kind']}: {row['cnt']}")

store.close()

Warning: While read operations are safe, direct write operations bypass the GraphStore abstraction and may corrupt the graph schema or violate constraints defined in code_review_graph/migrations.py.

Schema Evolution and Migration

The graph.db file structure evolves with the codebase. The project includes a code_review_graph/migrations.py module that handles schema updates when the tool version changes. This ensures that existing graph.db files are upgraded automatically rather than requiring manual recreation.

Summary

• Primary Location: The Code Review Graph data is stored in a SQLite file named graph.db inside a hidden .code-review-graph directory at the repository root.
• Implementation: The GraphStore class in code_review_graph/graph.py manages directory creation (lines 185–191) and SQLite connections (lines 191–194).
• Customization: Override the default path via the --graph-db CLI flag or by passing a custom Path to the GraphStore constructor.
• Portability: The entire graph exists in a single file, making it easy to backup, version, or transfer between environments.

Frequently Asked Questions

Can I move the graph.db file to a different location after creation?

Yes, you can move the graph.db file to any location on your filesystem. Simply pass the new path to GraphStore or the CLI tool when initializing. The database is self-contained and does not rely on absolute paths stored internally. However, ensure the file is not being accessed by another process during the move to prevent corruption.

Is the SQLite database safe for concurrent access?

The GraphStore initializes the connection with check_same_thread=False and timeout=30, which allows some concurrency flexibility. However, SQLite handles concurrent writes by locking the entire database file. For high-concurrency scenarios (multiple CI runners writing to the same file), consider using separate database files per job or implementing a file-locking mechanism to prevent "database is locked" errors.

How do I backup the Code Review Graph data?

Since all data resides in a single graph.db file, simply copy that file to your backup destination. For the default location, run:

cp .code-review-graph/graph.db /path/to/backup/graph-$(date +%Y%m%d).db

The file is portable across platforms and SQLite versions, though you should ensure your backup tool preserves file permissions and handles the file as binary data.

What happens if the .code-review-graph directory is deleted?

If the directory or graph.db file is deleted, the GraphStore class will recreate the directory structure and initialize a fresh, empty database on the next run (lines 185–191 of graph.py). You will need to re-analyze your codebase to repopulate the graph, as the knowledge base does not persist elsewhere by default.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}