Go Runtime Guide

For AI-assisted development, use the generated Assist contracts with the TeaQL Agent Kit Harness Engineering workflow.

The Go target generates entity packages, typed Request builders, Q and E facades, relation metadata, loaded-state expressions and graph persistence code. Generated public names use Go casing while preserving Java Request semantics.

Start here

Use this sequence for a new Go service:

1. Go Quick Start — model, generation layout, context assembly, first query and audited save.
2. Go First Verification — prove a real SQLite round trip, governance gates, SQL semantics and regeneration.
3. Go Customization — add trusted policy, behavior, validation, audit sinks and providers without editing generated files.
4. Go Business Scenarios — move into relations, aggregates, pagination and optimistic mutations.

The Go runtime is published as github.com/teaql/teaql-golang. The version table distinguishes its newest tag from the generator-selected dependency. The Quick Start covers both paths.

Runtime shape

Queries execute with one *runtime.UserContext. Providers and trusted request metadata are installed in that context; callers do not pass a second service or connection argument.

orders, err := lib.Q.CustomerOrders().
    Comment("Find orders awaiting review").
    Purpose("Prepare the authorized review queue").
    ExecuteForList(context)

The generated Purpose transition exposes execution only after a non-empty comment has already been supplied. Filters, selections, ordering and pagination may appear between comment and purpose.

Mutations require explicit audit intent:

saved, err := order.AuditAs("Approve reviewed order").Save(context)
_ = saved

Verified providers

The provider table is dated execution evidence from the earlier v0.1.4 acceptance campaign at commit 769358b, not a fresh test of today's tag.

Database	Driver observed in acceptance	Feature status
PostgreSQL	github.com/lib/pq 1.10.9	PASS
MySQL	github.com/go-sql-driver/mysql 1.7.1	PASS
SQLite	github.com/mattn/go-sqlite3 1.14.16	PASS

The Feature tests include root/parent/child filters, inclusive ranges, stable pagination, native COUNT/SUM/GROUP BY, relation hydration, exact per-parent Top-N, optimistic locking and both runtime audit paths.

Generation review checklist

After changing a model, evaluate, regenerate, and request focused model-aware Assist for changed APIs. Never construct a plural method name yourself. Keep the generated library unchanged and run go test ./... against the selected provider.