Crate valence

Expand description

Valence is a schema-driven ORM for Rust: declare typed tables with valence_schema!, generate Model CRUD at build time, and wire storage through Valence::builder without locking into one database.

Typed schemas and models with composable storage adapters.

§Features

Schema DSL — fields, connections, policies, ownership, TTL, and trait mixins (valence_schema!, valence_trait_schema!)
Table TTL — declare ttl: { seconds } on a schema; call Valence::ensure_ttl_for_all once at boot (ttl module: native Redis/Mongo, Deferred stamp + warn otherwise)
Build-time codegen — typed models from host schemas/ via valence-codegen
Composable backends — in-memory, SQLite, IndraDB, SurrealDB, Postgres, MongoDB, Redis
Multi-backend routing — one DatabaseRouter; each schema picks a backend with database: / DatabaseFromEngine
Host ports — secrets, actor identity, endpoints, and telemetry injected at boot
Privacy-aware CRUD — policy and ownership hooks on generated Model paths; field privacy via PrivacyEvaluator::filter_entity_fields on Model::get and query rows
Queued delete — Model::delete authorizes Delete on every CascadeDelete DAG node (check_dag_delete_privacy) before queueing; Read is not required. SetNull / RemoveEdge clear under the requester via deletion-scoped merge_record / unrelate_edge. Host workers restore the deleting actor and run schema side_effects on physical CascadeDelete.
Query privacy — QueryCore::execute / Model::query post-filter rows by entity read policy and field policies
Default-deny policies — schemas without entity policies: deny non-System actors
Query paging clamps — MAX_QUERY_LIMIT / MAX_QUERY_OFFSET on QueryCore
Dual-key privacy bypass — bench/test only: VALENCE_PRIVACY_BYPASS + VALENCE_PRIVACY_BYPASS_FORCE_ON (never in production; see repository SECURITY.md)
Actor JSON policy — optional RejectExternalSystemActor on factory builds

Enable backends with Cargo features (mem is the default). The crate README.md lists every feature flag and environment variable. See repository SECURITY.md for integrator wiring.

§Topologies

Valence is an in-process ORM: one host process owns Valence / DatabaseRouter. There is no coordinator/worker daemon split.

§Embedded (one process)

Engine runs in-process (mem, sqlite, indradb, Surreal embedded). No external database required for the canonical path.

§Remote (wire)

The host process is a client to an external database (Postgres, MongoDB, Redis, Surreal remote). Start the service, set the URL env var, then run one example process.

Runnable catalog: examples/README.md (walkthrough ladder) and crate README.md.

§Getting started

Follow these steps in order. Each linked API page includes details for that task.

§1. Choose and wire storage

Backend	Type	Feature	Topology	When to use
In-memory	`InMemoryBackend`	`mem` (default)	embedded	Local experiments; tests
SQLite	`SqliteBackend`	`sqlite`	embedded	Durable single-host store
IndraDB	`IndradbBackend`	`indradb`	embedded	Graph-oriented workloads
SurrealDB	`SurrealEmbeddedBackend`	`surreal`	embedded	Surreal engine in-process
Postgres	`PostgresBackend`	`postgres`	remote	Wire Postgres (`DATABASE_URL`)
MongoDB	`MongoBackend`	`mongodb`	remote	Wire Mongo (`VALENCE_MONGODB_URI`)
Redis	`RedisBackend`	`redis`	remote	Wire Redis (`VALENCE_REDIS_URL`)

§Select a backend in the schema

A schema does not contain a backend instance. Its database: field points to a stable DatabaseFromEngine evaluator. The evaluator combines:

a logical name (for example "default") that must match ValenceBuilder::add_backend, and
an engine ID exported by the selected adapter.

Define COUNTER_DB for the backend you enable:

Backend	`COUNTER_DB` declaration
In-memory	`Database::from_engine("default", MEM_ENGINE_ID)`
SQLite	`Database::from_engine("default", SQLITE_ENGINE_ID)`
IndraDB	`Database::from_engine("default", INDRADB_ENGINE_ID)`
SurrealDB	`Database::from_engine("default", SURREAL_ENGINE_ID)`
Postgres	`Database::from_engine("default", POSTGRES_ENGINE_ID)`
MongoDB	`Database::from_engine("default", MONGODB_ENGINE_ID)`
Redis	`Database::from_engine("default", REDIS_ENGINE_ID)`

Then use that evaluator in the same Counter schema:

