Rust Client¶
TypeBridge 2.1 ships a public, generated-schema Rust application surface with the same model, CRUD, immutable-query, transaction, and one-exchange remote contracts as the Python and TypeScript bindings. Rust 1.88 or newer is required.
Distribution¶
Starting with 2.0.1, the Rust SDK is distributed from crates.io as a complete,
version-locked package graph. Generated application crates depend only on the
public type-bridge package; they do not expose the supporting engine crates.
[dependencies]
models = { package = "type-bridge-generated-schema", path = "generated/rust" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
type-bridge = "2"
Commit Cargo.lock after resolving the SDK and generated schema crate.
Historical 2.0.0 source dependency¶
TypeBridge 2.0.0 was released before the complete package graph became publishable. Use the 40-character commit recorded in its GitHub release:
[dependencies]
models = { package = "type-bridge-generated-schema", path = "generated/rust" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
type-bridge = { version = "=2.0.0" }
[patch.crates-io]
# Replace this value with the exact release commit. Do not use a branch.
type-bridge = { git = "https://github.com/ds1sqe/type-bridge", rev = "<40-character-v2.0.0-commit>" }
The patch satisfies both the application's dependency and the generated
crate's exact type-bridge requirement from one immutable source revision.
Generate the schema crate¶
Declare the Rust output in the Split-YAML workspace:
Then validate and generate all configured projections:
type-bridge --manifest typebridge.yaml schema check
type-bridge --manifest typebridge.yaml schema generate
The Rust output is an ordinary application-owned crate. It contains the model
and create types, type/field/role tokens, schema fingerprints, canonical
compiled authority, and the owner-branded SCHEMA package used at connection
time. Its managers and query sessions need no external JSON authority.
Regenerate the crate whenever the canonical Split-YAML schema changes; do not
hand-edit generated code.
Apply the schema¶
Generation is offline and never changes TypeDB. Commit a migration and apply it through an environment whose workspace policy explicitly permits migration:
type-bridge --manifest typebridge.yaml migration make --name initial
type-bridge --manifest typebridge.yaml migration plan
type-bridge --manifest typebridge.yaml migration apply --environment development
Credentials remain environment references in typebridge.yaml; provide their
values through the named environment rather than committing them.
Connect and bind the generated authority¶
use models::{AppSchema, SCHEMA};
use type_bridge::{ConnectionOptions, Database};
async fn connect() -> type_bridge::Result<Database<AppSchema>> {
let options = ConnectionOptions::new("localhost:1729", "example-development")
.http_port(8000)
.credentials(
std::env::var("TYPEDB_USERNAME").unwrap_or_else(|_| "admin".into()),
std::env::var("TYPEDB_PASSWORD").unwrap_or_else(|_| "password".into()),
);
Database::connect(options).await?.with_schema(SCHEMA)
}
with_schema verifies and installs the generated runtime projection before it
changes Database<Unbound> into Database<AppSchema>. Models from another
generated package cannot be used with that handle. Enable verified TypeDB TLS
with .tls(true) and provision custom roots through the process's native
trust store.
CRUD¶
Generated constructors require complete schema-valid input. For the reference
workspace's person type:
use models::{DisplayName, EmployeeId, Person, PersonCreate};
let create = PersonCreate::try_new(
DisplayName::new("Ada Lovelace".to_owned())?,
EmployeeId::new("EMP-001".to_owned())?,
)?;
// put is idempotent by the generated key and returns a complete model.
let ada = db.entities::<Person>().put(create).await?;
let iid = ada.iid().to_owned();
let same = db
.entities::<Person>()
.get_by_iid(&iid)
.await?
.expect("person exists");
assert_eq!(same.employee_id().value(), "EMP-001");
let all = db.entities::<Person>().all().await?;
let count = db.entities::<Person>().count().await?;
assert_eq!(all.len() as u64, count);
db.entities::<Person>().delete(&iid).await?;
insert, insert_many, put_many, and update are also available.
Generated put and update replace the complete non-key state: an omitted
optional or empty multivalue deletes its prior ownership. Relation managers
provide the corresponding keyed lifecycle, role replacement, repeated
players, and IID/key-fallback references.
For several operations that must commit together, borrow managers from one write transaction:
let write = db.write().await?;
let person = write.entities::<Person>().put(create).await?;
// Other entity/relation operations borrow the same open context.
write.commit().await?;
Dropping an open write transaction never commits it; commit and rollback
consume the transaction. Use rollback_keep(&mut self) to discard writes and
continue using the same transaction before an explicit commit.
Exact manager filters¶
Generated field tokens also build immutable single-model filters without opening the broader typed-query grammar:
use type_bridge::ProjectedManagerComparison;
let adult = db.entities::<Person>().where_(
PersonType::age,
ProjectedManagerComparison::Gte,
&Age::new(18)?,
)?;
let people: Vec<Person> = adult.all().await?;
let ada = db.entities::<Person>().where_(
PersonType::person_id,
ProjectedManagerComparison::Eq,
&PersonId::new("ada")?,
)?.first().await?;
where_ returns a sibling and accepts only the six canonical scalar
comparisons. first requires equality evidence for every effective
reference-key field and proves that at most one exact IID matched. Use an
explicit read transaction when several manager terminals and typed queries
must share one snapshot:
let read = db.read().await?;
let adults = read.entities::<Person>().where_(
PersonType::age,
ProjectedManagerComparison::Gte,
&Age::new(18)?,
)?;
let count = adults.count().await?;
let exists = adults.exists().await?;
assert_eq!(exists, count != 0);
drop(adults);
read.close().await?;
Generated token types provide the package fence for ordinary Rust code, and
foreign-package tokens fail to compile against a local manager. The public
low-level FieldToken constructor remains available for compatibility; a
manually reconstructed token is therefore admitted only when its canonical
owner, ownership fact, attribute domain, and metadata are indistinguishable
from the installed projection.
Immutable typed queries¶
use models::{EmployeeId, Person, PersonType};
use type_bridge::value::Text;
use type_bridge::RowsOptions;
let mut session = db.query()?;
let person = session.exact::<Person>()?;
let employee_id = person.field(PersonType::employee_id);
let query = session
.query(person)?
.where_(employee_id.starts_with(Text::new("EMP-")?))?;
let people: Vec<Person> = query
.rows(RowsOptions::new(50).order_by(employee_id.asc()))
.await?;
let exists = query.exists().await?;
let count = query.count().await?;
The same grammar supports exact and subtype bindings, attribute predicates,
role connections, bounded reachability, tuples, derived SelectedRow
shapes, collected children, pages, aggregates, and grouping. All bindings
carry the generated schema owner, so cross-schema comparisons fail at
compile time.
Reuse one read transaction¶
Database-owned query terminals may open their own read context. To preserve one snapshot across several terminals, borrow a session from an explicit read transaction:
let read = db.read().await?;
let mut session = read.query();
let person = session.exact::<Person>()?;
let query = session.query(person)?;
let before = query.count().await?;
let any = query.exists().await?;
let after = query.count().await?;
assert_eq!(before, after);
assert_eq!(any, before != 0);
drop(query);
drop(session);
read.close().await?;
Staged transactions and plans¶
A plan is one typed query-plan/v3 pipeline: a match with comparisons and
let values, then updates, inserts, puts and deletes. A staged transaction
queues plans and runs them all at commit, in order, as one TypeDB
transaction. Nothing opens before commit, and a plan that matches no row
writes nothing, so one plan is a complete conditional write. Which writes
make it race-safe is in Concurrency and conditional writes.
The one-query purchase checks the stock and the balance, takes the item and the price, and records the purchase:
use models::{Account, AccountType, AppSchema, Item, ItemType, Purchase, PurchaseType};
use type_bridge::plan::Plan;
use type_bridge::staged::{PlanAnswer, TransactionOptions};
use type_bridge::Database;
fn purchase(order: &str, item_id: &str, account_id: &str) -> type_bridge::Result<Plan<AppSchema>> {
let mut plan = Plan::builder();
let item = plan.exact::<Item>();
let buyer = plan.exact::<Account>();
let order_input = plan.input::<String>("order_id");
let item_input = plan.input::<String>("item_id");
let account_input = plan.input::<String>("account_id");
let item_key = plan.field(item, ItemType::item_id);
let buyer_key = plan.field(buyer, AccountType::account_id);
let stock = plan.field(item, ItemType::stock);
let price = plan.field(item, ItemType::price);
let balance = plan.field(buyer, AccountType::balance);
plan.where_(item_key.eq(item_input))
.where_(buyer_key.eq(account_input))
.where_(stock.gt(0_i64))
.where_(balance.ge(price));
let next_stock = plan.let_("next_stock", stock - 1_i64);
let next_balance = plan.let_("next_balance", balance - price);
plan.update(item, ItemType::stock, next_stock)
.update(buyer, AccountType::balance, next_balance);
plan.insert::<Purchase>()
.field(PurchaseType::order_id, order_input)
.player(PurchaseType::buyer, buyer)
.player(PurchaseType::item, item);
plan.row([
order_input.value(order.to_owned()),
item_input.value(item_id.to_owned()),
account_input.value(account_id.to_owned()),
]);
plan.build(&models::SCHEMA)
}
async fn buy(db: &Database<AppSchema>) -> type_bridge::Result<bool> {
let mut tx = db.transaction(TransactionOptions::default());
let bought = tx.stage(&purchase("O1", "I1", "A1")?)?;
tx.commit().await?;
// `Matched(0)`: out of stock or short of funds; nothing was written.
Ok(*bought.get()? == PlanAnswer::Matched(1))
}
The builder's handles (item, stock, order_input) come from generated
model and field tokens, so a field another model owns does not compile.
build validates the plan against the generated schema and returns the
first invalid call; nothing is checked against TypeDB until commit.
- Reads. A plan without writes answers rows of the columns passed to
returning, orcount()/exists(). - Writes. A write plan answers
Matched(n), the number of rows its pipeline wrote, or withreturning(..)the rows from the same pipeline. - Batches. Each
rowbinds the inputs once; many rows run the one plan over all of them. - Answers. Each
stagereturns aPendinganswer that resolves after a successful commit. A failed commit stores nothing and reports the failing plan's index and its typed failure; see Classified errors. - Kinds.
TransactionOptions::default().with_kind(..)makes the transactionRead,WriteorSchema; without one, a staged write makes itWrite.Readrefuses write plans andSchemarefuses every plan. - Reuse.
rollbackdiscards the queued plans and keeps the transaction;closeends it. Dropping it never commits.
ProxyDatabase::transaction returns the same Transaction. Its commit is
one signed request; a lost reply is commit_outcome_unknown, and the caller
reads the database to learn whether the plans applied.
Building is deterministic: handles are numbered in creation order, match
terms keep their call order, consecutive writes of one kind share a stage,
and names come from labels (item, item_stock). The same program always
has the same canonical plan bytes (Plan::canonical_bytes).
Direct or proxy¶
A program that queries through a Connection runs unchanged against TypeDB
or a TypeBridge server; only the policy passed to SCHEMA.connect differs:
use models::{AppSchema, Person, SCHEMA};
use type_bridge::{
Connection, ConnectionPolicy, DirectConnectionPolicy, ProxyConnectionPolicy,
ProxyEndpoint, QueryExecutionResourceLimits, TlsPolicy,
};
fn policy(proxy: bool) -> ConnectionPolicy {
if proxy {
ProxyConnectionPolicy::new(
ProxyEndpoint::new("https://typebridge.example.com")
.tls(TlsPolicy::native_roots())
.header("Authorization", "Bearer <token>"),
)
.into()
} else {
DirectConnectionPolicy::new("localhost:1729", "example", "admin", "password").into()
}
}
let connection: Connection<AppSchema> = SCHEMA.connect(policy(use_proxy)).await?;
let mut session = connection.query_with_resources(
QueryExecutionResourceLimits {
items: 100,
..QueryExecutionResourceLimits::default()
},
type_bridge::AnswerCancellation::default(),
)?;
let person = session.exact::<Person>()?;
let rows: Vec<Person> = session
.query(person)?
.rows(type_bridge::RowsOptions::new(50))
.await?;
Both policies take answer_limits(..), the ceiling every session of the
connection is constrained by, and connection_limits(..), the deadline for
connecting. A session's resources are the stricter of its own and the
ceiling, on either transport. With nothing configured, a session runs under
its transport's defaults: the 2.2 executor defaults direct, the wire limits
(65,536 items, 32 MiB) through a proxy.
A proxy connection fetches the server's signed /v2/capabilities
advertisement when it connects, or uses the exact bytes pinned with
.advertisement(bytes). Fetch it only over TLS you trust, or pin it: the
advertisement carries the key every reply is verified with. Each terminal
then performs exactly one POST /v2/query. The SDK binds the scope and
semantic profile embedded in SCHEMA, the nonce, request fingerprint,
deadline, limits, and reply identity before it materializes the same model
types as a direct connection.
A host that routes or authenticates requests itself implements
ProxyExchange (capabilities() and exchange()) and passes it to
ProxyConnectionPolicy::with_exchange. Connection::Direct also gives the
Database with CRUD managers and transactions, which a proxy connection
does not offer.
Classified errors¶
Handle failures through the stable category, code, path, and detail accessors. Human messages are diagnostic text and are not a machine-readable contract:
use type_bridge::{Error, ErrorCategory, ModelValidationPhase};
fn inspect(error: &Error) {
match error.category() {
ErrorCategory::QueryAuthoring => {
eprintln!("invalid query {} at {:?}", error.code().unwrap(), error.path());
}
ErrorCategory::ModelValidation => {
assert!(matches!(
error.model_validation_phase(),
Some(ModelValidationPhase::Input | ModelValidationPhase::Hydration)
));
}
ErrorCategory::Capability | ErrorCategory::ResourceLimit => {
eprintln!("executor rejected {}: {}", error.code().unwrap(), error.message());
}
_ => eprintln!("{error}"),
}
}
Direct and remote query paths map canonical failures to the same
ErrorCategory and preserve stable codes and structured paths when supplied
by the engine or remote diagnostic. Authenticated remote failures also expose
their exact typed path through diagnostic_path() and deterministic detail map
through details(). Generated manager and projected-batch failures additionally
retain the binding-neutral category through sdk_category(); for example,
wrong_scalar_domain reports Some("invalid_input") even though the released
Rust compatibility category remains ErrorCategory::ModelValidation.
Implementations of ProxyExchange should wrap
application-owned transport failures with
Error::remote("stable_snake_case_code", message, source).
Provider rejections expose error.failure() with the shared
type_bridge::failure::Failure vocabulary. A rejected commit carries a reason,
reported lock kind where applicable, and retry_safe = true; rerun the entire
transaction on a fresh snapshot. An indeterminate outcome requires
reconciliation before retry. Rejection diagnostics keep their released codes
and add a rejection detail naming the reason. Staged errors additionally
retain operation indexes and schema identities supplied by plan metadata.