Skip to main content

Why TeaQL Rust?

A Rust Domain-Driven Data Framework tailored for the AI Era and Enterprise Compliance

In traditional software engineering, ORMs are merely tools for mapping objects to tables. However, in today's landscape where AI-assisted code generation is ubiquitous and enterprise data compliance is increasingly stringent, we need to redefine what a data framework is.

TeaQL abandons the narrow, traditional focus of "only caring about how to generate SQL" and instead reconstructs the value paradigm of a data runtime from the perspective of six core roles in the software lifecycle.

1. Architect & Compliance Perspective​

Core Demands: Data isolation, privacy protection, and reviewable architectural boundaries.

Architects usually do not care about how CRUD is written; they care about whether the system suffers from cross-tenant/cross-user privilege escalation, whether database leaks will expose private data, and whether the system can pass rigorous compliance audits like SOC2.

  • UserContext-Based Boundary: TeaQL uses UserContext as the runtime execution boundary. Projects must populate and verify tenant, identity, permission, and infrastructure resources.
  • Central Request Policy: Platform policy and generated filters can apply tenant constraints consistently when correctly modeled, registered, and tested. This reduces bypass opportunities but does not replace authorization review or database controls.
  • Structured Audit Events: EntityEventSink can record state transitions with identity and business intent. Compliance still depends on sink durability, access control, retention, configuration, and operational evidence.

2. AI Coder Perspective​

Core Demands: High modularity, unambiguous contracts, and extremely high-density context.

AI coding tools work better when contracts, generated methods, examples, and failure rules are explicit and inspectable.

  • Predictable API Surface: TeaQL uses recurring fluent patterns such as Q::entity() and entity.audit_as(...).save(&ctx). Agents must still read generated methods rather than infer them from entity names.
  • Machine-Readable Guidance: Project rules and focused examples can help agents respect generated-file, intent, and audit boundaries; compilation, tests, and human review remain required.

3. Human Reviewer Perspective​

Core Demands: Understand business intent at a glance, rather than getting lost in SQL joins and logic.

If code is generated by AI, the human job shifts to code review. Reviewers dread looking at dozens of lines of string-concatenated SQL logic.

  • Declarative Domain Graphs: Instead of seeing raw INSERT/UPDATE statements, reviewers see graph changes followed by task.audit_as("Dispatch task").save(&ctx). The exact cascade and transaction behavior still depends on the generated model and provider.
  • Intent-Driven Code: A query ends with comment → purpose → execution, so reviewers can see both the operation and its business reason.

4. SRE / Ops Perspective​

Core Demands: Instantly locate specific business code and context when slow queries or dirty data occur.

SQL generated by traditional ORMs is like hieroglyphics. When a DBA finds a slow query that locks a table, developers often fail to recognize which part of the code initiated it.

  • Business Intent Correlation: TeaQL requests carry comment and purpose, and mutations carry audit_as. Applications can correlate these with runtime output; propagation into database/server logs must be tested for the selected provider, driver, proxy, and monitoring stack.
  • Configurable Runtime Output: Current generated workspaces expose separate audit, SQL, tool, sink, and schema settings. Exact fields and trace export depend on application subscriber/sink wiring. See SRE & Observability.

5. Data Ops & Quality Perspective [In Planning]​

Core Demands: The database is no longer a black box; it can actively detect quality issues like orphan data, invalid foreign keys, and abnormal states.

Based on our mature enterprise experience with the Java version, TeaQL is introducing a global data quality inspection engine to the Rust ecosystem:

  • Schema Drift Detection: At startup, it precisely compares the in-memory EntityDescriptor with the actual database schema and outputs a detailed drift report.
  • Data Health Scanning: Utilizing the metadata association graph at the framework level, future releases will support generating data quality reports to automatically find issues like "orphan data with a Task but no corresponding Project" or "dirty data whose state transitions violate the state machine". Work that previously required offline big-data jobs is executed directly in the runtime data layer.

6. Real-time Analytics Perspective [In Planning]​

Core Demands: Seamlessly pipe data streams generated by business operations to analytical engines.

Traditional solutions rely on heavy components like Maxwell/Canal to monitor binlogs.

  • Built-in Facet Analysis: Generated statistic APIs can express multi-dimensional business queries without moving aggregation into application loops. Exact methods and performance depend on the model and provider.
  • Real-time EventSink Distribution: Building upon the implemented EntityEvent change capture mechanism, future plugins for Kafka/ClickHouse EventSinks will allow business data changes to flow to data warehouses for real-time analysis with just a single line of configuration, removing the need for external CDC components.

TeaQL Rust carries design experience from the Java runtime while adopting Rust-native providers and type boundaries. Evaluate current capabilities against the compatibility matrix and treat sections marked In Planning as direction, not released behavior.