Rust Overview

TeaQL Rust is the Rust runtime and generated-crate target for TeaQL domain models. It is not a conventional Rust ORM. It is a model-driven runtime for applications that want generated, typed business APIs, relation graph loading, graph writes, runtime policy, and auditable execution instead of handwritten repository boilerplate.

The current Rust workspace is centered on a clear split:

• teaql-code-gen turns a TeaQL model into generated Rust service crates.
• teaql-rs provides the runtime crates that execute those generated APIs.
• teaql-data-service defines the backend execution boundary so TeaQL can talk to SQL databases, search providers, memory execution, or other backend resources without making the core runtime depend on one driver.

Current Workspace Shape

The teaql-rs workspace is organized by runtime responsibility:

Crate	Responsibility
teaql-core	Entity traits, metadata, values, expressions, query model, mutation model, base entity data, and SmartList<T>.
teaql-data-service	Backend executor traits: DataServiceExecutor, QueryExecutor, MutationExecutor, TransactionExecutor, SchemaExecutor, and IdGeneratorExecutor.
teaql-sql	SQL dialects, compiled query types, DDL helpers, and AST-to-SQL compilation.
teaql-runtime	UserContext, metadata lookup, repository assembly, request policy, behavior registry, checker registry, event sinks, graph planning, graph saves, and memory execution.
teaql-macros	#[derive(TeaqlEntity)], entity descriptor generation, attribute parsing, and typed record/entity mapping.
teaql-provider-postgres	PostgreSQL provider using deadpool-postgres / tokio-postgres, schema bootstrap, row decoding, and ID-space generation.
teaql-provider-mysql	MySQL provider using mysql_async, schema bootstrap, row decoding, and ID-space generation.
teaql-provider-sqlite	SQLite provider using rusqlite, schema bootstrap, transactions, row decoding, streaming chunks, and ID-space generation.
teaql-provider-meilisearch	Meilisearch provider implementing TeaQL data-service query/mutation traits for search-backed execution.
teaql-cache-integration-redis	Redis-backed DataStore integration for distributed cache use cases.
teaql-web-integration-axum	Axum integration helpers for UserContext, request information, and web responses.
examples	Runnable examples for schema bootstrap, CRUD, relation loading, graph writes, and provider behavior.

The current published workspace version is 4.0.0.

Runtime Boundary

The most important architecture change is the teaql-data-service boundary. TeaQL runtime code plans queries, graph writes, relation enhancement, checks, and events. Backend providers execute concrete operations.

Generated Q API
  -> generated service crate
  -> RuntimeModule
  -> UserContext
  -> Repository / graph planning / request policy
  -> teaql-data-service traits
  -> PostgreSQL / MySQL / SQLite / Meilisearch / Memory / other backend

The main traits are:

Trait	Purpose
DataServiceExecutor	Base backend executor and capability flags.
QueryExecutor	Execute SelectQuery requests.
StreamQueryExecutor	Stream query results in chunks when a provider supports it.
MutationExecutor	Execute insert, update, delete, recover, and batch mutations.
TransactionExecutor	Create transaction scopes for graph writes and mixed operations.
SchemaExecutor	Ensure backing tables, columns, or provider schema are ready.
IdGeneratorExecutor	Generate entity IDs through backend-specific id-space behavior.

This boundary is why database providers, search providers, cache integrations, and web integrations can evolve without turning teaql-runtime into a driver-specific crate.

Generated Service Crate

teaql-code-gen can generate Rust service crates from the same TeaQL model used for Java generation. A generated Rust crate typically provides:

• entity structs with #[derive(TeaqlEntity)],
• generated Q::entities() query facade,
• generated request builders,
• field filters, projections, sorting, pagination, grouping, and aggregates,
• relation loading helpers such as select_relation_with(...),
• graph save helpers,
• behavior and checker skeletons,
• runtime registration helpers such as module(),
• repository and behavior registries,
• provider/runtime helper functions for generated service setup.

Application code should prefer generated APIs over raw data-access code:

use crm_erp_service::Q;

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

Runtime Assembly

Generated crates register metadata and hooks through RuntimeModule:

let mut 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());

Provider crates then register concrete execution resources:

use teaql_provider_postgres::{PgMutationExecutor, PostgresProviderExt};

ctx.use_postgres_provider(PgMutationExecutor::new(pool));
ctx.ensure_schema().await?;

The same generated business API can run against different execution targets when the provider is registered at runtime assembly time.

Current Capabilities

TeaQL Rust is strongest today for:

• generated Q-style business query APIs,
• typed entity mapping through TeaqlEntity,
• SmartList<T> result metadata,
• filters, sorting, paging, projection, grouping, aggregates, and HAVING,
• relation loading and nested relation enhancement,
• relation aggregate enhancement,
• graph writes with create, update, reference, remove, and missing-child handling,
• graph mutation planning through GraphMutationPlan,
• optimistic locking through id + version,
• UserContext as the runtime boundary,
• request policy hooks for platform-level enforcement,
• entity-level behavior hooks,
• checker registry and translated validation messages,
• mutation events and safe audit events,
• SQL debug logging,
• MemoryRepository for no-database tests,
• schema bootstrap through provider crates,
• ID generation through runtime and provider id-space mechanisms,
• framework-neutral web payload helpers,
• Axum integration,
• Redis cache integration,
• Meilisearch provider experimentation.

Provider Direction

The current provider naming is:

Provider crate	Backend
teaql-provider-postgres	PostgreSQL via deadpool-postgres / tokio-postgres
teaql-provider-mysql	MySQL via mysql_async
teaql-provider-sqlite	SQLite via rusqlite
teaql-provider-meilisearch	Meilisearch search backend
MemoryRepository	In-memory execution in teaql-runtime

Older documentation may mention teaql-provider-sqlx-* or teaql-provider-rusqlite. The current workspace has moved to the crate names above.

What Rust Is Not Trying To Be

TeaQL Rust is not trying to replace every Rust data access tool.

Use TeaQL when:

• the domain model is central,
• generated APIs are valuable,
• relation graphs matter,
• runtime policy and auditability matter,
• Java TeaQL-style business APIs should carry into Rust.

Use Diesel, SeaORM, or direct SQL when:

• you want a conventional Rust ORM,
• explicit SQL is the right abstraction,
• a generated domain API would get in the way.

Rust also does not try to copy every Java framework feature. Spring Boot autoconfiguration, Java GraphQL integration, and Java web/controller conventions are Java-specific unless a Rust-native target is explicitly designed.

Current Gaps

Important gaps remain:

• full Java feature parity is not the goal and is not complete,
• richer typed checker generation is still evolving,
• richer event payloads may be needed for old/new value snapshots,
• UUID and byte value support need more work,
• higher-level Rust service/web generation is still a design decision,
• schema migration remains additive/bootstrap-oriented rather than a full migration system.

For cross-stack generation context, read Java/Rust Parity & Generator. For provider selection, read Rust Database Providers. For platform-level runtime customization, read Rust Runtime Extension Points.