Skip to main content

Cookbook

The cookbook collects practical tasks and points each one to the best existing TeaQL docs. It is intentionally more task-oriented than a reference manual.

Recipe Verification Status​

The status describes maintained evidence for the exact recipe, not whether the underlying TeaQL feature or provider exists.

RecipeCurrent evidenceRemaining verification
Audit-Ready MutationRust 4.1.1/SQLite mutation executed with audit_as; Java shape reviewed only.Java execution; audit-sink payload, rollback, and masking assertions.
Multi-Tenant Query BoundaryDesign and contract reviewed; method names are explicitly illustrative.Two-tenant Java and Rust integration tests, including ID and nested-relation paths.
Switch Database ProviderRust SQLite 4.1.1 baseline executed; provider inventory reviewed.An actual provider-to-provider migration and all non-SQLite combinations.
Paginated Business QueryJava request shape and intent order reviewed.Current generated-workspace execution, boundary pages, stable ordering, and tenant scope.
Association LoadingJava selection shape and intent order reviewed; relation names are illustrative.SQL/query-count evidence and nested scope tests in a current generated workspace.
Statistics QueryJava aggregation shape and intent order reviewed.Provider-backed totals, grouping/null behavior, numeric types, and execution plan.
Dynamic JSON QueryJava parser and generated request shape reviewed.Allowlist, tenant-isolation, resource-limit, chain-path, and provider-backed integration tests.
Configure a Custom ID GeneratorJava 1.525-RELEASE JAR and Rust 4.1.1 source contracts reviewed; generated Rust SQLite registration observed.Custom strategy, Java persistence, multi-node collision, retry, restart, and failover tests.
Configure Read/Write SplittingJava 1.525-RELEASE registry and executor contracts reviewed.Distinct primary/replica topology, lag, transaction, failover, and tenant-route integration tests.
Sensitive Field HandlingEvaluator finding and regenerated audit_mask_fields metadata verified.Runtime safe-sink, response, debug/raw-log, export, and error-path assertions.
MemoryRepository TestsRuntime/provider boundary reviewed; no parity claim.Current generated memory test plus explicit comparison with SQLite/provider tests.
Debug Generated Code SafelyProcedure applied to the recorded Java blockers and Rust generated-workspace findings.Repeat for each newly reproduced failure and preserve its report/evidence.
Internal Team ModeOrganizational responsibility model reviewed; no team-performance study.Validate roles, generated API boundaries, and delivery outcomes in an actual project.
Distributed Delivery ModeOrganizational responsibility model reviewed; no distributed-delivery study.Validate ownership, review gates, API boundaries, and delivery outcomes in an actual project.

The dated commands and component versions live in Verification Evidence. “Reviewed” is not equivalent to “executed” or “supported.” The shorter task pointers below are discovery aids; follow their linked compatibility and verification pages before production adoption.

Task Recipes​

Build an Order List Page​

Use nested selection, filtering, pagination, and count/statistics in one generated query expression.

Start with:

Count Orders by Status​

Use generated count and group-by methods:

Q.orders().count()
    .groupByOrderStatus()
    .comment("Query orders").purpose("Load data")
    .executeForList(ctx);

Read:

Load Top 3 Items for Each Order​

Use nested list selection with limit:

Q.ordersWithId()
    .selectLineItemList(
        Q.lineItemsWithId()
            .selectImageURL()
            .limit(3)
    );

Read:

Query Objects That Have Children​

Use generated list-existence methods when available, such as hasOrders().

Read:

Query Objects That Have No Children​

Use generated negative list-existence methods when available, or wrap the reusable business constraint in a query util method.

Read:

Generate Dashboard Statistics​

Use count, sum, avg, min, max, and groupBy methods generated from the domain model.

Read:

Add Transaction Support​

Keep transaction boundaries in the service/runtime layer rather than scattering them through controllers.

Read:

Add Cache Support​

Put cache behavior behind runtime/context customization.

Read:

Use TeaQL with PostgreSQL​

For Java data-service concepts, start with:

For Rust providers, use:

Use TeaQL with MySQL​

For Java multi-database notes, start with:

For Rust providers, use:

Use TeaQL with SQLite​

The maintained Rust Golden Path executes teaql-provider-sqlite 4.1.1 with rusqlite 0.32. Qualify concurrency, transaction, database-version, and deployment requirements separately. Older SQLx/rusqlite provider names in historical content are not current crate names.

Read:

Use MemoryRepository for Tests​

Evaluate MemoryRepository for fast no-database tests, while retaining a provider-backed test layer. The current Golden Path does not establish parity between memory and SQL execution.

Read:

Use TeaQL as Agent Memory​

Use generated business APIs to keep agent memory structured, queryable, and provider-backed.

Read: