Quick Introduction
ent is a simple, yet powerful entity framework for Go, that makes it easy to build and maintain applications with large data-models and sticks with the following principles:
- Easily model database schema as a graph structure.
- Define schema as a programmatic Go code.
- Static typing based on code generation.
- Database queries and graph traversals are easy to write.
- Simple to extend and customize using Go templates.
#
InstallationAfter installing ent
codegen tool, you should have it in your PATH
.
If you don't find it your path, you can also run: go run entgo.io/ent/cmd/ent <command>
#
Setup A Go EnvironmentIf your project directory is outside GOPATH or you are not familiar with GOPATH, setup a Go module project as follows:
#
Create Your First SchemaGo to the root directory of your project, and run:
The command above will generate the schema for User
under <project>/ent/schema/
directory:
Add 2 fields to the User
schema:
Run go generate
from the root directory of the project as follows:
This produces the following files:
#
Create Your First EntityTo get started, create a new ent.Client
. For this example, we will use SQLite3.
Now, we're ready to create our user. Let's call this function CreateUser
for the sake of example:
#
Query Your Entitiesent
generates a package for each entity schema that contains its predicates, default values, validators
and additional information about storage elements (column names, primary keys, etc).
#
Add Your First Edge (Relation)In this part of the tutorial, we want to declare an edge (relation) to another entity in the schema.
Let's create 2 additional entities named Car
and Group
with a few fields. We use ent
CLI
to generate the initial schemas:
And then we add the rest of the fields manually:
Let's define our first relation. An edge from User
to Car
defining that a user
can have 1 or more cars, but a car has only one owner (one-to-many relation).
Let's add the "cars"
edge to the User
schema, and run go generate ./ent
:
We continue our example by creating 2 cars and adding them to a user.
But what about querying the cars
edge (relation)? Here's how we do it:
#
Add Your First Inverse Edge (BackRef)Assume we have a Car
object and we want to get its owner; the user that this car belongs to.
For this, we have another type of edge called "inverse edge" that is defined using the edge.From
function.
The new edge created in the diagram above is translucent, to emphasize that we don't create another edge in the database. It's just a back-reference to the real edge (relation).
Let's add an inverse edge named owner
to the Car
schema, reference it to the cars
edge
in the User
schema, and run go generate ./ent
.
We'll continue the user/cars example above by querying the inverse edge.
#
Create Your Second EdgeWe'll continue our example by creating a M2M (many-to-many) relationship between users and groups.
As you can see, each group entity can have many users, and a user can be connected to many groups;
a simple "many-to-many" relationship. In the above illustration, the Group
schema is the owner
of the users
edge (relation), and the User
entity has a back-reference/inverse edge to this
relationship named groups
. Let's define this relationship in our schemas:
<project>/ent/schema/group.go
:<project>/ent/schema/user.go
:
We run ent
on the schema directory to re-generate the assets.
#
Run Your First Graph TraversalIn order to run our first graph traversal, we need to generate some data (nodes and edges, or in other words, entities and relations). Let's create the following graph using the framework:
Now when we have a graph with data, we can run a few queries on it:
Get all user's cars within the group named "GitHub":
Change the query above, so that the source of the traversal is the user Ariel:
Get all groups that have users (query with a look-aside predicate):
The full example exists in GitHub.