# CRG SQLite Database Schema: Main Tables and Structure Explained

> Explore the CRG SQLite database schema main tables: nodes, edges, and metadata. Understand how code entities and relationships are stored in the tirth8205/code-review-graph repository.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: api-reference
- Published: 2026-08-08

---

**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`](https://github.com/tirth8205/code-review-graph/blob/main/sqlite.ts)

The extension validates the database structure before executing queries. In [`src/backend/sqlite.ts`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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:

```typescript
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.