Skip to main content

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 Business Scenarios — move into relations, aggregates, pagination and optimistic mutations.
  4. Go Customization — add trusted policy, behavior, validation, audit sinks and providers without editing generated files.
  5. Go Debugging and Observability — capture safe SQL evidence and verify Query, Facet, Mutation, telemetry, audit, and tenant policy.

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.

Evidence boundary​

Use Cross-language Conformance Status for the committed capability/evidence snapshot. The provider table below is an explicitly dated campaign and does not make the old tested tag the current release or a permanent support commitment.

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)

Execution requires both non-empty Comment and Purpose. They may appear in either order and need not be adjacent; filters, selections, ordering, and pagination may appear between them. Use model-aware Assist for the current generated executable type.

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.

DatabaseDriver observed in acceptanceFeature status
PostgreSQLgithub.com/lib/pq 1.10.9PASS
MySQLgithub.com/go-sql-driver/mysql 1.7.1PASS
SQLitegithub.com/mattn/go-sqlite3 1.14.16PASS

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.

Learn through an Order​

Follow the Order tutorial for the retained SQLite example: startup, complete reads, an audited quantity/total edit, bounded pages and expected results. Use the Order API usage guide for result shapes and the native troubleshooting table for recovery. The coverage matrix keeps remaining writing and clean-machine packaging gaps visible. Existing runtime pending-release and generator-deployment qualifications remain in place.