# Typed query generation

This separately installable module generates GORM query APIs from authored Go
structs. PostgreSQL is the only supported database. It does not generate models,
read database schemas or generate/apply schema migrations.

Tested compatibility: GORM **v1.31.2**, GEN **v0.3.29**, dbresolver **v1.6.2**.
GEN's default dbresolver v1.5.3 fails to compile against this GORM version
(`undefined: gorm.Stmt`); keep the explicit v1.6.2 requirement. GEN transitively
depends on other vendor drivers through upstream datatypes; these are not
Cicadel database integrations and do not change the PostgreSQL-only contract.

From this module:

```sh
go run ./example/generate
go test -race ./...
CICADEL_TEST_DATABASE_URL='postgres://.../disposable_database' go test -race ./...
```

Regeneration tests compare every generated query file byte-for-byte with the
committed example and run twice. PostgreSQL tests compile and execute typed
create, filter and update queries. A separate temporary consumer module resolves
this module through a local replacement and compiles/runs queries; this is local
installation verification, not evidence of a published release.

For local installation, require `github.com/fauzaanu/cicadel/contrib/querygen` at
`v0.0.0`, replacing it with this directory and replacing the framework with the
checkout. Run `go mod tidy`. No package release has been published yet.

Standard projects run `go run manage.go generatequeries` offline from registered `ModelOf` declarations. The generated `query/` directory is reviewed and committed. Existing custom hosts can register `querygen.New(querygen.Config{Models: registry.Models(),
OutputDirectory: "query"})` as an installed app. Run `querygen:generate` through
the host's management entrypoint, which must dispatch build commands before
opening a database. Explicit models work equally well without discovery.
The command writes generated queries to a dedicated output directory. Review
and commit generated files; remove obsolete generated files deliberately when
removing models. Do not store authored code in that directory.

Use `query.Use(db)` for instance-local query objects. The example deliberately
avoids GEN's package-global default database. Runtime models remain authoritative.
See the upstream [struct-based DAO configuration](https://gorm.io/gen/dao.html).

Catalog integration: pass `Config{Apps: installedApps, OutputDirectory: "query"}`
to consume app-owned `ModelOf[T]` declarations directly. `Apps` and `Models` are
mutually exclusive. Ownership and declared tables are validated before output;
tables must match GORM's default naming strategy, including `TableName` methods.
The factory snapshots declaration slices. Generation remains offline, does not
start apps, and never changes historical migration snapshots. Query model Go
names must be unique across selected apps and exported/importable.