Skip to main content

Introduction

Installation#

The project comes with a codegen tool called ent. In order to install ent run the following command:

go get entgo.io/ent/cmd/ent

Initialize A New Schema#

In order to generate one or more schema templates, run ent init as follows:

go run entgo.io/ent/cmd/ent init User Pet

init will create the 2 schemas (user.go and pet.go) under the ent/schema directory. If the ent directory does not exist, it will create it as well. The convention is to have an ent directory under the root directory of the project.

Generate Assets#

After adding a few fields and edges, you want to generate the assets for working with your entities. Run ent generate from the root directory of the project, or use go generate:

go generate ./ent

The generate command generates the following assets for the schemas:

  • Client and Tx objects used for interacting with the graph.
  • CRUD builders for each schema type. See CRUD for more info.
  • Entity object (Go struct) for each of the schema types.
  • Package containing constants and predicates used for interacting with the builders.
  • A migrate package for SQL dialects. See Migration for more info.
  • A hook package for adding mutation middlewares. See Hooks for more info.

Version Compatibility Between entc And ent#

When working with ent CLI in a project, you want to make sure the version being used by the CLI is identical to the ent version used by your project.

One of the options for achieving this is asking go generate to use the version mentioned in the go.mod file when running ent. If your project does not use Go modules, setup one as follows:

go mod init <project>

And then, re-run the following command in order to add ent to your go.mod file:

go get entgo.io/ent/cmd/ent

Add a generate.go file to your project under <project>/ent:

package ent
//go:generate go run -mod=mod entgo.io/ent/cmd/ent generate ./schema

Finally, you can run go generate ./ent from the root directory of your project in order to run ent code generation on your project schemas.

Code Generation Options#

For more info about codegen options, run ent generate -h:

generate go code for the schema directory
Usage:
ent generate [flags] path
Examples:
ent generate ./ent/schema
ent generate github.com/a8m/x
Flags:
--feature strings extend codegen with additional features
--header string override codegen header
-h, --help help for generate
--idtype [int string] type of the id field (default int)
--storage string storage driver to support in codegen (default "sql")
--target string target directory for codegen
--template strings external templates to execute

Storage Options#

ent can generate assets for both SQL and Gremlin dialect. The default dialect is SQL.

External Templates#

ent accepts external Go templates to execute. If the template name already defined by ent, it will override the existing one. Otherwise, it will write the execution output to a file with the same name as the template. The flag format supports file, dir and glob as follows:

go run entgo.io/ent/cmd/ent generate --template <dir-path> --template glob="path/to/*.tmpl" ./ent/schema

More information and examples can be found in the external templates doc.

Use entc As A Package#

Another option for running ent CLI is to use it as a package as follows:

package main
import (
"log"
"entgo.io/ent/entc"
"entgo.io/ent/entc/gen"
"entgo.io/ent/schema/field"
)
func main() {
err := entc.Generate("./schema", &gen.Config{
Header: "// Your Custom Header",
IDType: &field.TypeInfo{Type: field.TypeInt},
})
if err != nil {
log.Fatal("running ent codegen:", err)
}
}

The full example exists in GitHub.

Schema Description#

In order to get a description of your graph schema, run:

go run entgo.io/ent/cmd/ent describe ./ent/schema

An example for the output is as follows:

Pet:
+-------+---------+--------+----------+----------+---------+---------------+-----------+-----------------------+------------+
| Field | Type | Unique | Optional | Nillable | Default | UpdateDefault | Immutable | StructTag | Validators |
+-------+---------+--------+----------+----------+---------+---------------+-----------+-----------------------+------------+
| id | int | false | false | false | false | false | false | json:"id,omitempty" | 0 |
| name | string | false | false | false | false | false | false | json:"name,omitempty" | 0 |
+-------+---------+--------+----------+----------+---------+---------------+-----------+-----------------------+------------+
+-------+------+---------+---------+----------+--------+----------+
| Edge | Type | Inverse | BackRef | Relation | Unique | Optional |
+-------+------+---------+---------+----------+--------+----------+
| owner | User | true | pets | M2O | true | true |
+-------+------+---------+---------+----------+--------+----------+
User:
+-------+---------+--------+----------+----------+---------+---------------+-----------+-----------------------+------------+
| Field | Type | Unique | Optional | Nillable | Default | UpdateDefault | Immutable | StructTag | Validators |
+-------+---------+--------+----------+----------+---------+---------------+-----------+-----------------------+------------+
| id | int | false | false | false | false | false | false | json:"id,omitempty" | 0 |
| age | int | false | false | false | false | false | false | json:"age,omitempty" | 0 |
| name | string | false | false | false | false | false | false | json:"name,omitempty" | 0 |
+-------+---------+--------+----------+----------+---------+---------------+-----------+-----------------------+------------+
+------+------+---------+---------+----------+--------+----------+
| Edge | Type | Inverse | BackRef | Relation | Unique | Optional |
+------+------+---------+---------+----------+--------+----------+
| pets | Pet | false | | O2M | false | true |
+------+------+---------+---------+----------+--------+----------+

Code Generation Hooks#

The entc package provides an option to add a list of hooks (middlewares) to the code-generation phase. This option is ideal for adding custom validators for the schema, or for generating additional assets using the graph schema.

// +build ignore
package main
import (
"fmt"
"log"
"reflect"
"entgo.io/ent/entc"
"entgo.io/ent/entc/gen"
)
func main() {
err := entc.Generate("./schema", &gen.Config{
Hooks: []gen.Hook{
EnsureStructTag("json"),
},
})
if err != nil {
log.Fatalf("running ent codegen: %v", err)
}
}
// EnsureStructTag ensures all fields in the graph have a specific tag name.
func EnsureStructTag(name string) gen.Hook {
return func(next gen.Generator) gen.Generator {
return gen.GenerateFunc(func(g *gen.Graph) error {
for _, node := range g.Nodes {
for _, field := range node.Fields {
tag := reflect.StructTag(field.StructTag)
if _, ok := tag.Lookup(name); !ok {
return fmt.Errorf("struct tag %q is missing for field %s.%s", name, node.Name, field.Name)
}
}
}
return next.Generate(g)
})
}
}

Feature Flags#

The entc package provides a collection of code-generation features that be added or removed using flags.

For more information, please see the features-flags page.