====== Relations & Dependencies ======

Relations are the core concept that makes CodeDB more than a simple editor. They let you define typed connections between files, creating a knowledge graph of your codebase.

===== What Are Relations? =====

A relation connects a **source file** to a **target file** with a **type**. For example:

  * ''app.js'' **imports** ''utils.js''
  * ''api.py'' **depends_on** ''database.py''
  * ''README.md'' **documents** ''main.go''
  * ''test_auth.py'' **tests** ''auth.py''

===== Adding Relations =====

There are several ways to add a relation:

=== From the Relations Panel ===

  - Open a file in the editor
  - Open the bottom panel (⌘J) and click the **Relations** tab
  - The panel shows two sections: **Dependencies** (outgoing) and **Links & Tags** (incoming)
  - Use the controls to add a new relation

=== From the Context Menu ===

  - Right-click a file in the sidebar
  - Select **Add Relation**
  - Choose the target file and relation type

=== From the Command Palette ===

  - Press **⌘R** to quickly add a relation from the current file

===== Relation Types =====

You can use any relation type string. Common types include:

  * ''imports'' — file imports or includes another
  * ''depends_on'' — file depends on another
  * ''extends'' — file extends or inherits from another
  * ''tests'' — test file for a source file
  * ''documents'' — documentation for a file
  * ''related_to'' — general association
  * ''calls'' — file calls functions from another
  * ''configures'' — configuration file for a module

===== Viewing Relations =====

The **Relations** panel at the bottom of the editor shows all connections for the active file:

  * **Dependencies** — files that the current file depends on (outgoing relations)
  * **Links & Tags** — files that depend on or link to the current file (incoming relations)

Each relation shows the connected file name, relation type, and can be clicked to navigate to that file.

===== Relation Metadata =====

Relations can store optional metadata as key-value pairs. This is useful for adding context like version constraints, notes, or categories to a relationship.

===== Database Schema =====

Relations are stored in the ''relations'' table:

<code sql>
CREATE TABLE relations (
  id INTEGER PRIMARY KEY,
  source_id INTEGER REFERENCES files(id),
  target_id INTEGER REFERENCES files(id),
  relation_type TEXT NOT NULL,
  metadata TEXT
);
</code>

You can query relations directly in the [[codedb:query-console|Query Console]].