feat: Add emit_sql_as_comment option to Go code plugin (#2735)

This option adds the raw SQL query as a comment to the generated query function

This is useful when working in an IDE that displays comments over functions, you are able to glance at the actual SQL query that will be executed without having to lose context of where you are in the current file you are working on.

docs/reference/config.md

@@ -163,6 +163,8 @@ The `gen` mapping supports the following keys:
 - `emit_all_enum_values`:
   - If true, emit a function per enum type
     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`.
 - `build_tags`:
   - If set, add a `//go:build <build_tags>` directive at the beginning of each generated Go file.
 - `json_tags_id_uppercase`:

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"`
+	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"`
 	Out                         string            `json:"out" yaml:"out"`

internal/codegen/golang/result.go

@@ -199,14 +199,25 @@ func buildQueries(req *plugin.GenerateRequest, options *opts.Options, structs []
 			constantName = sdk.LowerTitle(query.Name)
 		}
 
+		comments := query.Comments
+		if options.EmitSqlAsComment {
+			if len(comments) == 0 {
+				comments = append(comments, query.Name)
+			}
+			comments = append(comments, " ")
+			for _, line := range strings.Split(query.Text, "\n") {
+				comments = append(comments, "  "+line)
+			}
+		}
+
 		gq := Query{
 			Cmd:          query.Cmd,
 			ConstantName: constantName,
 			FieldName:    sdk.LowerTitle(query.Name) + "Stmt",
 			MethodName:   query.Name,
 			SourceName:   query.Filename,
 			SQL:          query.Text,
-			Comments:     query.Comments,
+			Comments:     comments,
 			Table:        query.InsertIntoTable,
 		}
 		sqlpkg := parseDriver(options.SqlPackage)

internal/config/v_one.go

@@ -41,6 +41,7 @@ type v1PackageSettings 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"`
+	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"`
 	SQLPackage                string            `json:"sql_package" yaml:"sql_package"`
 	SQLDriver                 string            `json:"sql_driver" yaml:"sql_driver"`
@@ -150,6 +151,7 @@ func (c *V1GenerateSettings) Translate() Config {
 					EmitPointersForNullTypes:  pkg.EmitPointersForNullTypes,
 					EmitEnumValidMethod:       pkg.EmitEnumValidMethod,
 					EmitAllEnumValues:         pkg.EmitAllEnumValues,
+					EmitSqlAsComment:          pkg.EmitSqlAsComment,
 					Package:                   pkg.Name,
 					Out:                       pkg.Path,
 					SqlPackage:                pkg.SQLPackage,

internal/config/v_one.json

@@ -131,6 +131,9 @@
                     "emit_all_enum_values": {
                         "type": "boolean"
                     },
+                    "emit_sql_as_comment": {
+                        "type": "boolean"
+                    },
                     "build_tags": {
                         "type": "string"
                     },
@@ -340,4 +343,4 @@
             }
         }
     }
-}
+}

internal/config/v_two.json

@@ -140,6 +140,9 @@
                                     "emit_all_enum_values": {
                                         "type": "boolean"
                                     },
+                                    "emit_sql_as_comment": {
+                                        "type": "boolean"
+                                    },
                                     "build_tags": {
                                         "type": "string"
                                     },

internal/endtoend/testdata/emit_sql_as_comment/stdlib/query.sql

@@ -0,0 +1,10 @@
+CREATE TABLE bar (id serial not null);
+
+-- name: ListBar :many
+-- Lists all bars
+SELECT id FROM (
+  SELECT * FROM bar
+) bar;
+
+-- name: RemoveBar :exec
+DELETE FROM bar WHERE id = $1;

internal/endtoend/testdata/emit_sql_as_comment/stdlib/sqlc.json

@@ -0,0 +1,12 @@
+{
+  "version": "1",
+  "packages": [
+    {
+      "path": "go",
+      "name": "querytest",
+      "schema": "query.sql",
+      "queries": "query.sql",
+      "emit_sql_as_comment": true
+    }
+  ]
+}

internal/endtoend/testdata/process_plugin_disabled/gen/codegen.json

@@ -43,7 +43,8 @@
       "query_parameter_limit": 1,
       "output_batch_file_name": "",
       "json_tags_id_uppercase": false,
-      "omit_unused_structs": false
+      "omit_unused_structs": false,
+      "emit_sql_as_comment": false
     },
     "json": {
       "out": "",