schema/field: support annotating fields as deprecated (#4132)

schema/field/field.go

@@ -351,6 +351,17 @@ func (b *stringBuilder) Annotations(annotations ...schema.Annotation) *stringBui
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *stringBuilder) Deprecated(reason ...string) *stringBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *stringBuilder) Descriptor() *Descriptor {
 	if b.desc.Default != nil {
@@ -455,6 +466,17 @@ func (b *timeBuilder) Annotations(annotations ...schema.Annotation) *timeBuilder
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *timeBuilder) Deprecated(reason ...string) *timeBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *timeBuilder) Descriptor() *Descriptor {
 	if b.desc.Default != nil {
@@ -551,6 +573,17 @@ func (b *boolBuilder) Annotations(annotations ...schema.Annotation) *boolBuilder
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *boolBuilder) Deprecated(reason ...string) *boolBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *boolBuilder) Descriptor() *Descriptor {
 	b.desc.checkGoType(boolType)
@@ -720,6 +753,17 @@ func (b *bytesBuilder) SchemaType(types map[string]string) *bytesBuilder {
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *bytesBuilder) Deprecated(reason ...string) *bytesBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *bytesBuilder) Descriptor() *Descriptor {
 	if b.desc.Default != nil {
@@ -813,6 +857,14 @@ func (b *jsonBuilder) Default(v any) *jsonBuilder {
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *jsonBuilder) Deprecated(reason ...string) *jsonBuilder {
+	b.desc.Deprecated = true
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *jsonBuilder) Descriptor() *Descriptor {
 	return b.desc
@@ -901,6 +953,17 @@ func (b *sliceBuilder[T]) Default(v []T) *sliceBuilder[T] {
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *sliceBuilder[T]) Deprecated(reason ...string) *sliceBuilder[T] {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *sliceBuilder[T]) Descriptor() *Descriptor {
 	return b.desc
@@ -1058,6 +1121,17 @@ func (b *enumBuilder) GoType(ev EnumValues) *enumBuilder {
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *enumBuilder) Deprecated(reason ...string) *enumBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *enumBuilder) Descriptor() *Descriptor {
 	if b.desc.Info.RType != nil {
@@ -1160,6 +1234,17 @@ func (b *uuidBuilder) Annotations(annotations ...schema.Annotation) *uuidBuilder
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *uuidBuilder) Deprecated(reason ...string) *uuidBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *uuidBuilder) Descriptor() *Descriptor {
 	b.desc.checkGoType(valueScannerType)
@@ -1280,6 +1365,17 @@ func (b *otherBuilder) Annotations(annotations ...schema.Annotation) *otherBuild
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *otherBuilder) Deprecated(reason ...string) *otherBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *otherBuilder) Descriptor() *Descriptor {
 	b.desc.checkGoType(valueScannerType)
@@ -1291,25 +1387,27 @@ func (b *otherBuilder) Descriptor() *Descriptor {
 
 // A Descriptor for field configuration.
 type Descriptor struct {
-	Tag           string                  // struct tag.
-	Size          int                     // varchar size.
-	Name          string                  // field name.
-	Info          *TypeInfo               // field type info.
-	ValueScanner  any                     // custom field codec.
-	Unique        bool                    // unique index of field.
-	Nillable      bool                    // nillable struct field.
-	Optional      bool                    // nullable field in database.
-	Immutable     bool                    // create only field.
-	Default       any                     // default value on create.
-	UpdateDefault any                     // default value on update.
-	Validators    []any                   // validator functions.
-	StorageKey    string                  // sql column or gremlin property.
-	Enums         []struct{ N, V string } // enum values.
-	Sensitive     bool                    // sensitive info string field.
-	SchemaType    map[string]string       // override the schema type.
-	Annotations   []schema.Annotation     // field annotations.
-	Comment       string                  // field comment.
-	Err           error
+	Tag              string                  // struct tag.
+	Size             int                     // varchar size.
+	Name             string                  // field name.
+	Info             *TypeInfo               // field type info.
+	ValueScanner     any                     // custom field codec.
+	Unique           bool                    // unique index of field.
+	Nillable         bool                    // nillable struct field.
+	Optional         bool                    // nullable field in database.
+	Immutable        bool                    // create only field.
+	Default          any                     // default value on create.
+	UpdateDefault    any                     // default value on update.
+	Validators       []any                   // validator functions.
+	StorageKey       string                  // sql column or gremlin property.
+	Enums            []struct{ N, V string } // enum values.
+	Sensitive        bool                    // sensitive info string field.
+	SchemaType       map[string]string       // override the schema type.
+	Annotations      []schema.Annotation     // field annotations.
+	Comment          string                  // field comment.
+	Deprecated       bool                    // mark the field as deprecated.
+	DeprecatedReason string                  // deprecation reason.
+	Err              error
 }
 
 func (d *Descriptor) goType(typ any) {

schema/field/internal/numeric.tmpl

@@ -10,6 +10,7 @@ package field
 import (
 	"errors"
 	"reflect"
+	"strings"
 
 	"entgo.io/ent/schema"
 )
@@ -228,6 +229,17 @@ func (b *{{ $builder }}) Annotations(annotations ...schema.Annotation) *{{ $buil
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *{{ $builder }}) Deprecated(reason ...string) *{{ $builder }} {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *{{ $builder }}) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -409,6 +421,17 @@ func (b *{{ $builder }}) Annotations(annotations ...schema.Annotation) *{{ $buil
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *{{ $builder }}) Deprecated(reason ...string) *{{ $builder }} {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *{{ $builder }}) Descriptor() *Descriptor {
 	b.desc.checkGoType({{ $t }}Type)

schema/field/numeric.go

@@ -9,6 +9,7 @@ package field
 import (
 	"errors"
 	"reflect"
+	"strings"
 
 	"entgo.io/ent/schema"
 )
@@ -289,6 +290,17 @@ func (b *intBuilder) Annotations(annotations ...schema.Annotation) *intBuilder {
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *intBuilder) Deprecated(reason ...string) *intBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *intBuilder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -466,6 +478,17 @@ func (b *uintBuilder) Annotations(annotations ...schema.Annotation) *uintBuilder
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *uintBuilder) Deprecated(reason ...string) *uintBuilder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *uintBuilder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -653,6 +676,17 @@ func (b *int8Builder) Annotations(annotations ...schema.Annotation) *int8Builder
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *int8Builder) Deprecated(reason ...string) *int8Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *int8Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -840,6 +874,17 @@ func (b *int16Builder) Annotations(annotations ...schema.Annotation) *int16Build
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *int16Builder) Deprecated(reason ...string) *int16Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *int16Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -1027,6 +1072,17 @@ func (b *int32Builder) Annotations(annotations ...schema.Annotation) *int32Build
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *int32Builder) Deprecated(reason ...string) *int32Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *int32Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -1214,6 +1270,17 @@ func (b *int64Builder) Annotations(annotations ...schema.Annotation) *int64Build
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *int64Builder) Deprecated(reason ...string) *int64Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *int64Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -1391,6 +1458,17 @@ func (b *uint8Builder) Annotations(annotations ...schema.Annotation) *uint8Build
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *uint8Builder) Deprecated(reason ...string) *uint8Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *uint8Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -1568,6 +1646,17 @@ func (b *uint16Builder) Annotations(annotations ...schema.Annotation) *uint16Bui
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *uint16Builder) Deprecated(reason ...string) *uint16Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *uint16Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -1745,6 +1834,17 @@ func (b *uint32Builder) Annotations(annotations ...schema.Annotation) *uint32Bui
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *uint32Builder) Deprecated(reason ...string) *uint32Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *uint32Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -1922,6 +2022,17 @@ func (b *uint64Builder) Annotations(annotations ...schema.Annotation) *uint64Bui
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *uint64Builder) Deprecated(reason ...string) *uint64Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *uint64Builder) Descriptor() *Descriptor {
 	if b.desc.Default != nil || b.desc.UpdateDefault != nil {
@@ -2100,6 +2211,17 @@ func (b *float64Builder) Annotations(annotations ...schema.Annotation) *float64B
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *float64Builder) Deprecated(reason ...string) *float64Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *float64Builder) Descriptor() *Descriptor {
 	b.desc.checkGoType(float64Type)
@@ -2262,6 +2384,17 @@ func (b *float32Builder) Annotations(annotations ...schema.Annotation) *float32B
 	return b
 }
 
+// Deprecated marks the field as deprecated. Deprecated fields are not
+// selected by default in queries, and their struct fields are annotated
+// with `deprecated` in the generated code.
+func (b *float32Builder) Deprecated(reason ...string) *float32Builder {
+	b.desc.Deprecated = true
+	if len(reason) > 0 {
+		b.desc.DeprecatedReason = strings.Join(reason, " ")
+	}
+	return b
+}
+
 // Descriptor implements the ent.Field interface by returning its descriptor.
 func (b *float32Builder) Descriptor() *Descriptor {
 	b.desc.checkGoType(float32Type)