README

ent - An Entity Framework For Go

Simple, yet powerful ORM for modeling and querying data.

  • Schema As Code - model any database schema as Go objects.
  • Easily Traverse Any Graph - run queries, aggregations and traverse any graph structure easily.
  • Statically Typed And Explicit API - 100% statically typed and explicit API using code generation.
  • Multi Storage Driver - supports MySQL, PostgreSQL, SQLite and Gremlin.

Quick Installation

go get github.com/facebook/ent/cmd/entc

For proper installation using Go modules, visit entgo.io website.

Docs

The documentation for developing and using ent is available at: https://entgo.io

Join the ent Community

In order to contribute to ent, see the CONTRIBUTING file for how to go get started.
If your company or your product is using ent, please let us know by adding yourself to the ent users page.

About the Project

The ent project was inspired by Ent, an entity framework we use internally. It is developed and maintained by a8m and alexsn from the Facebook Connectivity team. It is used by multiple teams and projects in production, and the roadmap for its v1 release is described here. Read more about the motivation of the project here.

License

ent is licensed under Apache 2.0 as found in the LICENSE file.

Expand ▾ Collapse ▴

Documentation

Overview

Package ent is the interface between end-user schemas and entc (ent codegen).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// A Table is an optional table name defined for the schema.
	Table string
}

A Config structure is used to configure an entity schema. The usage of this structure is as follows:

func (T) Config() ent.Config {
	return ent.Config{
		Table: "Name",
	}
}

type Edge

type Edge interface {
	Descriptor() *edge.Descriptor
}

A Edge interface returns an edge descriptor for vertex edges. The usage for the interface is as follows:

func (T) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("S", S.Type),
	}
}

type Field

type Field interface {
	Descriptor() *field.Descriptor
}

A Field interface returns a field descriptor for vertex fields/properties. The usage for the interface is as follows:

func (T) Fields() []ent.Field {
	return []ent.Field{
		field.Int("int"),
	}
}

type Hook

type Hook func(Mutator) Mutator

Hook defines the "mutation middleware". A function that gets a Mutator and returns a Mutator. For example:

hook := func(next ent.Mutator) ent.Mutator {
	return ent.MutateFunc(func(ctx context.Context, m ent.Mutation) (ent.Value, error) {
		fmt.Printf("Type: %s, Operation: %s, ConcreteType: %T\n", m.Type(), m.Op(), m)
		return next.Mutate(ctx, m)
	})
}

type Index

type Index interface {
	Descriptor() *index.Descriptor
}

A Index interface returns an index descriptor for vertex indexes. The usage for the interface is as follows:

func (T) Indexes() []ent.Index {
	return []ent.Index{
		index.Fields("f1", "f2").
			Unique(),
	}
}

type Interface

type Interface interface {
	// Type is a dummy method, that is used in edge declaration.
	//
	// The Type method should be used as follows:
	//
	//	type S struct { ent.Schema }
	//
	//	type T struct { ent.Schema }
	//
	//	func (T) Edges() []ent.Edge {
	//		return []ent.Edge{
	//			edge.To("S", S.Type),
	//		}
	//	}
	//
	Type()
	// Fields returns the fields of the schema.
	Fields() []Field
	// Edges returns the edges of the schema.
	Edges() []Edge
	// Indexes returns the indexes of the schema.
	Indexes() []Index
	// Config returns an optional config for the schema.
	Config() Config
	// Mixin returns an optional list of Mixin to extends
	// the schema.
	Mixin() []Mixin
	// Hooks returns an optional list of Hook to apply on
	// mutations.
	Hooks() []Hook
	// Policy returns the privacy policy of the schema.
	Policy() Policy
}

The Interface type describes the requirements for an exported type defined in the schema package. It functions as the interface between the user's schema types and codegen loader. Users should use the Schema type for embedding as follows:

type T struct {
	ent.Schema
}

type Mixin

type Mixin interface {
	// Fields returns a slice of fields to add to the schema.
	Fields() []Field
	// Edges returns a slice of edges to add to the schema.
	Edges() []Edge
	// Indexes returns a slice of indexes to add to the schema.
	Indexes() []Index
	// Hooks returns a slice of hooks to add to the schema.
	// Note that mixin hooks are executed before schema hooks.
	Hooks() []Hook
}

The Mixin type describes a set of methods that can extend other methods in the schema without calling them directly.

type TimeMixin struct {}

func (TimeMixin) Fields() []ent.Field {
	return []ent.Field{
		field.Time("created_at").
			Immutable().
			Default(time.Now),
		field.Time("updated_at").
			Default(time.Now).
			UpdateDefault(time.Now),
	}
}

type T struct {
	ent.Schema
}

func(T) Mixin() []ent.Mixin {
	return []ent.Mixin{
		TimeMixin{},
	}
}

type MutateFunc

type MutateFunc func(context.Context, Mutation) (Value, error)

The MutateFunc type is an adapter to allow the use of ordinary function as mutator. If f is a function with the appropriate signature, MutateFunc(f) is a Mutator that calls f.

func (MutateFunc) Mutate

func (f MutateFunc) Mutate(ctx context.Context, m Mutation) (Value, error)

Mutate calls f(ctx, m).

type Mutation

type Mutation interface {
	// Op returns the operation name generated by entc.
	Op() Op
	// Type returns the schema type for this mutation.
	Type() string

	// Fields returns all fields that were changed during
	// this mutation. Note that, in order to get all numeric
	// fields that were in/decremented, call AddedFields().
	Fields() []string
	// Field returns the value of a field with the given name.
	// The second boolean value indicates that this field was
	// not set, or was not defined in the schema.
	Field(name string) (Value, bool)
	// SetField sets the value for the given name. It returns an
	// error if the field is not defined in the schema, or if the
	// type mismatch the field type.
	SetField(name string, value Value) error

	// AddedFields returns all numeric fields that were incremented
	// or decremented during this mutation.
	AddedFields() []string
	// AddedField returns the numeric value that was in/decremented
	// from a field with the given name. The second value indicates
	// that this field was not set, or was not define in the schema.
	AddedField(name string) (Value, bool)
	// AddField adds the value for the given name. It returns an
	// error if the field is not defined in the schema, or if the
	// type mismatch the field type.
	AddField(name string, value Value) error

	// ClearedFields returns all nullable fields that were cleared
	// during this mutation.
	ClearedFields() []string
	// FieldCleared returns a boolean indicates if this field was
	// cleared in this mutation.
	FieldCleared(name string) bool
	// ClearField clears the value for the given name. It returns an
	// error if the field is not defined in the schema.
	ClearField(name string) error

	// ResetField resets all changes in the mutation regarding the
	// given field name. It returns an error if the field is not
	// defined in the schema.
	ResetField(name string) error

	// AddedEdges returns all edge names that were set/added in this
	// mutation.
	AddedEdges() []string
	// AddedIDs returns all ids (to other nodes) that were added for
	// the given edge name.
	AddedIDs(name string) []Value

	// RemovedEdges returns all edge names that were removed in this
	// mutation.
	RemovedEdges() []string
	// RemovedIDs returns all ids (to other nodes) that were removed for
	// the given edge name.
	RemovedIDs(name string) []Value

	// ClearedEdges returns all edge names that were cleared in this
	// mutation.
	ClearedEdges() []string
	// EdgeCleared returns a boolean indicates if this edge was
	// cleared in this mutation.
	EdgeCleared(name string) bool
	// ClearEdge clears the value for the given name. It returns an
	// error if the edge name is not defined in the schema.
	ClearEdge(name string) error

	// ResetEdge resets all changes in the mutation regarding the
	// given edge name. It returns an error if the edge is not
	// defined in the schema.
	ResetEdge(name string) error

	// OldField returns the old value of the field from the database.
	// An error is returned if the mutation operation is not UpdateOne,
	// or the query to the database was failed.
	OldField(ctx context.Context, name string) (Value, error)
}

Mutation represents an operation that mutate the graph. For example, adding a new node, updating many, or dropping data. The implementation is generated by entc (ent codegen).

type Mutator

type Mutator interface {
	// Mutate apply the given mutation on the graph.
	Mutate(context.Context, Mutation) (Value, error)
}

