Skip to main content

Go First Verification

A successful compile proves only that generated symbols line up. The first useful verification must cross the generated Request, UserContext, provider, real database, and audited mutation boundary.

Verification ladder​

1. Public module resolution​

Run from a clean module cache or temporary module at least once:

teaql_probe_cache=$(mktemp -d)
GOMODCACHE="$teaql_probe_cache" \
  go mod download -json github.com/teaql/teaql-golang@v0.1.0
GOMODCACHE="$teaql_probe_cache" \
  go list -m -json github.com/teaql/teaql-golang@v0.1.0

Confirm the resolved version is v0.1.0 and no workspace-level go.work or local replace supplied the runtime.

2. Generated contract​

go test ./...
go vet ./...
rg 'func .*Purpose|ExecuteForList|AuditAs|Save' generated/go-lib

Confirm that execution takes exactly one context argument, and that only the type returned by Purpose exposes terminals. Inspect q.go for plural names and the Request files for human/non-human predicate words.

3. Real SQLite smoke test​

Use a new database file for the test. Initialize context with the SQLite data service, trusted tenant and actor. Ensure schema, save one audited record, query it through the generated API, close the connection, reopen it, and query again.

The test passes only if the reopened provider returns the row. An in-memory repository or a persistence-free mock does not prove SQL integration.

func TestSQLiteRoundTrip(t *testing.T) {
    ctx := newSQLiteContext(t) // application-owned trusted assembly

    order := lib.Q.CustomerOrders().Comment("Create verification order").
        Purpose("Verify SQLite persistence").NewEntity(ctx)
    order.UpdateOrderNumber("VERIFY-10001")
    require.NoError(t, order.AuditAs("Create verification fixture").Save(ctx))

    rows, err := lib.Q.CustomerOrders().Comment("Read verification order").
        WithOrderNumberContaining("VERIFY-10001").Purpose("Verify persisted result").
        ExecuteForList(ctx)
    require.NoError(t, err)
    require.Len(t, rows, 1)
}

Treat method names above as a shape: use the exact generated names from your model.

4. Negative governance checks​

Prove these operations fail:

  • query without Purpose;
  • purpose with no non-empty comment;
  • execution with an uninitialized context;
  • save without AuditAs;
  • stale-version update;
  • dynamic JSON containing unknown fields or trusted-context overrides.

Some failures should be compile-time because the terminal is absent; the rest must be runtime errors. Never turn them into empty results or unfiltered queries.

5. SQL semantics​

For a representative list query, retain a masked SQL trace and verify stable ordering, bound parameters, native COUNT/SUM/GROUP BY, and partition/window SQL for exact per-parent Top-N. Compare page rows, record count, totals, and facets under the same active filter.

6. Regeneration​

Add a field to the model, regenerate from scratch, compile, and rerun the SQLite test. Review the generated diff instead of keeping a manual generated-file repair.

Minimum evidence​

Record toolchain/runtime/generator versions, model hash, generation command, build and test exit codes, database/provider version, masked native response, and relevant SQL shape. This turns “it ran once” into a reproducible baseline.

After this gate passes, continue with Go Customization and the business scenarios.