Add emit_sql_as_comment option to Go code plugin

jasoncabot · andrewmbenton · commit de8ae610ebb2 · 2023-12-08T15:43:31.000-08:00
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.
diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -165,6 +165,8 @@ The `gen` mapping supports the following keys:
     that returns all valid enum values.
 - `build_tags`:
   - If set, add a `//go:build <build_tags>` directive at the beginning of each generated Go file.
+- `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`.
 - `json_tags_id_uppercase`:
   - If true, "Id" in json tags will be uppercase. If false, will be camelcase. Defaults to `false`
 - `json_tags_case_style`:
diff --git a/internal/codegen/golang/opts/options.go b/internal/codegen/golang/opts/options.go
@@ -42,6 +42,7 @@ type Options struct {
 	OmitSqlcVersion             bool              `json:"omit_sqlc_version,omitempty" yaml:"omit_sqlc_version"`
 	OmitUnusedStructs           bool              `json:"omit_unused_structs,omitempty" yaml:"omit_unused_structs"`
 	BuildTags                   string            `json:"build_tags,omitempty" yaml:"build_tags"`
+	EmitSqlAsComment            bool              `json:"emit_sql_as_comment,omitempty" yaml:"emit_sql_as_comment"`
 }
 
 type GlobalOptions struct {
diff --git a/internal/codegen/golang/result.go b/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)
diff --git a/internal/config/v_one.go b/internal/config/v_one.go
@@ -58,6 +58,7 @@ type v1PackageSettings struct {
 	OmitUnusedStructs         bool              `json:"omit_unused_structs,omitempty" yaml:"omit_unused_structs"`
 	Rules                     []string          `json:"rules" yaml:"rules"`
 	BuildTags                 string            `json:"build_tags,omitempty" yaml:"build_tags"`
+	EmitSqlAsComment          bool              `json:"emit_sql_as_comment,omitempty" yaml:"emit_sql_as_comment"`
 }
 
 func v1ParseConfig(rd io.Reader) (Config, error) {
@@ -166,6 +167,7 @@ func (c *V1GenerateSettings) Translate() Config {
 					OmitSqlcVersion:           pkg.OmitSqlcVersion,
 					OmitUnusedStructs:         pkg.OmitUnusedStructs,
 					BuildTags:                 pkg.BuildTags,
+					EmitSqlAsComment:          pkg.EmitSqlAsComment,
 				},
 			},
 			StrictFunctionChecks: pkg.StrictFunctionChecks,
diff --git a/internal/config/v_one.json b/internal/config/v_one.json
@@ -134,6 +134,9 @@
                     "build_tags": {
                         "type": "string"
                     },
+                    "emit_sql_as_comment": {
+                        "type": "boolean"
+                    },
                     "json_tags_case_style": {
                         "type": "string"
                     },
@@ -340,4 +343,4 @@
             }
         }
     }
-}
+}
diff --git a/internal/config/v_two.json b/internal/config/v_two.json
@@ -143,6 +143,9 @@
                                     "build_tags": {
                                         "type": "string"
                                     },
+                                    "emit_sql_as_comment": {
+                                        "type": "boolean"
+                                    },
                                     "json_tags_case_style": {
                                         "type": "string"
                                     },
diff --git a/internal/endtoend/testdata/emit_sql_as_comment/stdlib/go/db.go b/internal/endtoend/testdata/emit_sql_as_comment/stdlib/go/db.go
diff --git a/internal/endtoend/testdata/emit_sql_as_comment/stdlib/go/models.go b/internal/endtoend/testdata/emit_sql_as_comment/stdlib/go/models.go
diff --git a/internal/endtoend/testdata/emit_sql_as_comment/stdlib/go/query.sql.go b/internal/endtoend/testdata/emit_sql_as_comment/stdlib/go/query.sql.go
diff --git a/internal/endtoend/testdata/emit_sql_as_comment/stdlib/query.sql b/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;
diff --git a/internal/endtoend/testdata/emit_sql_as_comment/stdlib/sqlc.json b/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
+    }
+  ]
+}
diff --git a/internal/endtoend/testdata/process_plugin_disabled/gen/codegen.json b/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": "",

Original file line number	Diff line number	Diff line change
`@@ -42,6 +42,7 @@ type Options struct {`
`42`	`42`	OmitSqlcVersion bool `json:"omit_sqlc_version,omitempty" yaml:"omit_sqlc_version"`
`43`	`43`	OmitUnusedStructs bool `json:"omit_unused_structs,omitempty" yaml:"omit_unused_structs"`
`44`	`44`	BuildTags string `json:"build_tags,omitempty" yaml:"build_tags"`
	`45`	+ EmitSqlAsComment bool `json:"emit_sql_as_comment,omitempty" yaml:"emit_sql_as_comment"`
`45`	`46`	`}`
`46`	`47`
`47`	`48`	`type GlobalOptions struct {`
Original file line number	Diff line number	Diff line change
`@@ -134,6 +134,9 @@`
`134`	`134`	`"build_tags": {`
`135`	`135`	`"type": "string"`
`136`	`136`	`},`
	`137`	`+ "emit_sql_as_comment": {`
	`138`	`+ "type": "boolean"`
	`139`	`+ },`
`137`	`140`	`"json_tags_case_style": {`
`138`	`141`	`"type": "string"`
`139`	`142`	`},`
`@@ -340,4 +343,4 @@`
`340`	`343`	`}`
`341`	`344`	`}`
`342`	`345`	`}`
`343`		`-}`
	`346`	`+}`