Mutator is the interface that wraps the Mutate method.

type Op

type Op uint

An Op represents a mutation operation.

const (
	OpCreate    Op = 1 << iota // node creation.
	OpUpdate                   // update nodes by predicate (if any).
	OpUpdateOne                // update one node.
	OpDelete                   // delete nodes by predicate (if any).
	OpDeleteOne                // delete one one.
)

Mutation operations.

func (Op) Is

func (i Op) Is(o Op) bool

Is reports whether o is match the given operation.

func (Op) String

func (i Op) String() string

type Policy

type Policy interface {
	EvalMutation(context.Context, Mutation) error
	EvalQuery(context.Context, Query) error
}

The Policy type defines the write privacy policy of an entity. The usage for the interface is as follows:

type T struct {

ent.Schema

}

func(T) Policy() ent.Policy {

return privacy.AlwaysAllowReadWrite()

}

type Query

type Query interface{}

Query represents an ent query builder.

type Schema

type Schema struct {
	Interface
}

Schema is the default implementation for the schema Interface. It can be embedded in end-user schemas as follows:

type T struct {
	ent.Schema
}

func (Schema) Config

func (Schema) Config() Config

Config of the schema.

func (Schema) Edges

func (Schema) Edges() []Edge

Edges of the schema.

func (Schema) Fields

func (Schema) Fields() []Field

Fields of the schema.

func (Schema) Hooks

func (Schema) Hooks() []Hook

Hooks of the schema.

func (Schema) Indexes

func (Schema) Indexes() []Index

Indexes of the schema.

func (Schema) Mixin

func (Schema) Mixin() []Mixin

Mixin of the schema.

func (Schema) Policy

func (Schema) Policy() Policy

Policy of the schema.

type Value

type Value interface{}

Value represents a value returned by ent.

Directories

