fix #236: New fieldopt "noexpand" to treat a nested struct as one column

Author: huandu

README.md

@@ -272,6 +272,7 @@ type ATable struct {
     unexported int                                       // Unexported field is not visible to Struct.
     Quoted     string `db:"quoted" fieldopt:"withquote"` // Add quote to the field using back quote or double quote. See `Flavor#Quote`.
     Empty      uint   `db:"empty" fieldopt:"omitempty"`  // Omit the field in UPDATE if it is a nil or zero value.
+    Payload    Meta   `db:"payload" fieldopt:"noexpand"` // Treat a nested struct as one column instead of expanding it.
 
     // The `omitempty` can be written as a function.
     // In this case, omit empty field `Tagged` when UPDATE for tag `tag1` and `tag3` but not `tag2`.
@@ -311,6 +312,27 @@ fmt.Println(sql)
 // SELECT post.id, post.text, comment.body FROM posts post JOIN comments comment ON post.id = comment.post_id
 ```
 
+If a nested struct should stay as a single column, add `fieldopt:"noexpand"` to opt out of the automatic expansion. This is useful for JSON columns scanned into Go structs by the database driver.
+
+```go
+type Payload struct {
+    Key string `json:"key"`
+}
+
+type Row struct {
+    ID      string  `db:"id"`
+    Payload Payload `db:"payload" fieldopt:"noexpand"`
+}
+
+st := sqlbuilder.NewStruct(new(Row)).For(sqlbuilder.PostgreSQL)
+sql, _ := st.SelectFrom("events e").Build()
+
+fmt.Println(sql)
+
+// Output:
+// SELECT e.id, e.payload FROM events e
+```
+
 For detailed instructions on utilizing `Struct`, refer to the [examples](https://pkg.go.dev/github.com/huandu/go-sqlbuilder#Struct).
 
 Furthermore, `Struct` can be employed as a zero-configuration ORM. Unlike most ORM implementations that necessitate preliminary configurations for database connectivity, `Struct` operates without any configuration, functioning seamlessly with any SQL driver compatible with `database/sql`. `Struct` does not invoke any `database/sql` APIs; it solely generates the appropriate SQL statements with arguments for `DB#Query`/`DB#Exec` or an array of struct field addresses for `Rows#Scan`/`Row#Scan`.

struct.go

@@ -31,6 +31,7 @@ var (
 const (
 	fieldOptWithQuote = "withquote"
 	fieldOptOmitEmpty = "omitempty"
+	fieldOptNoExpand  = "noexpand"
 
 	optName   = "optName"
 	optParams = "optParams"

struct_test.go

@@ -368,6 +368,41 @@ func TestStructInsertIntoTaggedNestedFieldRemainsScalar(t *testing.T) {
 	a.Equal(args, []interface{}{rec.DecID, rec.LiabVar, rec.AssetVars})
 }
 
+func TestStructTaggedNestedFieldNoExpand(t *testing.T) {
+	type varRec struct {
+		ChnlPH string `json:"ph"`
+		ExpVK  int64  `json:"vk"`
+	}
+
+	type decRec struct {
+		DecID   string `db:"dec_id"`
+		LiabVar varRec `db:"liab_var" fieldopt:"noexpand"`
+	}
+
+	a := assert.New(t)
+	st := NewStruct(new(decRec)).For(PostgreSQL)
+	rec := &decRec{
+		DecID:   "dec-1",
+		LiabVar: varRec{ChnlPH: "ph", ExpVK: 7},
+	}
+
+	selectSQL, selectArgs := st.SelectFrom("decs d").Build()
+	a.Equal(selectSQL, "SELECT d.dec_id, d.liab_var FROM decs d")
+	a.Equal(selectArgs, nil)
+	a.Equal(st.Columns(), []string{"dec_id", "liab_var"})
+	a.Equal(st.Values(rec), []interface{}{rec.DecID, rec.LiabVar})
+
+	updateSQL, updateArgs := st.Update("decs", rec).Build()
+	a.Equal(updateSQL, "UPDATE decs SET dec_id = $1, liab_var = $2")
+	a.Equal(updateArgs, []interface{}{rec.DecID, rec.LiabVar})
+
+	var scanned decRec
+	addrs := st.Addr(&scanned)
+	a.Equal(len(addrs), 2)
+	a.Equal(addrs[0], &scanned.DecID)
+	a.Equal(addrs[1], &scanned.LiabVar)
+}
+
 func TestStructInsertIntoAnonymousFieldHasNoPrefix(t *testing.T) {
 	type embedded struct {
 		ID   string `db:"id"`

structfields.go

@@ -42,6 +42,12 @@ type structField struct {
 	omitEmptyTags omitEmptyTagMap
 }
 
+type structFieldOptions struct {
+	isQuoted      bool
+	omitEmptyTags omitEmptyTagMap
+	noExpand      bool
+}
+
 type structFieldsParser func() *structFields
 
 func makeDefaultFieldsParser(t reflect.Type) structFieldsParser {
@@ -101,16 +107,18 @@ func (sfs *structFields) parse(t reflect.Type, mapper FieldMapperFunc, prefix st
 			continue
 		}
 
-		if shouldExpandTaggedStructField(field.Type, dbtag) {
-			structField := makeStructField(field, alias, dbtag, mapper, prefix, index, i)
+		fieldOpts := parseStructFieldOptions(field)
+
+		if shouldExpandTaggedStructField(field.Type, dbtag, fieldOpts) {
+			structField := makeStructField(field, alias, dbtag, mapper, fieldOpts, prefix, index, i)
 			if allowInsert {
 				sfs.addInsertField(structField)
 			}
 			sfs.parse(dereferencedType(field.Type), mapper, dbtag+".", appendFieldIndex(index, i), false)
 			continue
 		}
 
-		structField := makeStructField(field, alias, dbtag, mapper, prefix, index, i)
+		structField := makeStructField(field, alias, dbtag, mapper, fieldOpts, prefix, index, i)
 		if allowInsert {
 			sfs.addField(structField)
 		} else {
@@ -124,7 +132,7 @@ func (sfs *structFields) parse(t reflect.Type, mapper FieldMapperFunc, prefix st
 	}
 }
 
-func makeStructField(field reflect.StructField, alias, dbtag string, mapper FieldMapperFunc, prefix string, index []int, fieldIndex int) *structField {
+func makeStructField(field reflect.StructField, alias, dbtag string, mapper FieldMapperFunc, fieldOpts structFieldOptions, prefix string, index []int, fieldIndex int) *structField {
 	if alias == "" {
 		alias = field.Name
 		if mapper != nil {
@@ -136,10 +144,29 @@ func makeStructField(field reflect.StructField, alias, dbtag string, mapper Fiel
 		alias = prefix + alias
 	}
 
+	fieldas := field.Tag.Get(FieldAs)
+	fieldtag := field.Tag.Get(FieldTag)
+	tags := splitTags(fieldtag)
+
+	return &structField{
+		Name:          field.Name,
+		Alias:         alias,
+		As:            fieldas,
+		Tags:          tags,
+		IsQuoted:      fieldOpts.isQuoted,
+		DBTag:         dbtag,
+		Field:         field,
+		Index:         appendFieldIndex(index, fieldIndex),
+		omitEmptyTags: fieldOpts.omitEmptyTags,
+	}
+}
+
+func parseStructFieldOptions(field reflect.StructField) structFieldOptions {
 	fieldopt := field.Tag.Get(FieldOpt)
 	opts := optRegex.FindAllString(fieldopt, -1)
-	isQuoted := false
-	omitEmptyTags := omitEmptyTagMap{}
+	fieldOpts := structFieldOptions{
+		omitEmptyTags: omitEmptyTagMap{},
+	}
 
 	for _, opt := range opts {
 		optMap := getOptMatchedMap(opt)
@@ -149,29 +176,18 @@ func makeStructField(field reflect.StructField, alias, dbtag string, mapper Fiel
 			tags := getTagsFromOptParams(optMap[optParams])
 
 			for _, tag := range tags {
-				omitEmptyTags[tag] = struct{}{}
+				fieldOpts.omitEmptyTags[tag] = struct{}{}
 			}
 
 		case fieldOptWithQuote:
-			isQuoted = true
+			fieldOpts.isQuoted = true
+
+		case fieldOptNoExpand:
+			fieldOpts.noExpand = true
 		}
 	}
 
-	fieldas := field.Tag.Get(FieldAs)
-	fieldtag := field.Tag.Get(FieldTag)
-	tags := splitTags(fieldtag)
-
-	return &structField{
-		Name:          field.Name,
-		Alias:         alias,
-		As:            fieldas,
-		Tags:          tags,
-		IsQuoted:      isQuoted,
-		DBTag:         dbtag,
-		Field:         field,
-		Index:         appendFieldIndex(index, fieldIndex),
-		omitEmptyTags: omitEmptyTags,
-	}
+	return fieldOpts
 }
 
 func (sfs *structFields) addField(field *structField) {
@@ -206,8 +222,8 @@ func shouldExpandAnonymousStructField(t reflect.Type) bool {
 	return canExpandStructType(t)
 }
 
-func shouldExpandTaggedStructField(t reflect.Type, dbtag string) bool {
-	return dbtag != "" && canExpandStructType(t)
+func shouldExpandTaggedStructField(t reflect.Type, dbtag string, fieldOpts structFieldOptions) bool {
+	return dbtag != "" && !fieldOpts.noExpand && canExpandStructType(t)
 }
 
 func canExpandStructType(t reflect.Type) bool {