Skip to main content

Using TeaQL with AI Coding Tools

AI coding tools are effective when they can compose stable APIs. They become risky when they must infer SQL, relationship loading, field names, permission rules, and transaction behavior from scattered implementation code.

TeaQL gives AI tools a generated business API layer:

  • Generated names come from the domain model.
  • Query shape is explicit in Q expressions.
  • Runtime policy is centralized in context/provider code.
  • Storage details stay behind repositories and providers.

Why AI Agents Should Not Write SQL Directly​

Direct SQL requires the AI to understand:

  • Physical table and column names
  • Joins and relationship cardinality
  • Null behavior and edge cases
  • Tenant and permission filters
  • Pagination and sorting rules
  • Transaction boundaries
  • Database-specific dialect differences

TeaQL exposes business intent instead:

Q.orders()
    .filterByMerchant(ctx.getMerchant())
    .count()
    .groupByTaskStatus()
    .executeForList(ctx);

This is easier for AI to reuse, review, and modify.

Prompting Pattern​

Give the AI a small set of generated API examples and ask it to compose from those examples instead of inventing persistence code.

Use TeaQL Q APIs for all reads.
Do not write SQL directly.
Use UserContext for runtime execution.
Keep query fragments reusable in util methods.
Use generated select/filter/count/group methods when available.
  1. Model the domain.
  2. Generate the API package.
  3. Give AI tools the relevant Q/E examples.
  4. Ask AI to implement application logic using generated APIs.
  5. Keep runtime policy in UserContext or provider modules.
  6. Review generated code for business intent, not SQL mechanics.

Reuse Existing Docs​

These existing docs are the best reference set for AI-assisted TeaQL coding:

Good AI Tasks​

Good fits:

  • Build an order list page query.
  • Count orders by status.
  • Load top child rows for each parent.
  • Add service methods around reusable query fragments.
  • Convert handwritten query code into generated API calls.
  • Create tests with MemoryRepository.

Riskier tasks:

  • Inventing model fields that do not exist.
  • Bypassing tenant or permission filters.
  • Writing raw SQL instead of generated APIs.
  • Mixing provider-specific details into business services.