Skip to main content

Generating Schemas

Introduction#

To facilitate the creation of tooling that generates ent.Schemas programmatically, ent supports the manipulation of the schema/ directory using the entgo.io/contrib/schemast package.

API#

Loading#

In order to manipulate an existing schema directory we must first load it into a schemast.Context object:

package main
import (
"fmt"
"log"
"entgo.io/contrib/schemast"
)
func main() {
ctx, err := schemast.Load("./ent/schema")
if err != nil {
log.Fatalf("failed: %v", err)
}
if ctx.HasType("user") {
fmt.Println("schema directory contains a schema named User!")
}
}

Printing#

To print back out our context to a target directory, use schemast.Print:

package main
import (
"log"
"entgo.io/contrib/schemast"
)
func main() {
ctx, err := schemast.Load("./ent/schema")
if err != nil {
log.Fatalf("failed: %v", err)
}
// A no-op since we did not manipulate the Context at all.
if err := schemast.Print("./ent/schema"); err != nil {
log.Fatalf("failed: %v", err)
}
}

Mutators#

To mutate the ent/schema directory, we can use schemast.Mutate, which takes a list of schemast.Mutators to apply to the context:

package schemast
// Mutator changes a Context.
type Mutator interface {
Mutate(ctx *Context) error
}

Currently, only a single type of schemast.Mutator is implemented, UpsertSchema:

package schemast
// UpsertSchema implements Mutator. UpsertSchema will add to the Context the type named
// Name if not present and rewrite the type's Fields, Edges, Indexes and Annotations methods.
type UpsertSchema struct {
Name string
Fields []ent.Field
Edges []ent.Edge
Indexes []ent.Index
Annotations []schema.Annotation
}

To use it:

package main
import (
"log"
"entgo.io/contrib/schemast"
"entgo.io/ent"
"entgo.io/ent/schema/field"
)
func main() {
ctx, err := schemast.Load("./ent/schema")
if err != nil {
log.Fatalf("failed: %v", err)
}
mutations := []schemast.Mutator{
&schemast.UpsertSchema{
Name: "User",
Fields: []ent.Field{
field.String("name"),
},
},
&schemast.UpsertSchema{
Name: "Team",
Fields: []ent.Field{
field.String("name"),
},
},
}
err = schemast.Mutate(ctx, mutations...)
if err := ctx.Print("./ent/schema"); err != nil {
log.Fatalf("failed: %v", err)
}
}

After running this program, observe two new files exist in the schema directory: user.go and team.go:

// user.go
package schema
import (
"entgo.io/ent"
"entgo.io/ent/schema"
"entgo.io/ent/schema/field"
)
type User struct {
ent.Schema
}
func (User) Fields() []ent.Field {
return []ent.Field{field.String("name")}
}
func (User) Edges() []ent.Edge {
return nil
}
func (User) Annotations() []schema.Annotation {
return nil
}
package schema
import (
"entgo.io/ent"
"entgo.io/ent/schema"
"entgo.io/ent/schema/field"
)
type Team struct {
ent.Schema
}
func (Team) Fields() []ent.Field {
return []ent.Field{field.String("name")}
}
func (Team) Edges() []ent.Edge {
return nil
}
func (Team) Annotations() []schema.Annotation {
return nil
}

Working with Edges#

Edges are defined in ent this way:

edge.To("edge_name", OtherSchema.Type)

This syntax relies on the fact that the OtherSchema struct already exists when we define the edge so we can refer to its Type method. When we are generating schemas programmatically, obviously we need somehow to describe the edge to the code-generator before the type definitions exist. To do this you can do something like:

type placeholder struct {
ent.Schema
}
func withType(e ent.Edge, typeName string) ent.Edge {
e.Descriptor().Type = typeName
return e
}
func newEdgeTo(edgeName, otherType string) ent.Edge {
// we pass a placeholder type to the edge constructor:
e := edge.To(edgeName, placeholder.Type)
// then we override the other type's name directly on the edge descriptor:
return withType(e, otherType)
}

Examples#

The protoc-gen-ent (doc) is a protoc plugin that programmatically generates ent.Schemas from .proto files, it uses the schemast to manipulate the target schema directory. To see how, read the source code.

Caveats#

schemast is still experimental, APIs are subject to change in the future. In addition, a small portion of the ent.Field definition API is unsupported at this point in time, to see a full list of unsupported features see the source code.