常见问题 (FAQ)
问题
How to create an entity from a struct T?
How to create a struct (or a mutation) level validator?
How to write an audit-log extension?
How to write custom predicates?
How to add custom predicates to the codegen assets?
How to define a network address field in PostgreSQL?
How to customize time fields to type DATETIME in MySQL?
How to use a custom generator of IDs?
How to use a custom XID globally unique ID?
How to define a spatial data type field in MySQL?
How to extend the generated models?
How to extend the generated builders?
How to store Protobuf objects in a BLOB column?
How to add CHECK constraints to table?
How to define a custom precision numeric field?
How to configure two or more DB to separate read and write?
How to change the character set and/or collation of a MySQL table?
How to configure json.Marshal to inline the edges keys in the top level object?
回答
如何通过结构体 T 创建一个实体？
构建器不支持从给定的结构体 T 中设置实体字段 (或关系)。 原因是，在更新数据库时无法区分空值和实际的0值 (例如， &ent.T{Age: 0, Name: ""}). 设置这些值的时候，可能在数据中写入错误的值或者更新不必要的列。
然而， 外部模板 选项能让你通过添加自定义逻辑，来扩展默认代码生成资源。 例如使用以下模板，可以为每个创建构造器生成一个方法，接受一个结构体作为输入并配置构造器：
{{ range $n := $.Nodes }}
{{ $builder := $n.CreateName }}
{{ $receiver := receiver $builder }}
func ({{ $receiver }} *{{ $builder }}) Set{{ $n.Name }}(input *{{ $n.Name }}) *{{ $builder }} {
{{- range $f := $n.Fields }}
{{- $setter := print "Set" $f.StructField }}
{{ $receiver }}.{{ $setter }}(input.{{ $f.StructField }})
{{- end }}
return {{ $receiver }}
}
{{ end }}
如何创建一个更变时校验器？
要实现一个更变时校验器， 你既可以使用 schema hooks 来验证应用于一个实体类型的更变， 也可以使用 transaction hooks 来验证应用于多个实体类型的更变 (好比一次GraphQL更变)。 举个例子：
// VersionHook是一个假的例子，它可以验证 "version" 字段
// 在每次更新时增加1。 注意，这只是一个假的例子，
// 且并不保证数据库的一致性。
func VersionHook() ent.Hook {
type OldSetVersion interface {
SetVersion(int)
Version() (int, bool)
OldVersion(context.Context) (int, error)
}
return func(next ent.Mutator) ent.Mutator {
return ent.MutateFunc(func(ctx context.Context, m ent.Mutation) (ent.Value, error) {
ver, ok := m.(OldSetVersion)
if !ok {
return next.Mutate(ctx, m)
}
oldV, err := ver.OldVersion(ctx)
if err != nil {
return nil, err
}
curV, exists := ver.Version()
if !exists {
return nil, fmt.Errorf("version field is required in update mutation")
}
if curV != oldV+1 {
return nil, fmt.Errorf("version field must be incremented by 1")
}
// 应添加一个SQL断言，验证 "version" 列是否等于 "oldV"
// (确保它在更变过程中没有被其他人改变)
return next.Mutate(ctx, m)
})
}
}
如何编写一个审计日志的扩展？
编写此扩展的推荐方式是使用 ent.Mixin。 使用 Fields 选项来为所有引入该 mixed-schema 的 Schema 设置相同的字段，并使用 Hooks 选项来为所有正在使用这些 Schema 的变更操作附加一个钩子。 下面是一个例子，基于 代码仓库 Issue 追踪器 中的讨论。
// AuditMixin 实现了 ent.Mixin，
// 用于 schema 包内通用的审计日志功能。
type AuditMixin struct{
mixin.Schema
}
// Fields of the AuditMixin.
func (AuditMixin) Fields() []ent.Field {
return []ent.Field{
field.Time("created_at").
Immutable().
Default(time.Now),
field.Int("created_by").
Optional(),
field.Time("updated_at").
Default(time.Now).
UpdateDefault(time.Now),
field.Int("updated_by").
Optional(),
}
}
// AuditMixin 的钩子
func (AuditMixin) Hooks() []ent.Hook {
return []ent.Hook{
hooks.AuditHook,
}
}
// AuditHook 是审计日志钩子的示例
func AuditHook(next ent.Mutator) ent.Mutator {
// AuditLogger 声明了所有嵌入 AuditLog mixin 的
// Schema 更变所共有的方法。 若变量 "existence "为真，
// 则该字段存在于此更变中 (例如被其它的钩子设置过)。
type AuditLogger interface {
SetCreatedAt(time.Time)
CreatedAt() (value time.Time, exists bool)
SetCreatedBy(int)
CreatedBy() (id int, exists bool)
SetUpdatedAt(time.Time)
UpdatedAt() (value time.Time, exists bool)
SetUpdatedBy(int)
UpdatedBy() (id int, exists bool)
}
return ent.MutateFunc(func(ctx context.Context, m ent.Mutation) (ent.Value, error) {
ml, ok := m.(AuditLogger)
if !ok {
return nil, fmt.Errorf("unexpected audit-log call from mutation type %T", m)
}
usr, err := viewer.UserFromContext(ctx)
if err != nil {
return nil, err
}
switch op := m.Op(); {
case op.Is(ent.OpCreate):
ml.SetCreatedAt(time.Now())
if _, exists := ml.CreatedBy(); !exists {
ml.SetCreatedBy(usr.ID)
}
case op.Is(ent.OpUpdateOne | ent.OpUpdate):
ml.SetUpdatedAt(time.Now())
if _, exists := ml.UpdatedBy(); !exists {
ml.SetUpdatedBy(usr.ID)
}
}
return next.Mutate(ctx, m)
})
}
如何编写自定义的断言？
用户可以在执行查询之前可以提供自定义的断言。 例如：
pets := client.Pet.
Query().
Where(predicate.Pet(func(s *sql.Selector) {
s.Where(sql.InInts(pet.OwnerColumn, 1, 2, 3))
})).
AllX(ctx)
users := client.User.
Query().
Where(predicate.User(func(s *sql.Selector) {
s.Where(sqljson.ValueContains(user.FieldTags, "tag"))
})).
AllX(ctx)
更多例子，请到 断言 页面，或者在代码仓库Issue跟踪器中搜索更多的高级例子，如 issue-842。
How to add custom predicates to the codegen assets?
The template option enables the capability for extending or overriding the default codegen assets. In order to generate a type-safe predicate for the example above, use the template option for doing it as follows:
{{/* A template that adds the "<F>Glob" predicate for all string fields. */}}
{{ define "where/additional/strings" }}
{{ range $f := $.Fields }}
{{ if $f.IsString }}
{{ $func := print $f.StructField "Glob" }}
// {{ $func }} applies the Glob predicate on the {{ quote $f.Name }} field.
func {{ $func }}(pattern string) predicate.{{ $.Name }} {
return predicate.{{ $.Name }}(func(s *sql.Selector) {
s.Where(sql.P(func(b *sql.Builder) {
b.Ident(s.C({{ $f.Constant }})).WriteString(" glob" ).Arg(pattern)
}))
})
}
{{ end }}
{{ end }}
{{ end }}
How to define a network address field in PostgreSQL?
The GoType and the SchemaType options allow users to define database-specific fields. For example, in order to define a macaddr field, use the following configuration:
func (T) Fields() []ent.Field {
return []ent.Field{
field.String("mac").
GoType(&MAC{}).
SchemaType(map[string]string{
dialect.Postgres: "macaddr",
}).
Validate(func(s string) error {
_, err := net.ParseMAC(s)
return err
}),
}
}
// MAC represents a physical hardware address.
type MAC struct {
net.HardwareAddr
}
// Scan implements the Scanner interface.
func (m *MAC) Scan(value any) (err error) {
switch v := value.(type) {
case nil:
case []byte:
m.HardwareAddr, err = net.ParseMAC(string(v))
case string:
m.HardwareAddr, err = net.ParseMAC(v)
default:
err = fmt.Errorf("unexpected type %T", v)
}
return
}
// Value implements the driver Valuer interface.
func (m MAC) Value() (driver.Value, error) {
return m.HardwareAddr.String(), nil
}
Note that, if the database doesn't support the macaddr type (e.g. SQLite on testing), the field fallback to its native type (i.e. string).
inet example:
func (T) Fields() []ent.Field {
return []ent.Field{
field.String("ip").
GoType(&Inet{}).
SchemaType(map[string]string{
dialect.Postgres: "inet",
}).
Validate(func(s string) error {
if net.ParseIP(s) == nil {
return fmt.Errorf("invalid value for ip %q", s)
}
return nil
}),
}
}
// Inet represents a single IP address
type Inet struct {
net.IP
}
// Scan implements the Scanner interface
func (i *Inet) Scan(value any) (err error) {
switch v := value.(type) {
case nil:
case []byte:
if i.IP = net.ParseIP(string(v)); i.IP == nil {
err = fmt.Errorf("invalid value for ip %q", v)
}
case string:
if i.IP = net.ParseIP(v); i.IP == nil {
err = fmt.Errorf("invalid value for ip %q", v)
}
default:
err = fmt.Errorf("unexpected type %T", v)
}
return
}
// Value implements the driver Valuer interface
func (i Inet) Value() (driver.Value, error) {
return i.IP.String(), nil
}
How to customize time fields to type DATETIME in MySQL?
Time fields use the MySQL TIMESTAMP type in the schema creation by default, and this type has a range of '1970-01-01 00:00:01' UTC to '2038-01-19 03:14:07' UTC (see, MySQL docs).
In order to customize time fields for a wider range, use the MySQL DATETIME as follows:
field.Time("birth_date").
Optional().
SchemaType(map[string]string{
dialect.MySQL: "datetime",
}),
如何使用自定义的 ID 生成器？
If you're using a custom ID generator instead of using auto-incrementing IDs in your database (e.g. Twitter's Snowflake), you will need to write a custom ID field which automatically calls the generator on resource creation.
To achieve this, you can either make use of DefaultFunc or of schema hooks - depending on your use case. If the generator does not return an error, DefaultFunc is more concise, whereas setting a hook on resource creation will allow you to capture errors as well. An example of how to use DefaultFunc can be seen in the section regarding the ID field.
Here is an example of how to use a custom generator with hooks, taking as an example sonyflake.
// BaseMixin to be shared will all different schemas.
type BaseMixin struct {
mixin.Schema
}
// Fields of the Mixin.
func (BaseMixin) Fields() []ent.Field {
return []ent.Field{
field.Uint64("id"),
}
}
// Hooks of the Mixin.
func (BaseMixin) Hooks() []ent.Hook {
return []ent.Hook{
hook.On(IDHook(), ent.OpCreate),
}
}
func IDHook() ent.Hook {
sf := sonyflake.NewSonyflake(sonyflake.Settings{})
type IDSetter interface {
SetID(uint64)
}
return func(next ent.Mutator) ent.Mutator {
return ent.MutateFunc(func(ctx context.Context, m ent.Mutation) (ent.Value, error) {
is, ok := m.(IDSetter)
if !ok {
return nil, fmt.Errorf("unexpected mutation %T", m)
}
id, err := sf.NextID()
if err != nil {
return nil, err
}
is.SetID(id)
return next.Mutate(ctx, m)
})
}
}
// User holds the schema definition for the User entity.
type User struct {
ent.Schema
}
// Mixin of the User.
func (User) Mixin() []ent.Mixin {
return []ent.Mixin{
// Embed the BaseMixin in the user schema.
BaseMixin{},
}
}
How to use a custom XID globally unique ID?
Package xid is a globally unique ID generator library that uses the Mongo Object ID algorithm to generate a 12 byte, 20 character ID with no configuration. The xid package comes with database/sql sql.Scanner and driver.Valuer interfaces required by Ent for serialization.
To store an XID in any string field use the GoType schema configuration:
// Fields of type T.
func (T) Fields() []ent.Field {
return []ent.Field{
field.String("id").
GoType(xid.ID{}).
DefaultFunc(xid.New),
}
}
Or as a reusable Mixin across multiple schemas:
package schema
import (
"entgo.io/ent"
"entgo.io/ent/schema/field"
"entgo.io/ent/schema/mixin"
"github.com/rs/xid"
)
// BaseMixin to be shared will all different schemas.
type BaseMixin struct {
mixin.Schema
}
// Fields of the User.
func (BaseMixin) Fields() []ent.Field {
return []ent.Field{
field.String("id").
GoType(xid.ID{}).
DefaultFunc(xid.New),
}
}
// User holds the schema definition for the User entity.
type User struct {
ent.Schema
}
// Mixin of the User.
func (User) Mixin() []ent.Mixin {
return []ent.Mixin{
// Embed the BaseMixin in the user schema.
BaseMixin{},
}
}
In order to use extended identifiers (XIDs) with gqlgen, follow the configuration mentioned in the issue tracker.
How to define a spatial data type field in MySQL?
The GoType and the SchemaType options allow users to define database-specific fields. For example, in order to define a POINT field, use the following configuration:
// Fields of the Location.
func (Location) Fields() []ent.Field {
return []ent.Field{
field.String("name"),
field.Other("coords", &Point{}).
SchemaType(Point{}.SchemaType()),
}
}
package schema
import (
"database/sql/driver"
"fmt"
"entgo.io/ent/dialect"
"entgo.io/ent/dialect/sql"
"github.com/paulmach/orb"
"github.com/paulmach/orb/encoding/wkb"
)
// A Point consists of (X,Y) or (Lat, Lon) coordinates
// and it is stored in MySQL the POINT spatial data type.
type Point [2]float64
// Scan implements the Scanner interface.
func (p *Point) Scan(value any) error {
bin, ok := value.([]byte)
if !ok {
return fmt.Errorf("invalid binary value for point")
}
var op orb.Point
if err := wkb.Scanner(&op).Scan(bin[4:]); err != nil {
return err
}
p[0], p[1] = op.X(), op.Y()
return nil
}
// Value implements the driver Valuer interface.
func (p Point) Value() (driver.Value, error) {
op := orb.Point{p[0], p[1]}
return wkb.Value(op).Value()
}
// FormatParam implements the sql.ParamFormatter interface to tell the SQL
// builder that the placeholder for a Point parameter needs to be formatted.
func (p Point) FormatParam(placeholder string, info *sql.StmtInfo) string {
if info.Dialect == dialect.MySQL {
return "ST_GeomFromWKB(" + placeholder + ")"
}
return placeholder
}
// SchemaType defines the schema-type of the Point object.
func (Point) SchemaType() map[string]string {
return map[string]string{
dialect.MySQL: "POINT",
}
}
A full example exists in the example repository.
How to extend the generated models?
Ent supports extending generated types (both global types and models) using custom templates. For example, in order to add additional struct fields or methods to the generated model, we can override the model/fields/additional template like in this example.
If your custom fields/methods require additional imports, you can add those imports using custom templates as well:
{{- define "import/additional/field_types" -}}
"github.com/path/to/your/custom/type"
{{- end -}}
{{- define "import/additional/client_dependencies" -}}
"github.com/path/to/your/custom/type"
{{- end -}}
How to extend the generated builders?
See the Injecting External Dependencies section, or follow the example on GitHub.
How to store Protobuf objects in a BLOB column?
Assuming we have a Protobuf message defined:
syntax = "proto3";
package pb;
option go_package = "project/pb";
message Hi {
string Greeting = 1;
}
We add receiver methods to the generated protobuf struct such that it implements ValueScanner
func (x *Hi) Value() (driver.Value, error) {
return proto.Marshal(x)
}
func (x *Hi) Scan(src any) error {
if src == nil {
return nil
}
if b, ok := src.([]byte); ok {
if err := proto.Unmarshal(b, x); err != nil {
return err
}
return nil
}
return fmt.Errorf("unexpected type %T", src)
}
We add a new field.Bytes to our schema, setting the generated protobuf struct as its underlying GoType:
// Fields of the Message.
func (Message) Fields() []ent.Field {
return []ent.Field{
field.Bytes("hi").
GoType(&pb.Hi{}),
}
}
Test that it works:
package main
import (
"context"
"testing"
"project/ent/enttest"
"project/pb"
_ "github.com/mattn/go-sqlite3"
"github.com/stretchr/testify/require"
)
func TestMain(t *testing.T) {
client := enttest.Open(t, "sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")
defer client.Close()
msg := client.Message.Create().
SetHi(&pb.Hi{
Greeting: "hello",
}).
SaveX(context.TODO())
ret := client.Message.GetX(context.TODO(), msg.ID)
require.Equal(t, "hello", ret.Hi.Greeting)
}
How to add CHECK constraints to table?
The entsql.Annotation option allows adding custom CHECK constraints to the CREATE TABLE statement. In order to add CHECK constraints to your schema, use the following example:
func (User) Annotations() []schema.Annotation {
return []schema.Annotation{
&entsql.Annotation{
// The `Check` option allows adding an
// unnamed CHECK constraint to table DDL.
Check: "website <> 'entgo.io'",
// The `Checks` option allows adding multiple CHECK constraints
// to table creation. The keys are used as the constraint names.
Checks: map[string]string{
"valid_nickname": "nickname <> firstname",
"valid_firstname": "length(first_name) > 1",
},
},
}
}
How to define a custom precision numeric field?
Using GoType and SchemaType it is possible to define custom precision numeric fields. For example, defining a field that uses big.Int.
func (T) Fields() []ent.Field {
return []ent.Field{
field.Int("precise").
GoType(new(BigInt)).
SchemaType(map[string]string{
dialect.SQLite: "numeric(78, 0)",
dialect.Postgres: "numeric(78, 0)",
}),
}
}
type BigInt struct {
big.Int
}
func (b *BigInt) Scan(src any) error {
var i sql.NullString
if err := i.Scan(src); err != nil {
return err
}
if !i.Valid {
return nil
}
if _, ok := b.Int.SetString(i.String, 10); ok {
return nil
}
return fmt.Errorf("could not scan type %T with value %v into BigInt", src, src)
}
func (b *BigInt) Value() (driver.Value, error) {
return b.String(), nil
}
How to configure two or more DB to separate read and write?
You can wrap the dialect.Driver with your own driver and implement this logic. For example.
You can extend it, add support for multiple read replicas and add some load-balancing magic.
func main() {
// ...
wd, err := sql.Open(dialect.MySQL, "root:pass@tcp(<addr>)/<database>?parseTime=True")
if err != nil {
log.Fatal(err)
}
rd, err := sql.Open(dialect.MySQL, "readonly:pass@tcp(<addr>)/<database>?parseTime=True")
if err != nil {
log.Fatal(err)
}
client := ent.NewClient(ent.Driver(&multiDriver{w: wd, r: rd}))
defer client.Close()
// Use the client here.
}
type multiDriver struct {
r, w dialect.Driver
}
var _ dialect.Driver = (*multiDriver)(nil)
func (d *multiDriver) Query(ctx context.Context, query string, args, v any) error {
e := d.r
// Mutation statements that use the RETURNING clause.
if ent.QueryFromContext(ctx) == nil {
e = d.w
}
return e.Query(ctx, query, args, v)
}
func (d *multiDriver) Exec(ctx context.Context, query string, args, v any) error {
return d.w.Exec(ctx, query, args, v)
}
func (d *multiDriver) Tx(ctx context.Context) (dialect.Tx, error) {
return d.w.Tx(ctx)
}
func (d *multiDriver) BeginTx(ctx context.Context, opts *sql.TxOptions) (dialect.Tx, error) {
return d.w.(interface {
BeginTx(context.Context, *sql.TxOptions) (dialect.Tx, error)
}).BeginTx(ctx, opts)
}
func (d *multiDriver) Close() error {
rerr := d.r.Close()
werr := d.w.Close()
if rerr != nil {
return rerr
}
if werr != nil {
return werr
}
return nil
}
func (d *multiDriver) Dialect() string {
return d.r.Dialect()
}
How to change the character set and/or collation of a MySQL table?
By default for MySQL the character set utf8mb4 is used and the collation of utf8mb4_bin. However if you'd like to change the schema's character set and/or collation you need to use an annotation.
Here's an example where we set the character set to ascii and the collation to ascii_general_ci.
// Annotations of the Entity.
func (Entity) Annotations() []schema.Annotation {
return []schema.Annotation{
entsql.Annotation{
Charset: "ascii",
Collation: "ascii_general_ci",
},
}
}
How to configure json.Marshal to inline the edges keys in the top level object?
To encode entities without the edges attribute, users can follow these two steps:
- Omit the default
edgestag generated by Ent. - Extend the generated models with a custom MarshalJSON method.
These two steps can be automated using codegen extensions, and a full working example is available under the examples/jsonencode directory.
//go:build ignore
// +build ignore
package main
import (
"log"
"entgo.io/ent/entc"
"entgo.io/ent/entc/gen"
"entgo.io/ent/schema/edge"
)
func main() {
opts := []entc.Option{
entc.Extensions{
&EncodeExtension{},
),
}
err := entc.Generate("./schema", &gen.Config{}, opts...)
if err != nil {
log.Fatalf("running ent codegen: %v", err)
}
}
// EncodeExtension is an implementation of entc.Extension that adds a MarshalJSON
// method to each generated type <T> and inlines the Edges field to the top level JSON.
type EncodeExtension struct {
entc.DefaultExtension
}
// Templates of the extension.
func (e *EncodeExtension) Templates() []*gen.Template {
return []*gen.Template{
gen.MustParse(gen.NewTemplate("model/additional/jsonencode").
Parse(`
{{ if $.Edges }}
// MarshalJSON implements the json.Marshaler interface.
func ({{ $.Receiver }} *{{ $.Name }}) MarshalJSON() ([]byte, error) {
type Alias {{ $.Name }}
return json.Marshal(&struct {
*Alias
{{ $.Name }}Edges
}{
Alias: (*Alias)({{ $.Receiver }}),
{{ $.Name }}Edges: {{ $.Receiver }}.Edges,
})
}
{{ end }}
`)),
}
}
// Hooks of the extension.
func (e *EncodeExtension) Hooks() []gen.Hook {
return []gen.Hook{
func(next gen.Generator) gen.Generator {
return gen.GenerateFunc(func(g *gen.Graph) error {
tag := edge.Annotation{StructTag: `json:"-"`}
for _, n := range g.Nodes {
n.Annotations.Set(tag.Name(), tag)
}
return next.Generate(g)
})
},
}
}