use valence::{Database, DatabaseFromEngine, FieldType, valence_schema};

// Choose the engine constant for the enabled backend.
pub const COUNTER_DB: DatabaseFromEngine =
    Database::from_engine("default", valence::MEM_ENGINE_ID);

valence_schema! {
    Counter {
        table: "counter",
        version: "0.1.0",
        description: "Simple counter",
        database: COUNTER_DB,
        fields: [
            id: { r#type: FieldType::String, primary_key: true, required: true },
            value: { r#type: FieldType::Integer, required: true },
        ],
    }
}

Omitting database: selects DEFAULT_IN_MEMORY ("default" + MEM_ENGINE_ID). If that router key is absent, the current runtime falls back to its active/default backend. Declare database: explicitly for clear behavior and for any runtime with multiple backends.

In-memory first run:

use std::sync::Arc;
use valence::{
    Database, DatabaseFromEngine, FieldType, InMemoryBackend, Valence, MEM_ENGINE_ID,
    valence_schema,
};

const COUNTER_DB: DatabaseFromEngine =
    Database::from_engine("default", MEM_ENGINE_ID);

valence_schema! {
    Counter {
        table: "counter",
        version: "0.1.0",
        database: COUNTER_DB,
        fields: [
            id: { r#type: FieldType::String, primary_key: true, required: true },
            value: { r#type: FieldType::Integer, required: true },
        ],
    }
}

let valence = Valence::builder()
    .add_backend("default", Arc::new(InMemoryBackend::new()))
    .build()?;
assert_eq!(valence.backend_for_table("counter")?.engine_id(), MEM_ENGINE_ID);

Runnable: cargo run -p uf-valence --example quickstart --features mem

§2. Declare schemas

Schemas are the typed contracts Valence registers and (via codegen) turns into models.

use valence::{
    Database, DatabaseFromEngine, FieldType, MEM_ENGINE_ID, valence_schema,
};

const COUNTER_DB: DatabaseFromEngine =
    Database::from_engine("default", MEM_ENGINE_ID);

valence_schema! {
    Counter {
        table: "counter",
        version: "0.1.0",
        description: "Simple counter",
        database: COUNTER_DB,
        fields: [
            id: { r#type: FieldType::String, primary_key: true, required: true },
            value: { r#type: FieldType::Integer, required: true },
        ],
    }
}

Replace MEM_ENGINE_ID with the engine constant from the table in step 1 when the Counter belongs on another backend.

See valence_schema! and valence_trait_schema! for the DSL field reference. Minimal schema example: workspace examples/minimal-schema. Macros and valence-codegen share one syn DSL parser (valence-schema-dsl), so host schemas/*_valence_schema.rs files accept the same syntax and semantics (including database: evaluators).

§Declare and ensure TTL

Add ttl: { seconds: N } on a table schema (create-only clock). After backends are registered, call Valence::ensure_ttl_for_all once — it scrapes the schema registry for every TTL table (no hand list). See the ttl module for capabilities, the reserved ttl::EXPIRE_AT_FIELD, and Deferred/non-native warnings. Hosts wire valence_platform::ttl_sweep::register_ttl_service so Deferred engines delete expired rows.

§3. Set up build-time codegen

Typed Model impls are generated at compile time from schema files under schemas/ (for example widget_valence_schema.rs). Add a build dependency and a one-line build.rs:

[dependencies]
uf-valence = { git = "https://github.com/deathbreakfast/valence", package = "uf-valence", features = ["mem"] }

[build-dependencies]
uf-valence-codegen = { git = "https://github.com/deathbreakfast/valence", package = "uf-valence-codegen" }

// build.rs
fn main() {
    valence_codegen::build().expect("valence codegen failed");
}

Include generated models (this is what must be linked for typed CRUD and inventory):

valence::include_generated_models!();

Schema files under schemas/ are scan inputs for codegen; they are not mod-linked. End-to-end proof: workspace examples/codegen-host and examples/product-model-host. See the valence-codegen crate docs for custom roots via build_with / CodegenConfig.

§4. Use generated models (CRUD)

After codegen, call Model methods with a Valence runtime:

use valence::Model;

// Widget is generated from schemas/widget_valence_schema.rs
let created = Widget::create(widget, &valence).await?;
let loaded = Widget::get(created.id(), &valence).await?;
Widget::update(created.id(), updated, &valence).await?;
Widget::delete(created.id(), &valence).await?;

Product-shaped schemas and connections: examples/product-model-host.

§5. Route multiple backends

One Valence holds a heterogeneous DatabaseRouter. Schema database: evaluators pick the router key per table.

use std::sync::Arc;
use valence::{InMemoryBackend, Valence, router_key, MEM_ENGINE_ID};

let primary = router_key("primary", MEM_ENGINE_ID);
let valence = Valence::builder()
    .add_backend("primary", Arc::new(InMemoryBackend::new()))
    .add_backend("archive", Arc::new(InMemoryBackend::new()))
    .default_backend_key(primary)
    .build()?;

Runnable: cargo run -p uf-valence --example multi_backend --features mem

Heterogeneous engines (mem Project ↔ sqlite Task) with hop + query: cargo run -p cross-backend-model-host. Walkthrough: examples/README.md.

§6. Inject host ports

Optional builder methods wire secrets, actor identity, endpoints, and telemetry: ValenceBuilder::secret_provider, ValenceBuilder::actor_factory, ValenceBuilder::endpoint_resolver, ValenceBuilder::telemetry_sink.

Port table and reference impls: valence_core::ports. Storage adapter contract and third-party checklist: DatabaseBackend. Router semantics: DatabaseRouter.

use std::sync::Arc;
use valence::{
    ConsoleSink, EnvSecretProvider, InMemoryBackend, JsonActorFactory, NoopEndpointResolver,
    Valence,
};

let _valence = Valence::builder()
    .add_backend("default", Arc::new(InMemoryBackend::new()))
    .secret_provider(Arc::new(EnvSecretProvider))
    .actor_factory(Arc::new(JsonActorFactory))
    .endpoint_resolver(Arc::new(NoopEndpointResolver))
    .telemetry_sink(Arc::new(ConsoleSink))
    .build()?;

§How the pieces link together

schemas/*.rs ──► build.rs (valence_codegen::build) ──► $OUT_DIR/generated_models.rs
  (scan inputs)                                              │
                                                             │ include_generated_models!
                                                             ▼
                                             impl Model + inventory submit
                                                             │
                             SchemaRegistry ◄────────────────┤
                                                             ▼
                                             typed CRUD on Valence
                                                             │
                             Valence runtime ◄── DatabaseRouter / backends

Dependency rules: valence-core owns ports and runtime (no engine SDK); valence-backend-* advertise open ENGINE_IDs; the public crate re-exports behind features; apps own schema roots and call valence-codegen from build.rs; one operation stays on one backend; host adapters inject at boot.

§Next steps

Task	Start here
Example walkthrough	`examples/README.md`
Schema DSL fields	`valence_schema!`, `valence_trait_schema!`
Build-time codegen	valence-codegen, `examples/codegen-host`
Wire storage	`Valence::builder()`, `InMemoryBackend`
Model CRUD	`Model`, `examples/product-model-host`
Multi-backend routing	`DatabaseRouter`, `multi_backend` example
Cross-backend hop + query	`examples/cross-backend-model-host`
Hybrid multi-logical	`hybrid_multi_logical` example (`hybrid,mem`)
Custom adapter	`DatabaseBackend`, `examples/acme-valence-backend-stub`
Surreal inventory bootstrap	`examples/embedded-bootstrap`
SQLite	`SqliteBackend`, `quickstart_sqlite` example
IndraDB	`IndradbBackend`, `quickstart_indradb` example
Surreal embedded	`SurrealEmbeddedBackend`, `surreal_embedded` example
Postgres	`PostgresBackend`, `quickstart_postgres` (env-gated)
MongoDB	`MongoBackend`, `quickstart_mongodb` (env-gated)
Redis	`RedisBackend`, `quickstart_redis` (env-gated)
Admin runtime	`SchemaRegistry`, `QueryCore`, `examples/admin-runtime-host`
Config / env vars	crate `README.md`
How to run examples	`examples/README.md`

§Entry points

prelude — ergonomic schema authoring imports
Valence / ValenceBuilder — runtime assembly
valence_schema! — schema DSL macro
Model — generated CRUD surface
DatabaseBackend / DatabaseRouter — storage ports

§Prerequisites and gotchas

Enable backend features explicitly (mem is on by default).
Product schemas and codegen roots belong in your application.
Wire adapters (postgres/mongodb/redis) need live URLs; examples skip cleanly when unset.
SurrealDB support lives in valence-backend-surreal (feature surreal), not in core ports.
Generated models (or macro-expanded schemas) must be linked into the binary or inventory will not see them.

§Runnable examples

Walkthrough ladder: examples/README.md — quickstarts, workspace hosts, and testkit hop fixtures in order.

Canonical path (see crate README How to run examples):

cargo run -p uf-valence --example quickstart --features mem
cargo run -p uf-valence --example quickstart_sqlite --features sqlite
cargo run -p uf-valence --example multi_backend --features mem
cargo test -p codegen-host
cargo run -p cross-backend-model-host

Example	Features	Notes
`quickstart`	`mem`	Schema + mem boot + registry proof
`quickstart_sqlite`	`sqlite`	Embedded SQLite
`multi_backend`	`mem`	Multiple logical backends
`hybrid_multi_logical`	`hybrid,mem`	Hybrid primary, several logical names
`surreal_embedded`	`surreal`	Surreal mem engine
`quickstart_indradb`	`indradb`	Embedded IndraDB
`quickstart_postgres`	`postgres`	Requires `DATABASE_URL`
`quickstart_mongodb`	`mongodb`	Requires `VALENCE_MONGODB_URI`
`quickstart_redis`	`redis`	Requires `VALENCE_REDIS_URL`
`quickstart_telemetry`	`mem,telemetry-console`	Console telemetry sink

Workspace hosts (see examples/README.md): minimal-schema, codegen-host, product-model-host, cross-backend-model-host, admin-runtime-host, embedded-bootstrap, acme-valence-backend-stub. Hop crates (hop-pair-model-host, hop-chain-model-host) are testkit/matrix fixtures only.

Modules§

actor: Actor identity for privacy checks and audit trails.
actor_policy: Optional policy for validating opaque actor_json at factory build time.
admin_entity_delete: Table-keyed queued delete for admin tooling.
backend: Pluggable database backends for Valence.
batch: Batch create hooks for codegen BatchCreatable impls (full batch runtime is host-owned).
compiled_query: Parameterized statement for crate::backend::DatabaseBackend::execute_compiled_query.
compiled_query_factory: Dialect-specific compiled queries for deletion DAG and ownership helpers.
connection: Connection cardinality, delete semantics, and id helpers for generated models.
currency: Monetary amount with an ISO-4217 CurrencyCode.
database_retry: Retry database operations when the engine reports retryable transaction contention.
datetime_unix: Persist chrono::DateTime<Utc> as signed UTC unix seconds.
deletion: Cascading delete orchestration — dispatch hooks and DAG planning.
entity: Privacy-filtered entity view for admin tooling.
error: Error types for Valence routing and backends.
evaluator: Runtime resolution of which crate::backend::DatabaseBackend a schema uses.
instrumentation: Instrumentation hooks for Valence runtime metrics and events.
inventory: github crates-io docs-rs
iter: Row-level iter descriptor types for valence_schema! { iters: [...] }.
json_as: Serde helpers for FieldType::JsonAs fields.
known_engines: Stable engine id slugs for first-party reference adapters.
model: Model contracts generated from schema DSL.
owner_ref: Stable owner identity for row-level ownership metadata.
ownership: First-class data ownership (platform tables + hooks from generated CRUD).
ports: Host-injectable ports (secrets, identity, endpoints).
prelude: Ergonomic imports for schema authoring and generated models.
privacy: Schema-driven privacy for entity and field access.
privacy_policies: Re-export built-in privacy policy constants for schema authors.
query: Composable query builder — filters, sorts, compiled execution.
query_compiler: Query compilation from crate::query::QueryCore to crate::compiled_query::CompiledQuery.
query_compiler_registry: Registry mapping DatabaseBackend::engine_id to query compilers.
read_cache: Valence-wide read-through LRU for Model::get-shaped point reads.
record_id: Backend-agnostic record identifier (table + id).
redact: Redact credentials from connection endpoints and error text.
reference: Reference placeholders for batch entity creation.
register_logical: Multi-logical registration of a shared DatabaseBackend on a DatabaseRouter.
registry: Generic string-keyed registry (inventory + HashMap, no quark dependency).
request_cache: Request-scoped permission check cache (shared via Arc on cloned Valence handles).
router: Named backend registry (heterogeneous engines per router).
router_key: Compound router keys: "{engine_id}:{logical_name}".
row_json: JSON row helpers shared by query fetch paths.
runtime: Valence runtime handle and builder.
safe_ident: Charset validation for SQL/Surreal identifiers interpolated into queries.
schema: Schema metadata registration hooks for valence_schema!.
schema_api: Structured schema metadata produced by the Valence DSL.
schema_types: DSL type vocabulary used by valence_schema! and valence_trait_schema!.
side_effect: Side effect types for post-mutation hooks.
storage_layout: Schema-driven physical storage layout and dialect DDL export.
trait_registry: Runtime trait metadata registry.
trait_schema: Trait schema metadata for valence_trait_schema!.
ttl: Table-level TTL policy, stamp helpers, and ensure entry points. Table-level TTL: schema policy, create-time stamping, and ensure APIs.
validation: Field validation framework

Macros§

include_generated_models: Include $OUT_DIR/generated_models.rs produced by valence_codegen::build.
valence_schema: Defines a Valence model schema at compile time.
valence_trait_schema: Defines a reusable trait schema (fields, optional connections, optional policies).

Structs§

BackendCapabilities: Capabilities advertised by a storage adapter (telemetry labels and contract tests).
CachePolicy: Resolved cache policy used on hot paths (built once at crate::HybridBackendBuilder::build).
CacheRules: Whether tables are cached by default, plus include/exclude overrides.
CompiledQuery
ConsoleSink: Writes telemetry to stderr (development and bench).
Currency: Composite money value: ISO code + signed minor units.
Database: Convenience namespace for built-in evaluators.
DatabaseFromEngine: Built-in evaluator: look up logical_name + engine_id on a DatabaseRouter.
DatabaseRouter: Maps compound router keys to concrete DatabaseBackend implementations.
DeleteSideEffectDescriptor: One registered delete side-effect dispatcher for a table (submitted by codegen).
DeletionRequest: Payload passed to the registered deletion dispatcher (typically starts a host job orchestrator).
DeletionService
EnvEndpointResolver: Resolve physical database URLs from env at bootstrap.
EnvSecretProvider: Read secrets from process environment variables (key = env var name).
FieldChange
ForeignKeyRef: Normalized foreign-key/reference metadata for a field.
HopSource: A previous query in the hop chain. Compiled at execution time.
HybridBackend: Postgres/SQL primary with an embedded IndraDB read-through cache for records and edges.
HybridBackendBuilder: Fluent builder for HybridBackend.
IdOnlyRecord: Minimal record containing only the ID field.
InMemoryBackend: In-memory DatabaseBackend storing rows and graph edges in process memory.
IndraQueryCompiler: Compiles QueryCore to parameterized SQL (document-row subset) for IndraDB.
IndradbBackend: Embedded IndraDB DatabaseBackend mapping Valence tables to vertex types.
InstrumentedBackend: Wraps an inner backend and emits instrumentation telemetry on every I/O call.
IterDescriptor: One registered iter implementation for a table (submitted by valence_schema!).
IterEvaluation: Result of an iter should_run hook.
JsonActorContext: ActorContext that stores JSON as-is.
JsonActorFactory: Reference factory that wraps JSON in JsonActorContext.
KnownEngines: Well-known DatabaseBackend::engine_id values shipped with this workspace.
LayoutDiff: Result of comparing desired layout to live physical layout.
LayoutField: One physical field in a typed table layout.
MongoBackend: MongoDB-backed DatabaseBackend storing JSON documents per collection.
MongoQueryCompiler: Compiles QueryCore for the MongoDB adapter.
Mutation
MutationTimer: Timer for mutation wall time (L1).
NoOpSecretProvider: Always returns Ok(None) — default when no provider is configured.
NoOpSink: Discards all telemetry (default for tests and minimal hosts).
NoopEndpointResolver: Always returns Ok(None).
OwnerRef: Resolved owner for a row (stored in ownership tables at the host layer).
OwnershipConfig: Ownership behavior declared in schema DSL (ownership: { ... }).
OwnershipService: Ownership persistence and transfer helpers.
ParseCurrencyCodeError: Unknown or non-canonical currency code string.
PostgresBackend: Postgres-backed DatabaseBackend using typed columns (JSONB cells for Json fields).
PrivacyError: Error returned when a privacy rule blocks field access.
PrivacyEvaluator: Privacy evaluation engine
PrivacyRule: A single privacy rule
QueryCompilerRegistry: Resolves a QueryCompiler for a storage engine slug.
QueryCore: Core query builder that compiles per registered engine.
RecordId
RecordedCounter: Captured counter increment.
RecordedEvent: Captured structured log event.
RecordedGauge: Captured gauge sample.
RecordingSink: Append-only in-memory sink for assertions in unit and integration tests.
RedisBackend: Redis-backed DatabaseBackend storing one Hash per record (field → JSON cell).
RedisQueryCompiler: Compiles QueryCore for the Redis adapter.
Reference
ReferencedEntity
RegisterBackendLogicalNamesOptions: Options for multi-logical backend registration.
RegisterEmbeddedLogicalNamesOptions: Options for embedded logical name registration.
RejectExternalSystemActor: Rejects well-known System-shaped actors on ActorTrust::External paths.
RequestPermissionCache: Memoizes permission name lookups for one HTTP/server-fn request.
ResolverContext
RouterValenceFactory: ValenceFactory backed by a shared DatabaseRouter.
RouterValenceFactoryConfig: Host wiring template applied when building from a shared router.
Schema: Complete runtime schema produced from valence_schema!.
SchemaConnection: Connection/relationship definition from schema DSL.
SchemaConnectionsOverlayInit: Codegen-submitted trait-merged connections for deletion graph and tooling.
SchemaEdge: Edge/relationship definition retained for older schema shapes.
SchemaField: Expanded metadata for one field declared in fields: [...].
SchemaMeta: Schema metadata summary block.
SchemaMetadataInit: Lazy initializer submitted via inventory::submit!.
SchemaPolicies: Full entity-level policy declaration for the schema.
SchemaPolicyRule: One policy rule reference stored in schema metadata.
SchemaPolicyRules: Policy rule buckets for a single CRUD operation.
SchemaPrivacy: Top-level privacy summary for a schema.
SchemaRegistry: Owned registry for schema metadata.
SchemaTtlPolicy: Table-level time-to-live policy from the schema DSL (ttl: { seconds, mode }).
SqlQueryCompiler: Compiles QueryCore to parameterized SQL.
SqliteBackend: SQLite-backed DatabaseBackend using typed columns from schema layout.
StaticEndpointResolver: In-memory map of logical name → URL.
StorageLayout: Physical layout for one table, derived from schema metadata.
SurrealEmbeddedBackend: Wraps a local Surreal handle (memory, RocksDB, etc.).
SurrealQueryCompiler: Compiles QueryCore to parameterized SurrealQL.
SurrealRemoteBackend: Wraps a remote-capable Surreal<Any> client (WebSocket / HTTP / …).
TraitDefinition: Runtime metadata for a single Valence trait definition.
TraitDefinitionInit: Lazy initializer for trait definitions.
TraitFieldDef: Minimal field descriptor stored in trait definitions.
TraitImplementor: Links a concrete table to the trait it implements.
TraitPolicies: Entity-level privacy policies declared by a trait.
TraitPolicyRules: Policy rule names for a single CRUD operation bucket.
TraitRegistry
Valence: Host-assembled Valence handle.
ValenceBuilder: Builder for constructing a Valence runtime.
ValenceEntity

Enums§

Actor: Who or what is performing a Valence operation.
ActorTrust: Trust level for an actor JSON call site.
AdditiveOp: One additive change to apply during sync.
BackendTtlCapability: Whether a storage adapter can enforce schema TTL natively.
Cardinality
CurrencyCode: ISO 4217 alphabetic currency code.
CurrencyError: Same-currency arithmetic / conversion failure.
DateTimePredicate: Predicate for datetime fields.
EmbeddedEngine: Embedded Surreal engine selection.
Error
FieldOperation: Field access direction for privacy checks.
FieldStorage: Physical storage kind for one field (engine-agnostic).
FieldType: Field data types accepted by the Valence DSL.
HopType: Describes how a hop connects a source query to a target query.
IntPredicate: Predicate for integer fields.
JsonAsSerdeError: How FieldType::JsonAs handles serde failures on the model boundary.
MutationKind
NullPredicate: Predicate for checking null/not-null on optional fields.
OnDelete
OwnerKind: Kind of principal that owns a row.
PrivacyOperation: Which CRUD operation is being checked.
RecordPredicate: Predicate for record-link fields (stored as Surreal RecordId).
Role: Role markers used by older privacy/mutation DSL shapes.
SortDirection: Sort direction for ordering query results.
SqlColumnType: SQLite / Postgres column type fragment.
StringPredicate: Predicate for string/text fields.
SurrealFieldType: Surreal DEFINE FIELD type fragment.
Validator: Built-in validators attachable to schema or trait fields.

Constants§

DEFAULT_EMBEDDED_SURREAL_LOGICAL_NAMES: Include in bootstrap registration so schemas that omit explicit database: still resolve.
DEFAULT_IN_MEMORY
DEFAULT_IN_MEMORY_ROUTER_KEY: Router key for default in-memory backend (inmemory_mem:default).
EXPIRE_AT_FIELD: Reserved document field holding RFC3339 UTC expire time (create-only).
HYBRID_ENGINE_ID: Stable engine slug for router keys (hybrid_indra_sql:logical_name).
HYBRID_PRIMARY: Schema evaluator const for database: routing (primary is the logical name in the key).
INDRADB_ENGINE_ID: Stable engine slug for router keys (indradb:logical_name).
INDRADB_PRIMARY: Schema evaluator const for database: routing.
MAX_QUERY_LIMIT: Maximum rows a single QueryCore::execute may return.
MAX_QUERY_OFFSET: Maximum query offset accepted by QueryCore.
MEM_ENGINE_ID: Stable engine slug for router keys (inmemory_mem:logical_name).
MONGODB_ENGINE_ID: Stable engine slug for router keys (mongodb:logical_name).
MONGODB_PRIMARY: Schema evaluator const for database: routing.
POSTGRES_ENGINE_ID: Stable engine slug for router keys (postgres:logical_name).
POSTGRES_PRIMARY: Schema evaluator const for database: routing.
PRIVACY_BYPASS_ENV: Env var requesting privacy bypass (1 to request).
PRIVACY_BYPASS_FORCE_ON_ENV: Second key required with PRIVACY_BYPASS_ENV before bypass is honored.
REDIS_ENGINE_ID: Stable engine slug for router keys (redis:logical_name).
REDIS_PRIMARY: Schema evaluator const for database: routing.
SQLITE_ENGINE_ID: Stable engine slug for router keys (sqlite:logical_name).
SQLITE_PRIMARY: Schema evaluator const for database: routing.
SURREAL_ENGINE_ID: Stable engine slug for router keys (surrealdb:logical_name).

Traits§

ActorContext: Request-scoped identity view used by privacy and ownership checks.
ActorFactory: Build an ActorContext from opaque JSON at the Valence port boundary.
ActorJsonPolicy: Validates actor_json before a crate::runtime::ValenceFactory binds an actor.
BatchCreatable: Marker trait for models participating in batch create codegen.
DatabaseBackend: Storage engine behind Valence: CRUD, compiled queries, and graph edges.
DatabaseEndpointResolver: Resolve a physical connection URL for a logical database name at bootstrap.
DatabaseEvaluator
IdHolder
Model: Core trait that all generated models implement.
PolicyEvaluator: Per-rule evaluator referenced from schema metadata (not registered on the builder).
QueryCompiler: Compiles QueryCore for one database dialect.
SchemaMetadata: Compile-time schema metadata access for generated models (trait; struct is crate::schema::SchemaMetadata).
SecretProvider: Resolve secret material by key at runtime.
SideEffect
TelemetrySink: Host-injectable telemetry sink for Valence ORM metrics and events.
ValenceFactory: Factory for reconstructing Valence instances outside request context.
WithReference

Functions§

apply_deletion_node: Apply one deletion DAG node under valence (deletion-scoped; no Update on SetNull).
bootstrap_embedded_router: Bootstrap an embedded router from explicit logical names.
bootstrap_embedded_router_from_inventory: Bootstrap an embedded router using schema inventory discovery.
check_dag_delete_privacy: Authorize PrivacyOperation::Delete for every CascadeDelete node in dag under valence’s actor.
check_dag_delete_privacy_with_registry: Like check_dag_delete_privacy, but uses registry (tests / tooling).
collect_distinct_embedded_surreal_logical_names: Distinct embedded Surreal logical names from every linked valence_schema! plus defaults.
compile_for_engine: Compile core for the given backend engine id.
connect_embedded_at_path: Open an embedded Surreal database at path, pin namespace/database, optionally clear stale lock.
connect_embedded_from_env: Open embedded Surreal using neutral env vars.
database_from_env: Read database name from VALENCE_DB (default prod).
dispatch: Invoke the dispatcher if configured.
dispatch_queued_delete_side_effects: Run registered Delete side effects for table using a pre-delete JSON snapshot.
embedded_engine_from_env: Read embedded engine from VALENCE_EMBEDDED_ENGINE (default RocksDB).
embedded_path_from_env: Read store path from VALENCE_EMBEDDED_PATH (default surreal/data).
extract_id_from_record: Errors
extract_id_from_record_display: Strip the first table: prefix from a Surreal thing display string; return the id portion.
extract_id_from_select_value: Parse a row from SELECT VALUE id (JSON) into the record id string (no table: prefix).
find_iter_descriptor: Find a descriptor by logical table name and iter type name (Rust type string).
get_record_via_cache: Point-get with optional read-through cache (raw row, pre-privacy).
get_record_with_ownership_bundle_via_cache: Unified Model::get fetch: one backend round trip for row + ownership gate status (when cache cold).
global_compiler_registry: Global registry populated from enabled compiler features.
id_from_model: Errors
install_default_mem_router: Register the default in-memory backend under DEFAULT_IN_MEMORY_ROUTER_KEY.
install_telemetry_sink: Install the process-wide Valence telemetry sink (tests and host boot).
invalidate: Drop cached rows after a write or ownership status change.
invalidate_for_backend: Drop a cached row for a specific backend after a write.
is_deletion_dispatcher_registered: True if register_deletion_dispatcher (or a test dispatcher) was installed in this process.
is_system_shaped_actor: True when actor_json uses the well-known System object key.
iter_descriptors_for_table: All iters registered for a table.
json_value_to_fields: Flatten a JSON object into string field pairs for sinks that only store tuples.
list_ttl_table_names: Tables in registry whose schema declares ttl:.
namespace_from_env: Read namespace/database from VALENCE_NS / VALENCE_DB (default prod/prod).
prepare_create_content: Prepare content for create / creating-upsert when the table has a TTL policy.
privacy_bypass_active: True when privacy evaluation is skipped (both bypass env keys set).
queue_delete_entity: Queue a privacy-checked deletion run for table/id.
queue_delete_entity_returning_run_id: Like queue_delete_entity, but returns the new valence_deletion_run id when a run was created (None when the row was already missing or already pending_deletion).
read_cache_enabled: Whether the read-through record cache is active (default on; VALENCE_READ_CACHE=0 disables).
redact_credentials_in_text: Redact scheme://userinfo@host substrings embedded in free-form error text.
redact_endpoint: Remove URL userinfo before placing an endpoint in an error or log message.
register_backend_logical_names: Register one shared backend under each logical name.
register_backend_logical_names_slices: Register backend under every distinct logical name in groups (deduplicated).
register_deletion_dispatcher: Register the process-wide deletion dispatcher (call once from server bootstrap).
register_embedded_logical_names: Register one embedded Surreal handle under each logical name.
register_embedded_logical_names_from_inventory: Register embedded logical names discovered from schema inventory.
register_embedded_logical_names_slices: Register db under every distinct logical name in groups (deduplicated).
register_noop_deletion_dispatcher_for_tests: Install a no-op dispatcher when the slot is still empty (integration tests, harness crates).
retry_on_database_tx_conflict: Retry an async Valence operation when is_retryable_transaction_contention applies.
router_key: Build the compound router key used for registration and resolution.
schema_connections_for_table: Connections for table_name, preferring macro-registered schema connections.
shared_router_with_embedded_logical_names: Build a router with embedded Surreal registered for each logical name.
surreal_record_id_for: Build a SurrealDB record id for a table and id string.
telemetry_sink: Current sink, or NoOpSink when none is installed.
try_log_event: Emit a structured event from flat field tuples.
try_log_event_value: Emit a structured event from a JSON payload (instrumentation default).
try_record_counter: Emit a counter when a sink is installed.
try_record_gauge: Emit a gauge when a sink is installed.
wrap_backend: Wrap inner with InstrumentedBackend.

Type Aliases§

DeleteSideEffectDispatchFn: Type-erased delete side-effect runner (before-row as JSON).
IterExecuteFn: Type-erased execute for orchestration (row as JSON).
IterShouldRunFn: Type-erased should_run for orchestration (row as JSON).
Result
SDb: Embedded Surreal client type.
SchemaMetadataStruct: Alias used by valence_schema! codegen.
SurrealMemBackend: Alias for SurrealEmbeddedBackend (historical template name).

Crate valence

Crate valence Copy item path

§Features

§Topologies

§Embedded (one process)

§Remote (wire)

§Getting started

§1. Choose and wire storage

§Select a backend in the schema

§2. Declare schemas

§Declare and ensure TTL

§3. Set up build-time codegen

§4. Use generated models (CRUD)

§5. Route multiple backends

§6. Inject host ports

§How the pieces link together

§Next steps

§Entry points

§Prerequisites and gotchas

§Runnable examples

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate valence