teaql-forge-rs Is Now Open Source

teaql-forge-rs is now open source.

The Rust-based generator transforms .tql domain models into executable code for the TeaQL ecosystem. Its release accompanies the v3.0 updates to teaql-rs and teaql-code-gen.

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. Intent-Aware API Generation: Supports .comment(), .purpose(), and .audit_as() chain calls. Generated APIs require callers to state the intent behind reads and mutations.
3. Rust-Based Parsing and DDL Mapping: Parses domain definitions and maps them to DDL for PostgreSQL, MySQL, and SQLite.
4. Generated DDD Structure: Separates the Q::entities() query interface from the persistence layer so application code works with domain APIs rather than database-specific calls.

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. Connect the client to the local generation service:

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

When the command finishes, the generated Rust workspace is available in the generated-rust directory. It is compatible with the Rust workflows in teaql-agent-kit.

Daily Development Guide After Generation

After generation, application code can work through domain objects instead of assembling SQL strings. The intent-aware API also keeps the reason for each data operation close to the operation itself.

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 interceptor executes the persistence operation and records its audit description: [AUDIT] Task(42) UPDATED ... action: User clicked the [Mark as Done] button.

Automating Programming with AI Assistants

A small and predictable API surface is easier for both developers and coding agents to use consistently.

For AI-assisted business development, teaql-agent-kit provides prompts and playgrounds for tools such as 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'."

With the generated API and project guidance in context, an assistant can produce code in the following form:

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?;
}

The compiler, generated APIs, and runtime checks still remain the source of feedback when generated code is incomplete or incorrect.

Conclusion

Agentic coding benefits from a predictable, semantic API surface. Open-sourcing teaql-forge-rs lets developers inspect, run, and contribute to the Rust generation path behind that approach.

Visit the GitHub repository to inspect the code, open an issue, or submit a pull request.