forked from cleveragents/cleveragents-core
98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
# 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
|
|
```
|