Getting Started
Tutorial: Building with CleaveDB
GUARD — Validation Rules
CleaveDB is a flexible document database, but production systems still require data integrity. The GUARD command establishes write-time validation rules enforced directly by the engine before writes enter the Write-Ahead Log.
Defining validation rules
Combine field requirements, numeric constraints, and enumeration checks using commas:
CleaveQLExample · Define guard rules
GUARD people WITH name IS REQUIRED, age >= 0, role IN ("admin", "user")Any subsequent write (via POUR or CHANGE) that violates these rules is immediately aborted with a detailed error.
Supported rule types
| Rule type | Canonical syntax | Description |
|---|---|---|
| Field presence | name IS REQUIRED | Field must exist and cannot be omitted |
| Field absence | nick IS NOT REQUIRED | Field is optional or explicitly disallowed |
| Comparison bounds | age >= 0 | Enforces numeric thresholds (supports >, <, >=, <=, =, !=) |
| Enumeration list | role IN ("admin", "user") | Value must match one of the listed strings |
| Data type assertion | age IS TYPE number | Enforces strict primitive type (e.g. number, string, boolean) |
Enforcement and error reporting
Violating operations fail cleanly without corrupting existing records:
CleaveQLExample · Missing required field error
-- Attempt to write document missing 'name':
POUR INTO people "p2" {"age": 5, "role": "user"}
-- Engine response:
-- Guard violation on 'people': 'name' is requiredSimilarly, out-of-bounds numbers are intercepted before commit:
CleaveQLExample · Numeric bound violation
-- Attempt to write invalid negative age:
POUR INTO people "p3" {"name": "Neg", "age": -1, "role": "user"}
-- Engine response:
-- Guard violation on 'people': 'age' must be >= 0