valence

Public crate re-exporting core, macros, and optional reference adapters — the primary dependency for Valence applications. Enable backend features explicitly (see below) and wire runtime storage with Valence::builder() at boot.

Overview and quickstart: ../README.md.

Source of truth: cargo doc -p uf-valence --open

Cargo features

Enable backends explicitly when minimizing dependencies:

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

How to run examples

Walkthrough ladder: examples/README.md — ordered path from quickstarts through workspace hosts to testkit fixtures.

Topology docs: Embedded / Remote (wire).

Valence is an in-process ORM: one host process owns the router. There is no coordinator/worker split. “Remote” means a wire client to an external database.

1. Embedded mem — quickstart (standalone)

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

Success: stdout prints quickstart: schema … registered; Valence runtime ready.

2. Durable embedded — quickstart_sqlite (standalone)

cargo run -p uf-valence --example quickstart_sqlite --features sqlite

3. Multi-backend routing — multi_backend (standalone)

One process, two logical mem backends + default key.

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

4. Codegen → Model — workspace codegen-host

Typed Model impls need host build.rs + valence-codegen (not a single-file [[example]]). Proof is the co-located test in examples/codegen-host/src/lib.rs.

cargo test -p codegen-host

5. Cross-backend hop + query — workspace cross-backend-model-host

One process, two backends (Project on mem, Task on sqlite): create rows, BelongsTo/HasMany hop, Model::query.

cargo run -p cross-backend-model-host

Success: stdout prints cross-backend-model-host: Project(mem) ↔ Task(sqlite) hop + query OK (…).

6. Remote wire — quickstart_postgres (optional)

Start Postgres with Docker, set the shared URL, then run one example process (skips cleanly when unset):

docker run --rm -d --name valence-postgres -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16
export DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/postgres
cargo run -p uf-valence --example quickstart_postgres --features postgres

MongoDB / Redis follow the same pattern with VALENCE_MONGODB_URI / VALENCE_REDIS_URL (see Other examples and the Docker one-liners in the examples walkthrough). For all four remote backends live at once, see workspace remote-multi-backend-host below.

Other examples

Workspace host proofs (not crate [[example]]s)

See examples/README.md for the full ordered ladder.

Configuration

There is no config file or global settings loader. Integrators wire backends in code; optional env vars tune runtime behavior.

Precedence (library)

1. Cargo features — choose which adapters and telemetry are linked (default = ["mem"]).
2. Constructor / builder arguments — ValenceBuilder methods at host boot.
3. Struct Default — omitted builder ports fall back to no-op providers.
4. Environment variables — read once at first use (see table below).

Library environment variables

Surreal-specific wiring and bootstrap helpers: valence-backend-surreal/README.md.

Host ports (secrets, actor, endpoints, telemetry): cargo doc -p uf-valence-core → module ports.

Storage adapter contract: cargo doc -p uf-valence-core → DatabaseBackend; example examples/acme-valence-backend-stub.