Rust Overview

TeaQL Rust is the Rust runtime and generated-crate target for TeaQL domain models. It is not a generic ORM replacement. It is useful when the domain model is central, relation graphs matter, and application code should work through generated, typed business APIs instead of handwritten repository boilerplate.

The Rust work is split across two sibling projects:

• teaql-rs: Rust runtime crates, SQL compiler, repository boundary, providers, macros, graph writes, checkers, events, and in-memory execution.
• teaql-code-gen: Java-based generator that can emit Java packages and Rust service crates from the same model.

Workspace Shape

The teaql-rs workspace is organized by runtime responsibility:

Crate	Responsibility
teaql-core	entity traits, metadata, values, expressions, query model, SmartList<T>
teaql-sql	SQL dialects, compiled query types, DDL helpers, AST-to-SQL compilation
teaql-runtime	UserContext, repository registry, behavior registry, checker registry, graph writes, events, memory execution
teaql-macros	#[derive(TeaqlEntity)] and entity/record mapping support
teaql-provider-sqlx-postgres	PostgreSQL SQLx provider, schema bootstrap, transactions, row decoding, id-space generation
teaql-provider-sqlx-mysql	MySQL SQLx provider, schema bootstrap, transactions, row decoding, id-space generation
teaql-provider-sqlx-sqlite	SQLite SQLx provider, schema bootstrap, transactions, row decoding, id-space generation
teaql-provider-rusqlite	synchronous SQLite provider for embedded and multi-architecture deployments

Generated Service Crate

teaql-code-gen can generate a Rust service crate from a TeaQL model. The generated crate typically provides:

• entity structs with #[derive(TeaqlEntity)]
• query facade Q
• safe expression facade E
• generated request builders
• relation loading helpers
• graph save helpers
• behavior and checker skeletons
• runtime registration helpers such as module(), module_with_behaviors(), module_with_behaviors_and_checkers()
• repository and behavior registries
• database runtime helpers when the selected data service has a Rust provider

Generated application code should prefer:

use crm_erp_service::Q;

let platforms = Q::platforms()
    .select_merchant_list_with(
        Q::merchants()
            .select_name()
            .with_names_contain("TeaQL"),
    )
    .execute_for_list(&ctx)
    .await?;

Runtime Assembly

The generated Rust crate registers metadata and runtime hooks through RuntimeModule:

let ctx = teaql_runtime::UserContext::new()
    .with_module(my_domain::module())
    .with_repository_registry(my_domain::repository_registry())
    .with_repository_behavior_registry(my_domain::behavior_registry());

For provider-backed services, generated helpers can assemble the runtime from a database pool or environment variables, register the selected provider, and call ensure_schema().

Domain model
  -> generated Rust crate
  -> RuntimeModule
  -> UserContext
  -> Repository API
  -> SQLx PostgreSQL / SQLx MySQL / SQLx SQLite / rusqlite / MemoryRepository

Current Scope

Rust is strongest today for:

• generated Q-style query APIs
• typed entity mapping
• selection, filters, sorting, paging, aggregation, and relation loading
• SmartList<T>
• relation enhancement and relation aggregate enhancement
• graph writes and graph mutation planning
• checkers and translated validation messages
• request policy hooks for platform-level data and infrastructure protection
• mutation events
• SQL debug logging
• provider-backed schema bootstrap
• no-database tests with MemoryRepository

For provider selection, read Rust Database Providers. For platform-level runtime customization, read Rust Runtime Extension Points.