CRG SQLite Database Schema: Main Tables and Structure Explained

The CRG SQLite database schema consists of three core tables—nodes, edges, and metadata—that store code entities, their relationships, and database versioning information.

The Code Review Graph (CRG) represents your codebase as a directed graph stored in a SQLite database. In the tirth8205/code-review-graph repository, this schema enables the VS Code extension to perform impact analysis and navigate code relationships efficiently. Understanding the CRG SQLite database schema is essential for querying code structure and extending the tool's functionality.

Core Tables in the CRG SQLite Database Schema

The database centers on three primary tables that define the graph structure, plus an optional fourth for advanced features.

The nodes Table

The nodes table stores every graph entity, including files, classes, functions, and tests. Key columns include id, kind, name, qualified_name, file_path, line_start, line_end, language, and is_test. This table serves as the canonical registry of all code entities in your project.

The edges Table

The edges table captures directed relationships between nodes, such as function calls, imports, and inheritance chains. Critical columns include id, kind, source_qualified, target_qualified, file_path, and line. Each row represents a dependency or interaction from one code entity to another.

The metadata Table

An optional but recommended table, metadata stores key-value pairs describing the database itself. It typically contains the schema_version and last_update timestamps. The extension uses this table to verify compatibility between the database and the VS Code extension code.

The embeddings Table (Optional)

When vector embeddings are generated for semantic code search, the embeddings table appears in the schema. However, this table is not required for basic operation and is only present when AI-powered features are enabled.

Schema Validation in sqlite.ts

The extension validates the database structure before executing queries. In src/backend/sqlite.ts, the checkSchemaCompatibility() method (lines 1998-2005) asserts the existence of the nodes and edges tables and reads the metadata table to confirm the schema version. This validation prevents runtime errors when opening databases generated by incompatible versions of the Python backend.

Querying the Database with SqliteReader

The SqliteReader class in src/backend/sqlite.ts provides the primary interface for interacting with the CRG SQLite database schema. The following TypeScript examples demonstrate how to query the core tables:

import { SqliteReader } from '@/backend/sqlite';

// Open the CRG database (read-only)
const reader = await SqliteReader.create('/path/to/crg.db');

// 1️⃣ List all files (nodes of kind 'File')
const files = reader.getAllFiles();
console.log('Files in project:', files);

// 2️⃣ Retrieve a node by its qualified name
const node = reader.getNode('src/components/Button.tsx');
console.log('Node details:', node);

// 3️⃣ List outgoing edges from a node
const outgoing = reader.getEdgesBySource('src/components/Button.tsx');
console.log('Outgoing edges:', outgoing);

// 4️⃣ Get overall graph statistics (node/edge counts, languages, etc.)
const stats = reader.getStats();
console.log('Graph stats:', stats);

// 5️⃣ Query the optional metadata table
const schemaVersion = reader.getMetadata('schema_version');
console.log('Schema version:', schemaVersion);

The getStats() method (lines 3560-3646) aggregates data from the nodes and edges tables, optionally including the embeddings table when calculating database statistics. Helper methods like getAllFiles(), getNode(), and getEdgesBySource() (lines 555-720) provide targeted access to specific graph elements.

Testing the Schema

Unit tests in test/sqlite.test.ts create temporary databases with the complete schema—including nodes, edges, and metadata tables—to verify the SqliteReader behavior. These tests ensure that schema compatibility checks and query methods function correctly across different database states.

Summary

• The CRG SQLite database schema relies on three core tables: nodes for code entities, edges for relationships, and metadata for versioning.
• The nodes table stores files, classes, functions, and tests with detailed location and language information.
• The edges table maps directed relationships using qualified names to connect source and target entities.
• Schema validation occurs in checkSchemaCompatibility() within src/backend/sqlite.ts to ensure database compatibility.
• The SqliteReader class provides methods like getAllFiles(), getNode(), and getEdgesBySource() to query the graph structure efficiently.

Frequently Asked Questions

What is the primary purpose of the nodes table in the CRG SQLite database schema?

The nodes table serves as the registry for all code entities in your project, storing files, classes, functions, and tests with their qualified names, file paths, and line numbers. It enables the extension to locate specific code elements and display their metadata within the VS Code interface.

How does the extension validate the CRG database schema before use?

The SqliteReader class calls checkSchemaCompatibility() (lines 1998-2005 in src/backend/sqlite.ts) to verify that the nodes and edges tables exist and checks the metadata table for a compatible schema version. This prevents the extension from attempting to query databases created by incompatible backend versions.

Can the CRG database function without the metadata table?

Yes, the metadata table is optional for basic operation, though it is recommended for tracking schema versions and update timestamps. The core functionality depends only on the nodes and edges tables, while metadata provides additional administrative information used during compatibility checks.

What information does the edges table store about code relationships?

The edges table stores directed relationships between entities using source_qualified and target_qualified columns to reference node identifiers, along with the relationship kind (such as calls or imports), file_path, and line numbers. This structure enables dependency tracking and impact analysis across the codebase.

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