teaql-runtime

Minimal runtime repository and graph persistence layer for TeaQL Rust.

teaql-runtime owns TeaQL's runtime concepts: metadata lookup, repository assembly, behaviors, checkers, events, graph planning, and in-memory execution. Database execution is supplied by provider crates.

What It Provides

• UserContext for metadata, typed resources, request locals, and runtime options
• request policy hooks for platform-level security, observability, and resource limits
• repository registry and behavior registry
• memory repository for tests and lightweight execution
• checker registry and translated validation results
• entity event sink support
• graph save planning and execution
• typed entity graph extraction
• SQL debug logging options on UserContext

Source Layout

The repository layer is split by concern under src/repository/:

• types.rs: public repository structs and relation load plan types
• executor.rs: QueryExecutor and graph transaction boundary types
• cache.rs: aggregation cache traits and in-memory cache
• base.rs: metadata-backed Repository compile and CRUD helpers
• context.rs: UserContext repository assembly and context repository logging/cache invalidation
• resolved.rs: entity-scoped repository query and mutation entry points
• graph.rs: graph planning, graph save execution, and graph node validation
• relation.rs: relation plans, relation enhancement, child queries, and relation aggregates
• helpers.rs: shared bucket keys, cache keys, projection helpers, and graph relation validation

Request Policy and Repository Behavior

RequestPolicy is the platform-level boundary. It runs on ResolvedRepository select and mutation entry points before SQL is compiled or executed, and it is intended for tenant isolation, permission enforcement, raw SQL control, observability, and infrastructure protection.

RepositoryBehavior remains entity-scoped. Use it for domain-specific behavior such as default relation loading or entity-specific command enrichment.

The runtime applies entity behavior first and request policy last, so platform policy remains the final enforcement point before repository execution.

Example

use teaql_runtime::{InMemoryMetadataStore, UserContext};

let mut ctx = UserContext::new()
    .with_metadata(InMemoryMetadataStore::default());

let logs = ctx.sql_logs();
assert!(logs.is_empty());

SQL execution logging is enabled for select and mutation statements by default. Use ctx.disable_sql_log() to turn it off, or ctx.set_sql_log_options(...) to restrict which operations are recorded.

With generated code, applications typically register a generated runtime module and then use generated entity/request helpers:

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

Database, cache, message, search, AI, and filesystem integrations live outside this crate as runtime providers/adapters. For SQLx-backed databases, choose one database-specific provider crate:

teaql-runtime = "0.7"
teaql-provider-sqlx-postgres = "0.7"
teaql-provider-sqlx-sqlite = "0.7"
teaql-provider-sqlx-mysql = "0.7"

Provider crates expose a small registration helper. Runtime code registers whichever provider the application selected, then calls the database-neutral schema entry point:

use teaql_provider_sqlx_postgres::{PgMutationExecutor, PostgresProviderExt};
use teaql_runtime::{RuntimeError, UserContext};

let mut ctx = UserContext::new()
    .with_module(my_domain::module())
    .with_repository_registry(my_domain::repository_registry());

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

The provider-specific helpers remain available for low-level use, but application code should prefer ctx.ensure_schema().await? once a provider is registered.

teaql-runtime itself no longer has a sqlx feature and no longer exports sqlx_support.