# Database Schema Reference

## Overview

CleverAgents uses SQLAlchemy ORM models with SQLite as the default backend.
All tables are created via `Base.metadata.create_all` through the
`init_database()` helper in
`src/cleveragents/infrastructure/database/models.py`.

## Resource Registry Tables

The resource registry consists of three core tables introduced in Stage B1:

| Table              | Model                | Description                        |
|--------------------|----------------------|------------------------------------|
| `resource_types`   | `ResourceTypeModel`  | Schema-level resource type defs    |
| `resources`        | `ResourceModel`      | Registered resource instances      |
| `resource_edges`   | `ResourceEdgeModel`  | Parent-child DAG edges             |

### resource_types

Primary key: `name` (namespaced, e.g. `builtin/git-checkout`).
Stores kind (`physical`/`virtual`), handler references, JSON argument
schemas, allowed parent/child types, auto-discovery config, and
capabilities.

### resources

Primary key: `resource_id` (26-char ULID).
FK to `resource_types.name`. Stores optional namespaced name, location,
JSON properties/metadata, and content hash for equivalence tracking.

### resource_edges

Composite primary key: `(parent_id, child_id)`.
Both columns FK to `resources.resource_id` with `CASCADE` delete.
Stores `link_type` (`contains`, `references`, `derived_from`) and a
self-loop check constraint.

## Robot Migration Smoke Suite

A Robot Framework smoke suite validates that schema creation produces the
expected resource registry tables with correct columns.

### Running the suite

```bash
# Via nox (recommended — runs all Robot integration tests):
nox -s integration_tests

# Directly with robot:
robot --outputdir build/reports/robot robot/resource_registry_migration.robot
```

### Test cases

| Test Case                                        | What it checks                                   |
|--------------------------------------------------|--------------------------------------------------|
| Schema Creation Produces Resource Registry Tables | `resource_types`, `resources`, `resource_edges` exist |
| Resource Registry Tables Have Expected Columns   | Core columns present on each table               |
| Migration Is Idempotent                          | Calling `init_database` twice is safe            |

The helper script (`robot/helper_resource_registry_migration.py`) uses
`init_database()` with a temporary SQLite file and validates via
`sqlalchemy.inspect`.

## Behave BDD Tests

The Behave feature file `features/resource_registry_tables.feature`
contains comprehensive scenarios covering:

- Table existence after schema creation
- CRUD operations for `ResourceTypeModel`, `ResourceModel`, `ResourceEdgeModel`
- Constraint enforcement (uniqueness, FK, check constraints)
- ORM relationship navigation
- Migration smoke verification

Run Behave tests via:

```bash
nox -s unit_tests
```

## ASV Benchmarks

Performance benchmarks for resource registry operations live in
`benchmarks/resource_registry_migration_bench.py` and measure:

- Schema creation time
- Insert throughput for types, resources, and edges
- DAG query performance

Run benchmarks via:

```bash
nox -s benchmark
```