Start from Example

The fastest way to experience TeaQL is not by manually writing boilerplate code, but by leveraging an AI coding agent (such as Claude Code, Cursor, or Copilot) alongside the TeaQL Agent Kit.

1. The Quick Try (Vibe Coding)

Starting a new project is as simple as pasting a single prompt into your coding agent.

Copy the following text and let your agent run with it:

Follow the instructions from https://github.com/teaql/teaql-agent-kit.

Use Java to build a school management system with these domain concepts:

- Platform
- School
- School Type, with values Primary and Secondary

Create the semantic TeaQL model first, review it, then generate the Java TeaQL code. Generate both the Java library with gen-lib and the runnable Spring Boot application with gen-app. Build the project to verify it compiles.

Your coding agent will read the agent kit instructions, create a repository, and scaffold a fully working, type-safe enterprise application in minutes. It looks like magic, but the mechanics behind it are deeply rigorous.

2. What Happens Behind the Scenes?

While the prompt is simple, the underlying pipeline ensures that the generated application is robust, strictly typed, and ready for production. Here is the step-by-step breakdown of how natural language transforms into a secure workspace:

Step 1: Natural Language ➡️ Semantic Model File

The AI reads your natural language prompt and, guided by the rules in the Agent Kit, translates your domain concepts into a declarative TeaQL Semantic Model (e.g. .ksml files). Instead of immediately writing chaotic SQL or disjointed Java classes, the AI is forced to establish a rigorous, semantic truth of your domain.

Step 2: Model File ➡️ Generated Code Library

Once the semantic model is defined, the TeaQL CLI generator takes over. It reads the model and generates a heavily optimized, type-safe code library. This library contains all the query builders, entity DTOs, and runtime boundary definitions. Because this code is generated from a strict model, it eliminates the hallucinations and boilerplate errors typically introduced by AI coding tools.

Step 3: Library ➡️ Runnable Workspace

The generated library is then injected into a standard application template (e.g., a Java Spring Boot application). This results in a fully compiling, runnable workspace equipped with proper database providers, transactions, and necessary infrastructure.

Step 4: Continuous AI-Assisted Iteration

Now that the workspace is generated, it becomes the perfect playground. The AI coding agent (and you) can continue to work within this repository. Because the underlying data access layer is strict and generated by TeaQL, the AI has a solid, typed foundation. It can confidently add business logic, write tests, or expand the model without the risk of breaking database constraints or hallucinating invalid queries.

By starting with the TeaQL Agent Kit, you establish Semantic Guardrails from minute one, allowing AI to code at warp speed without compromising architectural integrity.

3. The Runtime Experience: Transparent and Self-Contained

A generated workspace is only useful if it runs smoothly. We designed the runtime experience to be completely self-contained, allowing developers (and AI agents) to stay focused on business logic without constantly switching contexts.

In-Memory Databases & Sample Data

The generated application boots up instantly using an in-memory database right out of the box (e.g., H2 for Java or in-memory SQLite for Rust). You don't need to configure Docker containers or set up database clusters just to test an idea. Furthermore, the runtime handles schema initialization and can inject realistic sample data automatically. You can start executing queries from second one.

No External SQL Tools Required

Because the domain model is strictly typed and the generated SDK provides full visibility, you never have to leave your IDE. You don't need external SQL GUI tools to poke around tables, write raw DDL, or verify your data structures. You can write your business logic and test cases directly in the workspace, with the compiler guaranteeing correctness.

Complete Transparency (Not a Black Box)

A common criticism of code generators and heavy ORMs is that they act as a "black box", obscuring inefficient database operations. TeaQL explicitly rejects this.

We provide transparent runtime observability. Every generated query, mutation, and data access is precisely logged. If you want to see exactly what SQL is being executed beneath the surface, the built-in audit trails expose it:

{
  "traceId": "tq-109384",
  "action": "FindSchool",
  "executionTimeMs": 4,
  "generatedSql": "SELECT id, name, type FROM school WHERE type = ? AND status = 'ACTIVE'",
  "parameters": ["Primary"]
}

To see how we track data provenance and guarantee observability, check out our deep dives on the Rust Audit Log Reference and Java Custom Audit Trails.

4. Deep Dive: The Uncompromising Ecosystem

The magic of the "Quick Try" is only possible because of the rigorous engineering beneath the surface. We solved the problem of context fragmentation (where developers and AI struggle to align the database, the domain model, and the runtime code) by designing a comprehensive ecosystem from the ground up.

If you want to understand the exact design decisions, architectural boundaries, and how we ensure absolute parity across languages, explore these deep dives:

• Architecture & Core Concepts: Discover why TeaQL is fundamentally different from a traditional ORM.
• E-Expressions & Type Reasoning: How we achieve safe, dynamic querying and strict type reasoning.
• AI Agentic Coding Files: The specific artifacts and guardrails designed specifically for AI consumption.

Language Ecosystem Comparison: Java vs. Rust

TeaQL is built to offer the exact same semantic guarantees across vastly different runtime environments. Here is how our ecosystem is implemented and tailored for both Java and Rust:

Concept / Component	Java Ecosystem	Rust Ecosystem
Generator / Scaffolding	gen-lib, gen-app (Spring Boot Native)	Rust Codegen, Cargo Build Scripts, Macros
Runtime Infrastructure	Spring Boot, IOC Container, Thread-local Context	Tokio (Async), Zero-cost abstractions
Database Providers	JDBC, Enterprise Connection Pools	Native Async Drivers (PostgreSQL, MySQL, SQLite)
Core Strengths	Enterprise web services, rich domain models, massive business logic	High-performance edge, agent memory, strict memory safety
Deep Dive Link	Spring Boot Integration	Rust Database Providers

By reading through these links, you'll see exactly how the top-tier engineering team behind TeaQL structured the platform so that your AI agents can simply "vibe code" on top of a rock-solid foundation.