Path Synopsis
cmd/entc
dialect
dialect/gremlin
dialect/gremlin/encoding
dialect/gremlin/encoding/graphson
dialect/gremlin/graph
dialect/gremlin/graph/dsl Package dsl provide an API for writing gremlin dsl queries almost as-is in Go without using strings in the code.
dialect/gremlin/graph/dsl/g
dialect/gremlin/graph/dsl/p
dialect/gremlin/internal/ws
dialect/gremlin/ocgremlin
dialect/sql
dialect/sql/schema Package schema contains all schema migration logic for SQL dialects.
dialect/sql/sqlgraph sqlgraph provides graph abstraction capabilities on top of sql-based databases for ent codegen.
entc Package entc provides an interface for interacting with entc (ent codegen) as a package rather than an executable.
entc/gen Package gen is the interface for generating loaded schemas into a Go package.
entc/gen/internal Package internal Code generated by go-bindata.
entc/integration/config/ent
entc/integration/config/ent/enttest
entc/integration/config/ent/hook
entc/integration/config/ent/migrate
entc/integration/config/ent/predicate
entc/integration/config/ent/privacy
entc/integration/config/ent/runtime
entc/integration/config/ent/schema
entc/integration/config/ent/user
entc/integration/customid/ent
entc/integration/customid/ent/blob
entc/integration/customid/ent/car
entc/integration/customid/ent/enttest
entc/integration/customid/ent/group
entc/integration/customid/ent/hook
entc/integration/customid/ent/migrate
entc/integration/customid/ent/pet
entc/integration/customid/ent/predicate
entc/integration/customid/ent/privacy
entc/integration/customid/ent/runtime
entc/integration/customid/ent/schema
entc/integration/customid/ent/user
entc/integration/ent
entc/integration/ent/card
entc/integration/ent/comment
entc/integration/ent/enttest
entc/integration/ent/fieldtype
entc/integration/ent/file
entc/integration/ent/filetype
entc/integration/ent/group
entc/integration/ent/groupinfo
entc/integration/ent/hook
entc/integration/ent/item
entc/integration/ent/migrate
entc/integration/ent/node
entc/integration/ent/pet
entc/integration/ent/predicate
entc/integration/ent/privacy
entc/integration/ent/role
entc/integration/ent/runtime
entc/integration/ent/schema
entc/integration/ent/spec
entc/integration/ent/task
entc/integration/ent/template
entc/integration/ent/user
entc/integration/gremlin/ent
entc/integration/gremlin/ent/card
entc/integration/gremlin/ent/comment
entc/integration/gremlin/ent/enttest
entc/integration/gremlin/ent/fieldtype
entc/integration/gremlin/ent/file
entc/integration/gremlin/ent/filetype
entc/integration/gremlin/ent/group
entc/integration/gremlin/ent/groupinfo
entc/integration/gremlin/ent/hook
entc/integration/gremlin/ent/item
entc/integration/gremlin/ent/node
entc/integration/gremlin/ent/pet
entc/integration/gremlin/ent/predicate
entc/integration/gremlin/ent/privacy
entc/integration/gremlin/ent/runtime
entc/integration/gremlin/ent/spec
entc/integration/gremlin/ent/task
entc/integration/gremlin/ent/user
entc/integration/hooks/ent
entc/integration/hooks/ent/card
entc/integration/hooks/ent/enttest
entc/integration/hooks/ent/hook
entc/integration/hooks/ent/migrate
entc/integration/hooks/ent/predicate
entc/integration/hooks/ent/privacy
entc/integration/hooks/ent/runtime
entc/integration/hooks/ent/schema
entc/integration/hooks/ent/user
entc/integration/idtype/ent
entc/integration/idtype/ent/enttest
entc/integration/idtype/ent/hook
entc/integration/idtype/ent/migrate
entc/integration/idtype/ent/predicate
entc/integration/idtype/ent/privacy
entc/integration/idtype/ent/runtime
entc/integration/idtype/ent/schema
entc/integration/idtype/ent/user
entc/integration/json/ent
entc/integration/json/ent/enttest
entc/integration/json/ent/hook
entc/integration/json/ent/migrate
entc/integration/json/ent/predicate
entc/integration/json/ent/privacy
entc/integration/json/ent/runtime
entc/integration/json/ent/schema
entc/integration/json/ent/user
entc/integration/migrate/entv1
entc/integration/migrate/entv1/car
entc/integration/migrate/entv1/enttest
entc/integration/migrate/entv1/hook
entc/integration/migrate/entv1/migrate
entc/integration/migrate/entv1/predicate
entc/integration/migrate/entv1/privacy
entc/integration/migrate/entv1/runtime
entc/integration/migrate/entv1/schema
entc/integration/migrate/entv1/user
entc/integration/migrate/entv2
entc/integration/migrate/entv2/car
entc/integration/migrate/entv2/enttest
entc/integration/migrate/entv2/group
entc/integration/migrate/entv2/hook
entc/integration/migrate/entv2/migrate
entc/integration/migrate/entv2/pet
entc/integration/migrate/entv2/predicate
entc/integration/migrate/entv2/privacy
entc/integration/migrate/entv2/runtime
entc/integration/migrate/entv2/schema
entc/integration/migrate/entv2/user
entc/integration/privacy/ent
entc/integration/privacy/ent/enttest
entc/integration/privacy/ent/galaxy
entc/integration/privacy/ent/hook
entc/integration/privacy/ent/migrate
entc/integration/privacy/ent/planet
entc/integration/privacy/ent/predicate
entc/integration/privacy/ent/privacy
entc/integration/privacy/ent/runtime
entc/integration/privacy/ent/schema
entc/integration/privacy/rule
entc/integration/template/ent
entc/integration/template/ent/enttest
entc/integration/template/ent/group
entc/integration/template/ent/hook
entc/integration/template/ent/migrate
entc/integration/template/ent/pet
entc/integration/template/ent/predicate
entc/integration/template/ent/privacy
entc/integration/template/ent/runtime
entc/integration/template/ent/schema
entc/integration/template/ent/user
entc/load Package load is the interface for loading schema package into a Go program.
entc/load/internal Package internal Code generated by go-bindata.
examples/edgeindex/ent
examples/edgeindex/ent/city
examples/edgeindex/ent/enttest
examples/edgeindex/ent/hook
examples/edgeindex/ent/migrate
examples/edgeindex/ent/predicate
examples/edgeindex/ent/privacy
examples/edgeindex/ent/runtime
examples/edgeindex/ent/schema
examples/edgeindex/ent/street
examples/entcpkg/ent
examples/entcpkg/ent/enttest
examples/entcpkg/ent/hook
examples/entcpkg/ent/migrate
examples/entcpkg/ent/predicate
examples/entcpkg/ent/privacy
examples/entcpkg/ent/runtime
examples/entcpkg/ent/schema
examples/entcpkg/ent/user
examples/m2m2types/ent
examples/m2m2types/ent/enttest
examples/m2m2types/ent/group
examples/m2m2types/ent/hook
examples/m2m2types/ent/migrate
examples/m2m2types/ent/predicate
examples/m2m2types/ent/privacy
examples/m2m2types/ent/runtime
examples/m2m2types/ent/schema
examples/m2m2types/ent/user
examples/m2mbidi/ent
examples/m2mbidi/ent/enttest
examples/m2mbidi/ent/hook
examples/m2mbidi/ent/migrate
examples/m2mbidi/ent/predicate
examples/m2mbidi/ent/privacy
examples/m2mbidi/ent/runtime
examples/m2mbidi/ent/schema
examples/m2mbidi/ent/user
examples/m2mrecur/ent
examples/m2mrecur/ent/enttest
examples/m2mrecur/ent/hook
examples/m2mrecur/ent/migrate
examples/m2mrecur/ent/predicate
examples/m2mrecur/ent/privacy
examples/m2mrecur/ent/runtime
examples/m2mrecur/ent/schema
examples/m2mrecur/ent/user
examples/o2m2types/ent
examples/o2m2types/ent/enttest
examples/o2m2types/ent/hook
examples/o2m2types/ent/migrate
examples/o2m2types/ent/pet
examples/o2m2types/ent/predicate
examples/o2m2types/ent/privacy
examples/o2m2types/ent/runtime
examples/o2m2types/ent/schema
examples/o2m2types/ent/user
examples/o2mrecur/ent
examples/o2mrecur/ent/enttest
examples/o2mrecur/ent/hook
examples/o2mrecur/ent/migrate
examples/o2mrecur/ent/node
examples/o2mrecur/ent/predicate
examples/o2mrecur/ent/privacy
examples/o2mrecur/ent/runtime
examples/o2mrecur/ent/schema
examples/o2o2types/ent
examples/o2o2types/ent/card
examples/o2o2types/ent/enttest
examples/o2o2types/ent/hook
examples/o2o2types/ent/migrate
examples/o2o2types/ent/predicate
examples/o2o2types/ent/privacy
examples/o2o2types/ent/runtime
examples/o2o2types/ent/schema
examples/o2o2types/ent/user
examples/o2obidi/ent
examples/o2obidi/ent/enttest
examples/o2obidi/ent/hook
examples/o2obidi/ent/migrate
examples/o2obidi/ent/predicate
examples/o2obidi/ent/privacy
examples/o2obidi/ent/runtime
examples/o2obidi/ent/schema
examples/o2obidi/ent/user
examples/o2orecur/ent
examples/o2orecur/ent/enttest
examples/o2orecur/ent/hook
examples/o2orecur/ent/migrate
examples/o2orecur/ent/node
examples/o2orecur/ent/predicate
examples/o2orecur/ent/privacy
examples/o2orecur/ent/runtime
examples/o2orecur/ent/schema
examples/start
examples/start/ent
examples/start/ent/car
examples/start/ent/enttest
examples/start/ent/group
examples/start/ent/hook
examples/start/ent/migrate
examples/start/ent/predicate
examples/start/ent/privacy
examples/start/ent/runtime
examples/start/ent/schema
examples/start/ent/user
examples/traversal/ent
examples/traversal/ent/enttest
examples/traversal/ent/group
examples/traversal/ent/hook
examples/traversal/ent/migrate
examples/traversal/ent/pet
examples/traversal/ent/predicate
examples/traversal/ent/privacy
examples/traversal/ent/runtime
examples/traversal/ent/schema
examples/traversal/ent/user
schema/edge
schema/field
schema/field/gen gen is a codegen cmd for generating numeric build types from template.
schema/index
schema/mixin