Announcing Open Source: teaql-forge-rs — The Next-Generation TeaQL Semantic Generation Engine

We are incredibly excited to announce that teaql-forge-rs is now officially open-source!

As an indispensable scaffolding and code generation engine in the entire TeaQL ecosystem, teaql-forge-rs carries the core mission of transforming human and AI high-level business intentions (.tql models) into production-ready executable code. Alongside the upgrade of the foundational teaql-rs and teaql-code-gen to v3.0, Forge has also welcomed its full open-source release.

What is teaql-forge-rs?

In the past, building an enterprise-level application that complies with Domain-Driven Design (DDD) standards, includes built-in auditing, and supports complex relational queries often required writing a massive amount of boilerplate code.

teaql-forge-rs is a Rust-based code generation tool. By parsing the minimalist .tql DSL (Domain-Specific Language), it automatically generates your foundational domain models, type-safe Query APIs, database access layers (Repositories), and even scaffolding interfaces for frontend-backend interaction. Forge helps alleviate the repetitive labor when writing Rust services.

Core Features

In this open-source release, teaql-forge-rs includes the following main features:

1. Lightweight Rust Generation Engine: A new, relatively streamlined Rust generation engine that supports automatic base code generation for CLI tools or Axum backend applications (Note: The closed-source commercial Java generation engine is not included here).
2. Triple-Intent Semantic API Generation: Fully supports the latest .comment(), .purpose(), and .audit_as() semantic chain call specifications. The code generated by Forge natively forces developers and AI to provide clear business intentions when operating on data, turning logs from unreadable text into business stories.
3. Lightning-Fast Parsing & DDL Mapping: Leveraging Rust's extreme performance, it can parse complex architectures with hundreds of entity definitions in an instant, and automatically map them to DDL structures across multiple databases (PostgreSQL, MySQL, SQLite).
4. Plug-and-Play DDD Structure: The generated code strictly adheres to Domain-Driven Design boundaries, perfectly decoupling the Q::entities() query interface from the persistence layer, drastically reducing maintenance costs and lowering the comprehension barrier for AI.

Docker Quick Start Guide

To allow everyone to experience teaql-forge-rs with zero environment configuration, we provide an official Docker image. You just need to write a schema.tql, and let Docker handle the rest.

1. Prepare Your TQL Model File

Create a schema.tql file in your current directory (for example, defining a simple task board):

entity Task {
    name: string
    status: string
}

2. One-Click Code Generation via Docker

By starting a local Docker service container and using the local client tool, you can experience one-click generation:

1. Start the local code generation service:

docker run -d --name teaql-forge-server -p 8080:8080 teaql/teaql-forge-rs:latest

2. Seamlessly connect the client to the local service for generation:

Combined with the cargo-teaql client tool we provided previously, you simply point the generation endpoint to your local service using --endpoint-prefix to output the enterprise scaffolding and domain:

cargo-teaql gen-workspace --endpoint-prefix http://127.0.0.1:8080/ schema.tql --output ./generated-rust

Once it finishes running, you'll see the complete set of enterprise-grade Rust code in the generated-rust folder in your current directory! This is fully compatible with all operations in teaql-agent-kit.

Daily Development Guide After Generation

After you generate code with teaql-forge-rs, your daily data operations will be completely oriented around domain objects, saying goodbye to tedious SQL string concatenation. Coupled with the latest "Triple-Intent" specification, the business intent of the code itself will be crystal clear.

1. Daily Data Queries and Filtering

All query operations are unified through the Q::entities() entry point. You can use method chaining as naturally as speaking, and you are forced to attach clear business comments:

use generated_rust::Q;

let active_tasks = Q::tasks()
    .which_status_are("TODO")
    .page(1, 20)
    .comment("Retrieve board list data")
    .purpose("Display unfinished tasks")
    .execute_for_list(&ctx)
    .await?;

2. Business Workflows in DDD Mode

In Domain-Driven Design (DDD), we recommend completing business logic on in-memory domain objects before uniformly persisting them. You can first query the object, modify its state, and finally save it using .audit_as() carrying the audit context:

// 1. Query the domain object
let mut task = Q::tasks()
    .with_id_is(42)
    .comment("Get task by ID")
    .purpose("Prepare to advance task workflow status")
    .execute_for_one(&ctx)
    .await?
    .expect("Task does not exist");

// 2. Pure in-memory state transition (via generated Setters or your own domain behaviors)
task.update_status_to("DONE")
    .update_name("Completed task");

// 3. Persist with human operational intent
task.audit_as("User clicked the [Mark as Done] button").save(&ctx).await?;

In this mode, the underlying interceptor will not only execute the corresponding SQL but also automatically generate an audit log with immense business value: [AUDIT] Task(42) UPDATED ... action: User clicked the [Mark as Done] button.

Automating Programming with AI Assistants

A highly standardized, predictable underlying API surface is not only friendly to humans but also serves as "dessert" for large language models.

If you want AI to help you write business code with zero hallucinations, we strongly recommend using it in conjunction with teaql-agent-kit. This toolkit contains built-in Prompts and playgrounds for AI tools like Cursor and GitHub Copilot.

With it, you only need to describe your requirement to the AI:

"Find tasks where the name contains 'bug' and the status is 'TODO', and batch update their status to 'IN_PROGRESS'."

The AI will be able to effortlessly and 100% accurately output the following code:

let mut tasks = Q::tasks()
    .which_names_contain("bug")
    .which_status_are("TODO")
    .comment("Retrieve historical Bugs")
    .purpose("Batch advance Bug status")
    .execute_for_list(&ctx)
    .await?;

for mut task in tasks {
    task.update_status_to("IN_PROGRESS");
    task.audit_as("Automatically advance Bug processing progress").save(&ctx).await?;
}

Through unified semantic API specifications, your AI assistant will truly evolve into a senior engineer that never makes mistakes.

Conclusion

In the era of Agentic Coding, we need a more predictable and semantic underlying API surface. The open-sourcing of teaql-forge-rs is a crucial step towards our vision of "Code is Business Intent".

Welcome to visit the GitHub repository to clone the code, open Issues, or submit PRs, and build the next-generation data runtime environment with us!