cleveragents-core/docs/reference/database_schema.md

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

# 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:

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:

nox -s benchmark