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:

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.

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.