feat(codegen): add emit_query_comments option for golang code generation

quantumsheep · quantumsheep · commit d2bf5b9bd4f5 · 2025-06-18T11:39:12.000+02:00
Signed-off-by: Nathanael DEMACON &lt;quantumsheep@users.noreply.github.com&gt;
diff --git a/bin/sqlc-dev b/bin/sqlc-dev
diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -167,6 +167,8 @@ The `gen` mapping supports the following keys:
     that returns all valid enum values.
 - `emit_sql_as_comment`:
   - If true, emits the SQL statement as a code-block comment above the generated function, appending to any existing comments. Defaults to `false`.
+- `emit_query_comments`:
+  - If true, emits the SQL query comments inside the generated query constants. Defaults to `false`.
 - `build_tags`:
   - If set, add a `//go:build <build_tags>` directive at the beginning of each generated Go file.
 - `initialisms`:
@@ -416,6 +418,7 @@ packages:
     emit_pointers_for_null_types: false
     emit_enum_valid_method: false
     emit_all_enum_values: false
+    emit_query_comments: false
     build_tags: "some_tag"
     json_tags_case_style: "camel"
     omit_unused_structs: false
diff --git a/internal/codegen/golang/gen.go b/internal/codegen/golang/gen.go
@@ -37,6 +37,7 @@ type tmplCtx struct {
 	EmitMethodsWithDBArgument bool
 	EmitEnumValidMethod       bool
 	EmitAllEnumValues         bool
+	EmitQueryComments         bool
 	UsesCopyFrom              bool
 	UsesBatch                 bool
 	OmitSqlcVersion           bool
@@ -181,6 +182,7 @@ func generate(req *plugin.GenerateRequest, options *opts.Options, enums []Enum,
 		EmitMethodsWithDBArgument: options.EmitMethodsWithDbArgument,
 		EmitEnumValidMethod:       options.EmitEnumValidMethod,
 		EmitAllEnumValues:         options.EmitAllEnumValues,
+		EmitQueryComments:         options.EmitQueryComments,
 		UsesCopyFrom:              usesCopyFrom(queries),
 		UsesBatch:                 usesBatch(queries),
 		SQLDriver:                 parseDriver(options.SqlPackage),
diff --git a/internal/codegen/golang/opts/options.go b/internal/codegen/golang/opts/options.go
@@ -24,6 +24,7 @@ type Options struct {
 	EmitPointersForNullTypes    bool              `json:"emit_pointers_for_null_types" yaml:"emit_pointers_for_null_types"`
 	EmitEnumValidMethod         bool              `json:"emit_enum_valid_method,omitempty" yaml:"emit_enum_valid_method"`
 	EmitAllEnumValues           bool              `json:"emit_all_enum_values,omitempty" yaml:"emit_all_enum_values"`
+	EmitQueryComments           bool              `json:"emit_query_comments,omitempty" yaml:"emit_query_comments"`
 	EmitSqlAsComment            bool              `json:"emit_sql_as_comment,omitempty" yaml:"emit_sql_as_comment"`
 	JsonTagsCaseStyle           string            `json:"json_tags_case_style,omitempty" yaml:"json_tags_case_style"`
 	Package                     string            `json:"package" yaml:"package"`
diff --git a/internal/codegen/golang/templates/pgx/batchCode.tmpl b/internal/codegen/golang/templates/pgx/batchCode.tmpl
@@ -7,6 +7,10 @@ var (
 {{range .GoQueries}}
 {{if eq (hasPrefix .Cmd ":batch") true }}
 const {{.ConstantName}} = {{$.Q}}-- name: {{.MethodName}} {{.Cmd}}
+{{if $.EmitQueryComments -}}
+{{range .Comments}}--{{.}}
+{{end -}}
+{{end -}}
 {{escape .SQL}}
 {{$.Q}}
 
diff --git a/internal/codegen/golang/templates/pgx/queryCode.tmpl b/internal/codegen/golang/templates/pgx/queryCode.tmpl
@@ -3,6 +3,10 @@
 {{if $.OutputQuery .SourceName}}
 {{if and (ne .Cmd ":copyfrom") (ne (hasPrefix .Cmd ":batch") true)}}
 const {{.ConstantName}} = {{$.Q}}-- name: {{.MethodName}} {{.Cmd}}
+{{if $.EmitQueryComments -}}
+{{range .Comments}}--{{.}}
+{{end -}}
+{{end -}}
 {{escape .SQL}}
 {{$.Q}}
 {{end}}
diff --git a/internal/codegen/golang/templates/stdlib/queryCode.tmpl b/internal/codegen/golang/templates/stdlib/queryCode.tmpl
@@ -2,6 +2,10 @@
 {{range .GoQueries}}
 {{if $.OutputQuery .SourceName}}
 const {{.ConstantName}} = {{$.Q}}-- name: {{.MethodName}} {{.Cmd}}
+{{if $.EmitQueryComments -}}
+{{range .Comments}}--{{.}}
+{{end -}}
+{{end -}}
 {{escape .SQL}}
 {{$.Q}}
 
diff --git a/internal/config/v_one.go b/internal/config/v_one.go
@@ -42,6 +42,7 @@ type v1PackageSettings struct {
 	EmitEnumValidMethod       bool              `json:"emit_enum_valid_method,omitempty" yaml:"emit_enum_valid_method"`
 	EmitAllEnumValues         bool              `json:"emit_all_enum_values,omitempty" yaml:"emit_all_enum_values"`
 	EmitSqlAsComment          bool              `json:"emit_sql_as_comment,omitempty" yaml:"emit_sql_as_comment"`
+	EmitQueryComments         bool              `json:"emit_query_comments,omitempty" yaml:"emit_query_comments"`
 	JSONTagsCaseStyle         string            `json:"json_tags_case_style,omitempty" yaml:"json_tags_case_style"`
 	SQLPackage                string            `json:"sql_package" yaml:"sql_package"`
 	SQLDriver                 string            `json:"sql_driver" yaml:"sql_driver"`
@@ -152,6 +153,7 @@ func (c *V1GenerateSettings) Translate() Config {
 					EmitEnumValidMethod:       pkg.EmitEnumValidMethod,
 					EmitAllEnumValues:         pkg.EmitAllEnumValues,
 					EmitSqlAsComment:          pkg.EmitSqlAsComment,
+					EmitQueryComments:         pkg.EmitQueryComments,
 					Package:                   pkg.Name,
 					Out:                       pkg.Path,
 					SqlPackage:                pkg.SQLPackage,
diff --git a/internal/config/v_one.json b/internal/config/v_one.json
@@ -134,6 +134,9 @@
                     "emit_sql_as_comment": {
                         "type": "boolean"
                     },
+                    "emit_query_comments": {
+                        "type": "boolean"
+                    },
                     "build_tags": {
                         "type": "string"
                     },
diff --git a/internal/config/v_two.json b/internal/config/v_two.json
@@ -143,6 +143,9 @@
                                     "emit_sql_as_comment": {
                                         "type": "boolean"
                                     },
+                                    "emit_query_comments": {
+                                        "type": "boolean"
+                                    },
                                     "build_tags": {
                                         "type": "string"
                                     },
diff --git a/internal/endtoend/testdata/emit_query_comments/stdlib/exec.json b/internal/endtoend/testdata/emit_query_comments/stdlib/exec.json
@@ -0,0 +1,3 @@
+{
+    "os": ["darwin", "linux"]
+}
diff --git a/internal/endtoend/testdata/emit_query_comments/stdlib/go/db.go b/internal/endtoend/testdata/emit_query_comments/stdlib/go/db.go
diff --git a/internal/endtoend/testdata/emit_query_comments/stdlib/go/models.go b/internal/endtoend/testdata/emit_query_comments/stdlib/go/models.go
diff --git a/internal/endtoend/testdata/emit_query_comments/stdlib/go/query.sql.go b/internal/endtoend/testdata/emit_query_comments/stdlib/go/query.sql.go
diff --git a/internal/endtoend/testdata/emit_query_comments/stdlib/query.sql b/internal/endtoend/testdata/emit_query_comments/stdlib/query.sql
@@ -0,0 +1,8 @@
+-- name: ListBar :many
+-- Lists all bars
+SELECT id FROM (
+  SELECT * FROM bar
+) bar;
+
+-- name: RemoveBar :exec
+DELETE FROM bar WHERE id = $1;
diff --git a/internal/endtoend/testdata/emit_query_comments/stdlib/schema.sql b/internal/endtoend/testdata/emit_query_comments/stdlib/schema.sql
@@ -0,0 +1 @@
+CREATE TABLE bar (id serial not null);
diff --git a/internal/endtoend/testdata/emit_query_comments/stdlib/sqlc.json b/internal/endtoend/testdata/emit_query_comments/stdlib/sqlc.json
@@ -0,0 +1,12 @@
+{
+  "version": "1",
+  "packages": [
+    {
+      "path": "go",
+      "name": "querytest",
+      "schema": "schema.sql",
+      "queries": "query.sql",
+      "emit_query_comments": true
+    }
+  ]
+}
