Ent

https://entgo.io/docs/
Admin
Ent is a simple yet powerful entity framework for Go that enables easy modeling, querying, and...
Tokens:138,401
Snippets:1,369
Trust Score:9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone and Run Example Project

Source: https://entgo.io/docs/tutorial-todo-gql

Commands to clone the example repository and start the server.

```bash
git clone git@github.com:a8m/ent-graphql-example.git  
cd ent-graphql-example  
go run ./cmd/todo  
```

--------------------------------

### Clone and Run Example Project

Source: https://entgo.io/docs/tutorial-todo-gql-mutation-input

Clone the example project and run the GraphQL server to start with the initial version.

```bash
git clone git@github.com:a8m/ent-graphql-example.git  
cd ent-graphql-example   
go run ./cmd/todo/  
```

--------------------------------

### Install gqlgen

Source: https://entgo.io/docs/tutorial-todo-gql

Command to install the gqlgen framework.

```bash
go get github.com/99designs/gqlgen  
```

--------------------------------

### Install SQLite Driver

Source: https://entgo.io/docs/tutorial-setup

Install the SQLite driver for Go.

```bash
go get github.com/mattn/go-sqlite3
```

--------------------------------

### Start Ent Docs Development Server

Source: https://entgo.io/docs/writing-docs

Navigate to the website directory and start the Docusaurus development server using npm.

```bash
cd doc/website && npm start  

```

--------------------------------

### Install Dependencies for Ent Docs

Source: https://entgo.io/docs/writing-docs

Navigate to the website directory and install Node.js dependencies using npm.

```bash
cd doc/website && npm install  

```

--------------------------------

### SQL data migration example

Source: https://entgo.io/docs/data-migrations

Example SQL script to backfill NULL or null tags in a users table.

```sql
-- Backfill NULL or null tags with a default value.
UPDATE `users` SET `tags` = '["foo","bar"]' WHERE `tags` IS NULL OR JSON_CONTAINS(`tags`, 'null', '$');
```

--------------------------------

### Install entgql Extension

Source: https://entgo.io/docs/tutorial-todo-gql

Command to install the entgql extension for Ent.

```bash
go get entgo.io/contrib/entgql@master  
```

--------------------------------

### Install Atlas

Source: https://entgo.io/docs/migration/enum-types

Installation commands for various platforms.

```bash
curl -sSf https://atlasgo.sh | sh
```

```bash
brew install ariga/tap/atlas
```

```bash
docker pull arigaio/atlas
docker run --rm arigaio/atlas --help
```

```bash
docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply \
  --url "mysql://root:pass@:3306/test"
```

--------------------------------

### Install Ent

Source: https://entgo.io/docs/tutorial-setup

Install the Ent command-line tool globally.

```bash
go get entgo.io/ent/cmd/ent
```

--------------------------------

### Run GraphQL server

Source: https://entgo.io/docs/tutorial-todo-gql

Starts the server using the go run command.

```bash
go run ./cmd/todo
```

--------------------------------

### Cloning the Ent GraphQL Example

Source: https://entgo.io/docs/tutorial-todo-gql-node

Commands to clone the repository and run the server for the tutorial.

```bash
git clone git@github.com:a8m/ent-graphql-example.git
cd ent-graphql-example
go run ./cmd/todo/
```

--------------------------------

### Example SQL Migration File

Source: https://entgo.io/docs/versioned-migrations

This is an example of a SQL file generated by Atlas for creating a 'users' table.

```sql
-- create "users" table
CREATE TABLE `users` (`id` bigint NOT NULL AUTO_INCREMENT, PRIMARY KEY (`id`)) CHARSET utf8mb4 COLLATE utf8mb4_bin;
```

--------------------------------

### Install entfix Tool

Source: https://entgo.io/docs/globalid-migrate

Install the `entfix` command-line tool, which is used for migrating Ent schemas.

```bash
go install entgo.io/ent/cmd/entfix@latest
```

--------------------------------

### Install Ent CLI

Source: https://entgo.io/docs/code-gen

Install the Ent codegen tool using the Go toolchain.

```bash
go get entgo.io/ent/cmd/ent  
```

--------------------------------

### Generated Service Implementation

Source: https://entgo.io/docs/grpc-generating-a-service

An example of the generated Get method implementation in entpb_user_service.go.

```go
// Get implements UserServiceServer.Get  
func (svc *UserService) Get(ctx context.Context, req *GetUserRequest) (*User, error) {  
    var (  
        err error  
        get *ent.User  
    )  
    id := int(req.GetId())  
    switch req.GetView() {  
    case GetUserRequest_VIEW_UNSPECIFIED, GetUserRequest_BASIC:  
        get, err = svc.client.User.Get(ctx, id)  
    case GetUserRequest_WITH_EDGE_IDS:  
        get, err = svc.client.User.Query().  
            Where(user.ID(id)).  
            Only(ctx)  
    default:  
        return nil, status.Error(codes.InvalidArgument, "invalid argument: unknown view")  
    }  
    switch {  
    case err == nil:  
        return toProtoUser(get)  
    case ent.IsNotFound(err):  
        return nil, status.Errorf(codes.NotFound, "not found: %s", err)  
    default:  
        return nil, status.Errorf(codes.Internal, "internal error: %s", err)  
    }  
}  
```

--------------------------------

### Run Tests

Source: https://entgo.io/docs/tutorial-setup

Execute Go tests to verify the project setup and functionality.

```bash
go test
```

--------------------------------

### Install Atlas CLI

Source: https://entgo.io/docs/migration/composite-types

Installs the Atlas CLI. Ensure Atlas is in your system's PATH.

```bash
curl -sSf https://atlasgo.sh | sh  
```

--------------------------------

### Install Atlas

Source: https://entgo.io/docs/migration/domain-types

Various methods to install the Atlas CLI tool.

```bash
curl -sSf https://atlasgo.sh | sh  
```

```bash
brew install ariga/tap/atlas  
```

```bash
docker pull arigaio/atlas  
docker run --rm arigaio/atlas --help  
```

--------------------------------

### Install protoc-gen-entgrpc

Source: https://entgo.io/docs/grpc-generating-proto

Command to install the `protoc-gen-entgrpc` plugin, which is required for generating gRPC service implementations from Protobuf definitions.

```bash
go install entgo.io/contrib/entproto/cmd/protoc-gen-entgrpc@master

```

--------------------------------

### Example SQL Migration File

Source: https://entgo.io/docs/versioned-migrations

This is an example of a generated SQL migration file that creates a 'users' table with an auto-incrementing primary key.

```sql
-- create "users" table  
CREATE TABLE `users` (`id` bigint NOT NULL AUTO_INCREMENT, PRIMARY KEY (`id`)) CHARSET utf8mb4 COLLATE utf8mb4_bin;  

```

--------------------------------

### Run Local Database Containers

Source: https://entgo.io/docs/versioned-migrations

Commands to start local database instances for computing migration states.

```bash
docker run --name migration --rm -p 3306:3306 -e MYSQL_ROOT_PASSWORD=pass -e MYSQL_DATABASE=test -d mysql  
```

```bash
docker run --name migration --rm -p 3306:3306 -e MYSQL_ROOT_PASSWORD=pass -e MYSQL_DATABASE=test -d mariadb  
```

```bash
docker run --name migration --rm -p 5432:5432 -e POSTGRES_PASSWORD=pass -e POSTGRES_DB=test -d postgres  
```

--------------------------------

### Install Atlas via Homebrew

Source: https://entgo.io/docs/migration/composite-types

Installs the Atlas CLI using Homebrew on macOS and Linux.

```bash
brew install ariga/tap/atlas  
```

--------------------------------

### Install Atlas CLI

Source: https://entgo.io/docs/multischema-migrations

Commands to install the Atlas CLI on various platforms.

```bash
curl -sSf https://atlasgo.sh | sh
```

```bash
brew install ariga/tap/atlas
```

```bash
docker pull arigaio/atlas
docker run --rm arigaio/atlas --help
```

--------------------------------

### Generated Schema Files

Source: https://entgo.io/docs/generating-ent-schemas

Example output files generated by the mutation process.

```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  
}
```

```go
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  
}
```

--------------------------------

### SQL Schema Output Example

Source: https://entgo.io/docs/getting-started

Example of the SQL schema generated by Ent for 'cars' and 'users' tables. Shows table creation statements with primary keys, constraints, and data types.

```sql
-- Create "cars" table  
CREATE TABLE `cars` (  
  `id` integer NOT NULL PRIMARY KEY AUTOINCREMENT,  
  `model` text NOT NULL,  
  `registered_at` datetime NOT NULL,  
  `user_cars` integer NULL,  
  CONSTRAINT `cars_users_cars` FOREIGN KEY (`user_cars`) REFERENCES `users` (`id`) ON DELETE SET NULL  
);  
  
-- Create "users" table  
CREATE TABLE `users` (  
  `id` integer NOT NULL PRIMARY KEY AUTOINCREMENT,  
  `age` integer NOT NULL,  
  `name` text NOT NULL DEFAULT 'unknown'  
);  


```

--------------------------------

### Run Go Tests

Source: https://entgo.io/docs/grpc-generating-proto

Commands to install dependencies for the generated package and then run all Go tests in the project, including the test for the generated Protobuf structs.

```bash
go get -u ./...
go test ./...

```

--------------------------------

### Create a Todo Item

Source: https://entgo.io/docs/tutorial-todo-crud

Example of creating a single Todo item and saving it to the database. Ensure the client and context are properly initialized before use.

```go
func Example_Todo() {
    // ...
    task1, err := client.Todo.Create().Save(ctx)
    if err != nil {
        log.Fatalf("failed creating a todo: %v", err)
    }
    fmt.Println(task1)
    // Output:
    // Todo(id=1)
}
```

--------------------------------

### Atlas migration output

Source: https://entgo.io/docs/versioned/new-migration

Example output from the Atlas CLI after applying a migration.

```text
Migrating to version 20221115101649 from 20221114165732 (1 migrations in total):  
  
  -- migrating version 20221115101649  
    -> ALTER TABLE `users` ADD COLUMN `title` varchar(255) NULL;  
  -- ok (36.152277ms)  
  
  -------------------------  
  -- 44.1116ms  
  -- 1 migrations  
  -- 1 sql statements
```

--------------------------------

### Apply migrations with Docker

Source: https://entgo.io/docs/versioned/auto-plan

Example of running Atlas via Docker with host network access and directory mounting.

```bash
docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply  \
  --url "mysql://root:pass@:3306/test"
```

--------------------------------

### Example Migration SQL File

Source: https://entgo.io/docs/migration/domain-types

This represents the content of a generated migration file containing domain and table definitions.

```sql
-- Create domain type "us_postal_code"
CREATE DOMAIN "us_postal_code" AS text CONSTRAINT "us_postal_code_check" CHECK ((VALUE ~ '^\d{5}$'::text) OR (VALUE ~ '^\d{5}-\d{4}$'::text));
-- Create "users" table
CREATE TABLE "users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "postal_code" "us_postal_code" NOT NULL, PRIMARY KEY ("id"));
```

--------------------------------

### Add SQLite Driver

Source: https://entgo.io/docs/grpc-server-and-client

Installs the go-sqlite3 package, which is required for the Ent server to use SQLite.

```bash
go get -u github.com/mattn/go-sqlite3
```

--------------------------------

### Run Atlas in Docker

Source: https://entgo.io/docs/migration/domain-types

Example of running Atlas in a container with host network access and volume mounting.

```bash
docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply  
  --url "mysql://root:pass@:3306/test"  
```

--------------------------------

### Querying a View in Ent

Source: https://entgo.io/docs/schema-views

Example of how to query a view once it's defined and generated. Note that mutation builders (`Create`, `Update`, `Delete`) are not generated for views.

```go
client.CleanUser.Query().OnlyX(ctx)

```

--------------------------------

### Initialize Go Project

Source: https://entgo.io/docs/tutorial-setup

Create a new project directory, navigate into it, and initialize a Go module.

```bash
mkdir todo
cd $_
go mod init todo
```

--------------------------------

### Generated UserService Definition

Source: https://entgo.io/docs/grpc-service-generation-options

This is an example of a generated gRPC service definition in a .proto file, showing the available methods (Create, Get, List, BatchCreate) for the UserService after customization.

```proto
service UserService {  
  rpc Create ( CreateUserRequest ) returns ( User );  
  
  rpc Get ( GetUserRequest ) returns ( User );  
  
  rpc List ( ListUserRequest ) returns ( ListUserResponse );  
  
  rpc BatchCreate ( BatchCreateUsersRequest ) returns ( BatchCreateUsersResponse );  
}  

```

--------------------------------

### Initialize Ent Client

Source: https://entgo.io/docs/crud

Connect to various database backends and run auto-migration.

```go
package main  
  
import (  
    "context"  
    "log"  
  
    "entdemo/ent"  
  
    _ "github.com/mattn/go-sqlite3"  
)  
  
func main() {  
    client, err := ent.Open("sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")  
    if err != nil {  
        log.Fatalf("failed opening connection to sqlite: %v", err)  
    }  
    defer client.Close()  
    // Run the auto migration tool.  
    if err := client.Schema.Create(context.Background()); err != nil {  
        log.Fatalf("failed creating schema resources: %v", err)  
    }  
}  
```

```go
package main  
  
import (  
    "context"  
    "log"  
  
    "entdemo/ent"  
  
    _ "github.com/lib/pq"  
)  
  
func main() {  
    client, err := ent.Open("postgres","host=<host> port=<port> user=<user> dbname=<database> password=<pass>")  
    if err != nil {  
        log.Fatalf("failed opening connection to postgres: %v", err)  
    }  
    defer client.Close()  
    // Run the auto migration tool.  
    if err := client.Schema.Create(context.Background()); err != nil {  
        log.Fatalf("failed creating schema resources: %v", err)  
    }  
}  
```

```go
package main  
  
import (  
    "context"  
    "log"  
  
    "entdemo/ent"  
  
    _ "github.com/go-sql-driver/mysql"  
)  
  
func main() {  
    client, err := ent.Open("mysql", "<user>:<pass>@tcp(<host>:<port>)/<database>?parseTime=True")  
    if err != nil {  
        log.Fatalf("failed opening connection to mysql: %v", err)  
    }  
    defer client.Close()  
    // Run the auto migration tool.  
    if err := client.Schema.Create(context.Background()); err != nil {  
        log.Fatalf("failed creating schema resources: %v", err)  
    }  
}  
```

```go
package main  
  
import (  
    "log"  
  
    "entdemo/ent"  
)  
  
func main() {  
    client, err := ent.Open("gremlin", "http://localhost:8182")  
    if err != nil {  
        log.Fatal(err)  
    }  
}  
```

--------------------------------

### Run Docker for Dev Database

Source: https://entgo.io/docs/versioned/programmatically

Starts a MySQL Docker container to serve as a development database for migration planning. Ensure the port is not already in use.

```bash
docker run --rm --name atlas-db-dev -d -p 3306:3306 -e MYSQL_DATABASE=dev -e MYSQL_ROOT_PASSWORD=pass mysql:8  

```

--------------------------------

### Initialize GraphQL server

Source: https://entgo.io/docs/tutorial-todo-gql

Sets up the main entry point for the GraphQL server with SQLite migration.

```go
package main  
  
import (  
    "context"  
    "log"  
    "net/http"  
  
    "todo"  
    "todo/ent"  
    "todo/ent/migrate"  
  
    "entgo.io/ent/dialect"  
    "github.com/99designs/gqlgen/graphql/handler"  
    "github.com/99designs/gqlgen/graphql/playground"  
  
    _ "github.com/mattn/go-sqlite3"  
)  
  
func main() {  
    // Create ent.Client and run the schema migration.  
    client, err := ent.Open(dialect.SQLite, "file:ent?mode=memory&cache=shared&_fk=1")  
    if err != nil {  
        log.Fatal("opening ent client", err)  
    }  
    if err := client.Schema.Create(  
        context.Background(),  
        migrate.WithGlobalUniqueID(true),  
    ); err != nil {  
        log.Fatal("opening ent client", err)  
    }  
  
    // Configure the server and start listening on :8081.  
    srv := handler.NewDefaultServer(todo.NewSchema(client))  
    http.Handle("/",  
        playground.Handler("Todo", "/query"),  
    )  
    http.Handle("/query", srv)  
    log.Println("listening on :8081")  
    if err := http.ListenAndServe(":8081", nil); err != nil {  
        log.Fatal("http server terminated", err)  
    }  
}
```

--------------------------------

### Install Atlas using curl

Source: https://entgo.io/docs/migration/extensions

Installs the latest release of Atlas by downloading and executing the installation script. This is a common method for macOS and Linux.

```bash
curl -sSf https://atlasgo.sh | sh
```

--------------------------------

### Basic Ent Client Test Setup

Source: https://entgo.io/docs/testing

Use `enttest.Open` to create an Ent client for unit tests. It automatically handles schema migrations. Ensure you defer `client.Close()` to release resources.

```go
package main  
  
import (  
    "testing"  
  
    "<project>/ent/enttest"  
  
    _ "github.com/mattn/go-sqlite3"  
)  
  
func TestXXX(t *testing.T) {  
    client := enttest.Open(t, "sqlite3", "file:ent?mode=memory&_fk=1")  
    defer client.Close()  
    // ...  
}  

```

--------------------------------

### Install Atlas using curl

Source: https://entgo.io/docs/getting-started

Installs the latest release of Atlas by downloading and executing the installation script. This is a common method for macOS and Linux users.

```bash
curl -sSf https://atlasgo.sh | sh  

```

--------------------------------

### Initialize Go Module

Source: https://entgo.io/docs/grpc-setting-up

Commands to create a new directory and initialize a Go module for the project.

```bash
mkdir ent-grpc-example  
cd ent-grpc-example  
go mod init ent-grpc-example  
```

--------------------------------

### Create gRPC Server with Ent

Source: https://entgo.io/docs/grpc-server-and-client

Initializes an Ent client, runs migrations, creates a gRPC server, registers the Ent service, and starts listening on port 5000. Requires the go-sqlite3 driver.

```go
package main

import (
    "context"
    "log"
    "net"

    _ "github.com/mattn/go-sqlite3"
    "ent-grpc-example/ent"
    "ent-grpc-example/ent/proto/entpb"
    "google.golang.org/grpc"
)

func main() {
    // Initialize an ent client.
    client, err := ent.Open("sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("failed opening connection to sqlite: %v", err)
    }
    defer client.Close()

    // Run the migration tool (creating tables, etc).
    if err := client.Schema.Create(context.Background()); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }

    // Initialize the generated User service.
    svc := entpb.NewUserService(client)

    // Create a new gRPC server (you can wire multiple services to a single server).
    server := grpc.NewServer()

    // Register the User service with the server.
    entpb.RegisterUserServiceServer(server, svc)

    // Open port 5000 for listening to traffic.
    lis, err := net.Listen("tcp", ":5000")
    if err != nil {
        log.Fatalf("failed listening: %s", err)
    }

    // Listen for traffic indefinitely.
    if err := server.Serve(lis); err != nil {
        log.Fatalf("server ended: %s", err)
    }
}
```

--------------------------------

### Ent Client and Schema Creation Example

Source: https://entgo.io/docs/tutorial-setup

Instantiates an Ent client with an in-memory SQLite database and runs automatic migration to create schema resources. Ensure the 'todo' package and necessary imports are correctly set up.

```go
package todo

import (
    "context"
    "log"
    "todo/ent"

    "entgo.io/ent/dialect"
    _ "github.com/mattn/go-sqlite3"
)

func Example_Todo() {
    // Create an ent.Client with in-memory SQLite database.
    client, err := ent.Open(dialect.SQLite, "file:ent?mode=memory&cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("failed opening connection to sqlite: %v", err)
    }
    defer client.Close()
    ctx := context.Background()
    // Run the automatic migration tool to create all schema resources.
    if err := client.Schema.Create(ctx); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }
    // Output:
}
```

--------------------------------

### Initialize Go Module

Source: https://entgo.io/docs/code-gen

Initialize a new Go module for projects not currently using one.

```bash
go mod init <project>  
```

--------------------------------

### Create PostgreSQL Client and Schema

Source: https://entgo.io/docs/getting-started

This Go code shows how to connect to a PostgreSQL database using Ent and execute the schema creation. Replace placeholder connection details with your actual credentials.

```go
package main

import (
    "context"
    "log"

    "entdemo/ent"

    _ "github.com/lib/pq"
)

func main() {
    client, err := ent.Open("postgres","host=<host> port=<port> user=<user> dbname=<database> password=<pass>")
    if err != nil {
        log.Fatalf("failed opening connection to postgres: %v", err)
    }
    defer client.Close()
    // Run the auto migration tool.
    if err := client.Schema.Create(context.Background()); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }
}

```

--------------------------------

### Create MySQL Client and Schema

Source: https://entgo.io/docs/getting-started

This Go code demonstrates connecting to a MySQL database with Ent and performing schema migrations. Ensure you provide the correct user, password, host, port, and database name.

```go
package main

import (
    "context"
    "log"

    "entdemo/ent"

    _ "github.com/go-sql-driver/mysql"
)

func main() {
    client, err := ent.Open("mysql", "<user>:<pass>@tcp(<host>:<port>)/<database>?parseTime=True")
    if err != nil {
        log.Fatalf("failed opening connection to mysql: %v", err)
    }
    defer client.Close()
    // Run the auto migration tool.
    if err := client.Schema.Create(context.Background()); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }
}

```

--------------------------------

### Example atlas.sum file content

Source: https://entgo.io/docs/versioned-migrations

This is an example of the content found in an `atlas.sum` file, which stores checksums for migration files.

```plaintext
h1:KRFsSi68ZOarsQAJZ1mfSiMSkIOZlMq4RzyF//Pwf8A
20220318104614_team_A.sql h1:EGknG5Y6GQYrc4W8e/r3S61Aqx2p+NmQyVz/2m8ZNwA=

```

--------------------------------

### Hook into Atlas Diff and Apply Processes

Source: https://entgo.io/docs/migrate

This example demonstrates how to hook into both the Atlas Diff and Apply steps during schema creation. It shows how to intercept and potentially modify the diff changes or the apply process.

```go
package main  
  
import (  
    "context"  
    "log"  
  
    "<project>/ent"  
    "<project>/ent/migrate"  
  
    "ariga.io/atlas/sql/migrate"  
    atlas "ariga.io/atlas/sql/schema"  
    "entgo.io/ent/dialect"  
    "entgo.io/ent/dialect/sql/schema"  
)  
  
func main() {  
    client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")  
    if err != nil {  
        log.Fatalf("failed connecting to mysql: %v", err)  
    }  
    defer client.Close()  
    ctx := context.Background()  
    // Run migration.  
    err :=  client.Schema.Create(  
        ctx,  
        // Hook into Atlas Diff process.  
        schema.WithDiffHook(func(next schema.Differ) schema.Differ {  
            return schema.DiffFunc(func(current, desired *atlas.Schema) ([]atlas.Change, error) {  
                // Before calculating changes.  
                changes, err := next.Diff(current, desired)  
                if err != nil {  
                    return nil, err  
                }  
                // After diff, you can filter  
                // changes or return new ones.  
                return changes, nil  
            })  
        }),  
        // Hook into Atlas Apply process.  
        schema.WithApplyHook(func(next schema.Applier) schema.Applier {  
            return schema.ApplyFunc(func(ctx context.Context, conn dialect.ExecQuerier, plan *migrate.Plan) error {  
                // Example to hook into the apply process, or implement  
                // a custom applier. For example, write to a file.  
                //  
                //  for _, c := range plan.Changes {  
                //      fmt.Printf("%s: %s", c.Comment, c.Cmd)  
                //      if err := conn.Exec(ctx, c.Cmd, c.Args, nil); err != nil {  
                //          return err  
                //      }  
                //  }  
                //  
                return next.Apply(ctx, conn, plan)  
            })  
        }),  
    )  
    if err != nil {  
        log.Fatalf("failed creating schema resources: %v", err)  
    }  
}  

```

--------------------------------

### Implementing an Apply Hook for Schema Migration

Source: https://entgo.io/docs/migrate

Demonstrates how to use schema.WithApplyHook to execute custom SQL updates during the schema creation process.

```go
func main() {  
    client, err := ent.Open("mysql", "root:pass@tcp(localhost:3306)/test")  
    if err != nil {  
        log.Fatalf("failed connecting to mysql: %v", err)  
    }  
    defer client.Close()  
    // ...  
    if err := client.Schema.Create(ctx, schema.WithApplyHook(fillNulls)); err != nil {  
        log.Fatalf("failed creating schema resources: %v", err)  
    }  
}  
  
func fillNulls(next schema.Applier) schema.Applier {  
    return schema.ApplyFunc(func(ctx context.Context, conn dialect.ExecQuerier, plan *migrate.Plan) error {  
        // There are three ways to UPDATE the NULL values to "Unknown" in this stage.  
        // Append a custom migrate.Change to the plan, execute an SQL statement directly  
        // on the dialect.ExecQuerier, or use the ent.Client used by the project.  
  
        // Execute a custom SQL statement.  
        query, args := sql.Dialect(dialect.MySQL).  
            Update(user.Table).  
            Set(user.FieldDropOptional, "Unknown").  
            Where(sql.IsNull(user.FieldDropOptional)).  
            Query()  
        if err := conn.Exec(ctx, query, args, nil); err != nil {  
            return err  
        }  
  
        // Append a custom statement to migrate.Plan.  
        //  
        //  plan.Changes = append([]*migrate.Change{  
        //      {  
        //          Cmd: fmt.Sprintf("UPDATE users SET %[1]s = '%[2]s' WHERE %[1]s IS NULL", user.FieldDropOptional, "Unknown"),  
        //      },  
        //  }, plan.Changes...)  
  
        // Use the ent.Client used by the project.  
        //  
        //  drv := sql.NewDriver(dialect.MySQL, sql.Conn{ExecQuerier: conn.(*sql.Tx)})  
        //  if err := ent.NewClient(ent.Driver(drv)).  
        //      User.  
        //      Update().  
        //      SetDropOptional("Unknown").  
        //      Where(/* Add predicate to filter only rows with NULL values */).  
        //      Exec(ctx); err != nil {  
        //      return fmt.Errorf("fix default values to uppercase: %w", err)  
        //  }  
  
        return next.Apply(ctx, conn, plan)  
    })  
}  
```

--------------------------------

### Install Atlas using Homebrew

Source: https://entgo.io/docs/getting-started

Installs the latest release of Atlas using the Homebrew package manager. This is a convenient option for macOS users.

```bash
brew install ariga/tap/atlas  

```

--------------------------------

### Install Atlas using Homebrew

Source: https://entgo.io/docs/migration/extensions

Installs Atlas using the Homebrew package manager on macOS. Ensures you have the latest version available through the Ariga tap.

```bash
brew install ariga/tap/atlas
```

--------------------------------

### Initialize New Schema

Source: https://entgo.io/docs/code-gen

Create new schema templates within the ent/schema directory.

```bash
go run -mod=mod entgo.io/ent/cmd/ent new User Pet  
```

--------------------------------

### Install PostGIS Extension using SQL

Source: https://entgo.io/docs/migration/extensions

SQL command to install the PostGIS extension in a PostgreSQL database. This enables spatial data types and functions.

```sql
CREATE EXTENSION postgis;
```

--------------------------------

### Pull and Run Atlas Docker Image

Source: https://entgo.io/docs/getting-started

Pulls the latest Atlas Docker image and runs a help command to verify the installation. Useful for testing Atlas without local installation.

```bash
docker pull arigaio/atlas  
docker run --rm arigaio/atlas --help  

```

--------------------------------

### Initialize Go Module

Source: https://entgo.io/docs/getting-started

Use this command to initialize a new Go module project if your project directory is outside GOPATH or you are not familiar with GOPATH.

```bash
go mod init entdemo
```

--------------------------------

### UserService Get Method Implementation

Source: https://entgo.io/docs/grpc-edges

Implements the Get method for the UserService, handling different view options to conditionally fetch edge information. It queries for edge IDs when `WITH_EDGE_IDS` is specified.

```go
// Get implements UserServiceServer.Get
func (svc *UserService) Get(ctx context.Context, req *GetUserRequest) (*User, error) {
    // .. truncated ..
    switch req.GetView() {
    case GetUserRequest_VIEW_UNSPECIFIED, GetUserRequest_BASIC:
        get, err = svc.client.User.Get(ctx, int(req.GetId()))
    case GetUserRequest_WITH_EDGE_IDS:
        get, err = svc.client.User.Query().
            Where(user.ID(int(req.GetId()))).
            WithAdministered(func(query *ent.CategoryQuery) {
                query.Select(category.FieldID)
            }).
            Only(ctx)
    default:
        return nil, status.Errorf(codes.InvalidArgument, "invalid argument: unknown view")
    }
// .. truncated ..
}

```

--------------------------------

### Create Test File

Source: https://entgo.io/docs/tutorial-setup

Create an empty file to hold the test case.

```bash
touch example_test.go
```

--------------------------------

### Usage Example for Enum Fields

Source: https://entgo.io/docs/schema-fields

After code generation, enum fields can be set and queried using their defined constants and values. This example shows setting and retrieving user data with various enum types.

```go
client.User.Create().  
    SetFirstName("John").  
    SetLastName("Dow").  
    SetSize(user.SizeSmall).  
    SetShape(property.Triangle).  
    SetLevel(property.Low).  
    SaveX(context.Background())  
      
john := client.User.Query().FirstX(context.Background())  
fmt.Println(john)  
// User(id=1, first_name=John, last_name=Dow, size=small, shape=TRIANGLE, level=LOW)  


```

--------------------------------

### Generated GraphQL Schema

Source: https://entgo.io/docs/tutorial-todo-gql

Example of the generated GraphQL schema file.

```graphql
directive @goField(forceResolver: Boolean, name: String) on FIELD_DEFINITION | INPUT_FIELD_DEFINITION  
directive @goModel(model: String, models: [String!]) on OBJECT | INPUT_OBJECT | SCALAR | ENUM | INTERFACE | UNION  
"""
Define a Relay Cursor type:  
https://relay.dev/graphql/connections.htm#sec-Cursor  
"""
scalar Cursor  
"""
An object with an ID.  
Follows the [Relay Global Object Identification Specification](https://relay.dev/graphql/objectidentification.htm)  
"""
interface Node @goModel(model: "todo/ent.Noder") {  
  """The id of the object."""
  id: ID!  
}  
  
# ...  
```

--------------------------------

### Create SQLite Client and Schema

Source: https://entgo.io/docs/getting-started

This Go code demonstrates how to open a connection to an in-memory SQLite database using Ent and run the automatic schema migration.

```go
package main

import (
    "context"
    "log"

    "entdemo/ent"

    _ "github.com/mattn/go-sqlite3"
)

func main() {
    client, err := ent.Open("sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("failed opening connection to sqlite: %v", err)
    }
    defer client.Close()
    // Run the auto migration tool.
    if err := client.Schema.Create(context.Background()); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }
}

```

--------------------------------

### Configure Separate Read and Write Database Connections

Source: https://entgo.io/docs/faq

Implement a custom `dialect.Driver` by wrapping existing drivers to separate read and write database operations. This example demonstrates a `multiDriver` that directs queries to a read replica unless a mutation is detected.

```go
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()
}

```

--------------------------------

### Install entproto Package

Source: https://entgo.io/docs/grpc-setting-up

Adds the entproto contribution package to the project dependencies.

```bash
go get -u entgo.io/contrib/entproto  
```

--------------------------------

### Configure Generate File

Source: https://entgo.io/docs/code-gen

Create a generate.go file to automate code generation via go generate.

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

--------------------------------

### Traverse Graph Edges

Source: https://entgo.io/docs/traversals

Perform a multi-step traversal starting from a Group entity.

```go
func Traverse(ctx context.Context, client *ent.Client) error {  
    owner, err := client.Group.         // GroupClient.  
        Query().                        // Query builder.  
        Where(group.Name("Github")).    // Filter only Github group (only 1).  
        QueryAdmin().                   // Getting Dan.  
        QueryFriends().                 // Getting Dan's friends: [Ariel].  
        QueryPets().                    // Their pets: [Pedro, Xabi].  
        QueryFriends().                 // Pedro's friends: [Coco], Xabi's friends: [].  
        QueryOwner().                   // Coco's owner: Alex.  
        Only(ctx)                       // Expect only one entity to return in the query.  
    if err != nil {  
        return fmt.Errorf("failed querying the owner: %w", err)  
    }  
    fmt.Println(owner)  
    // Output:  
    // User(id=3, age=37, name=Alex)  
    return nil  
}  
```

--------------------------------

### Offset Query Results

Source: https://entgo.io/docs/paging

Sets the starting point for the returned entities in a query.

```go
users, err := client.User.  
    Query().  
    Offset(10).  
    All(ctx)  

```

--------------------------------

### Generate Initial Migration File

Source: https://entgo.io/docs/versioned/programmatically

Executes the Go migration script to create the initial migration file. The 'initial' argument is a label for the migration and can be any descriptive name.

```bash
go run -mod=mod ent/migrate/main.go initial  

```

--------------------------------

### Create Multiple Todo Items with Text

Source: https://entgo.io/docs/tutorial-todo-crud

Example of creating two Todo items, setting their text, and printing their IDs and text. This demonstrates setting required fields after schema updates.

```go
func Example_Todo() {
    // ...
    task1, err := client.Todo.Create().SetText("Add GraphQL Example").Save(ctx)
    if err != nil {
        log.Fatalf("failed creating a todo: %v", err)
    }
    fmt.Printf("%d: %q\n", task1.ID, task1.Text)
    task2, err := client.Todo.Create().SetText("Add Tracing Example").Save(ctx)
    if err != nil {
        log.Fatalf("failed creating a todo: %v", err)
    }
    fmt.Printf("%d: %q\n", task2.ID, task2.Text)
    // Output:
    // 1: "Add GraphQL Example"
    // 2: "Add Tracing Example"
}
```

--------------------------------

### Execute CreateTodo Mutation

Source: https://entgo.io/docs/tutorial-todo-gql

Example mutation request to create a new todo item.

```graphql
mutation CreateTodo {  
    createTodo(input: {text: "Create GraphQL Example", status: IN_PROGRESS, priority: 1}) {  
        id  
        text  
        createdAt  
        priority  
    }  
}  

```

--------------------------------

### Generated Edge Resolver

Source: https://entgo.io/docs/graphql

Example of an automatically generated edge resolver for a Todo node.

```go
func (t *Todo) Children(ctx context.Context) ([]*Todo, error) {  
    result, err := t.Edges.ChildrenOrErr()  
    if IsNotLoaded(err) {  
        result, err = t.QueryChildren().All(ctx)  
    }  
    return result, err  
}  
```

--------------------------------

### GraphQL query for fields collection

Source: https://entgo.io/docs/graphql

Example query demonstrating nested edge fetching.

```graphql
query {  
  users(first: 100) {  
    edges {  
      node {  
        photos {  
          link  
        }  
        posts {  
          content  
          comments {  
            content  
          }  
        }  
      }  
    }  
  }  
}  
```

--------------------------------

### Use ordering in GraphQL query

Source: https://entgo.io/docs/graphql

Example of executing a paginated query with sorting applied.

```graphql
query {  
    todos(first: 3, orderBy: {direction: DESC, field: TEXT}) {  
        edges {  
            node {  
                text  
            }  
        }  
    }  
}  
```

--------------------------------

### View Generate Help

Source: https://entgo.io/docs/code-gen

Display command-line options and flags for the generate command.

```bash
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  
      --storage string        storage driver to support in codegen (default "sql")  
      --target string         target directory for codegen  
      --template strings      external templates to execute  
```

--------------------------------

### Configure gqlgen for Ent

Source: https://entgo.io/docs/graphql

Example configuration for mapping Ent types to GraphQL models.

```yaml
schema:  
  - todo.graphql  
  
resolver:  
  # Tell gqlgen to generate resolvers next to the schema file.  
  layout: follow-schema  
  dir: .  
  
# gqlgen will search for any type names in the schema in the generated  
# ent package. If they match it will use them, otherwise it will new ones.  
autobind:  
  - entgo.io/contrib/entgql/internal/todo/ent  
  
models:  
  ID:  
    model:  
      - github.com/99designs/gqlgen/graphql.IntID  
  Node:  
    model:  
      # ent.Noder is the new interface generated by the Node template.  
      - entgo.io/contrib/entgql/internal/todo/ent.Noder  
```

--------------------------------

### Offset Query Results

Source: https://entgo.io/docs/paging

The `Offset` method specifies the starting point for returned records.

```APIDOC
## Offset Query Results

### Description
Sets the first node to return from the query.

### Method
`Offset(n)`

### Example
```go
users, err := client.User.Query().Offset(10).All(ctx)
```
```

--------------------------------

### Generate SQL Migration File

Source: https://entgo.io/docs/data-migrations

This Go code snippet demonstrates how to create a new user with specific attributes and then flush the changes to generate a migration file. Ensure the 'w.FlushChange' function is correctly implemented to write the migration.

```go
client.User.Create().SetName("nati").SetAge(1).SetTags([]string{"bar"}), 
    ).Exec(context.Background()) 
    if err != nil { 
        return fmt.Errorf("failed generating statement: %w", err) 
    } 
  
    // Write the content to the migration directory. 
    return w.FlushChange( 
        "seed_users", 
        "Add the initial users to the database.", 
    )
```

--------------------------------

### Create Schema Resources

Source: https://entgo.io/docs/migrate

Run the auto-migration logic in the initialization of the application to create all database resources needed for your ent project. By default, Create works in an "append-only" mode.

```go
if err := client.Schema.Create(ctx); err != nil {
    log.Fatalf("failed creating schema resources: %v", err)
}

```

--------------------------------

### Example of Creating Cities and Streets with Uniqueness Constraint

Source: https://entgo.io/docs/schema-indexes

Demonstrates creating cities and streets, including an operation that is expected to fail due to a unique constraint violation on street names within the same city. Uses `SaveX` for operations that panic on error.

```go
func Do(ctx context.Context, client *ent.Client) error {
    // Unlike `Save`, `SaveX` panics if an error occurs.
    tlv := client.City.
        Create().
        SetName("TLV").
        SaveX(ctx)
    nyc := client.City.
        Create().
        SetName("NYC").
        SaveX(ctx)
    // Add a street "ST" to "TLV".
    client.Street.
        Create().
        SetName("ST").
        SetCity(tlv).
        SaveX(ctx)
    // This operation fails because "ST"  
    // was already created under "TLV".
    if err := client.Street.
        Create().
        SetName("ST").
        SetCity(tlv).
        Exec(ctx); err == nil {
        return fmt.Errorf("expecting creation to fail")
    }
    // Add a street "ST" to "NYC".
    client.Street.
        Create().
        SetName("ST").
        SetCity(nyc).
        SaveX(ctx)
    return nil
}

```

--------------------------------

### Checksum error output

Source: https://entgo.io/docs/versioned/custom-migrations

Example error message displayed by Atlas when migration directory integrity is compromised.

```text
You have a checksum error in your migration directory.  
This happens if you manually create or edit a migration file.  
Please check your migration files and run  
  
'atlas migrate hash'  
  
to re-hash the contents and resolve the error  
  
Error: checksum mismatch
```

--------------------------------

### Generated Filter Input Types

Source: https://entgo.io/docs/tutorial-todo-gql-filter-input

Examples of the generated Go struct and GraphQL input type for filtering.

```go
// TodoWhereInput represents a where input for filtering Todo queries.
type TodoWhereInput struct {
    Not *TodoWhereInput   `json:"not,omitempty"`
    Or  []*TodoWhereInput `json:"or,omitempty"`
    And []*TodoWhereInput `json:"and,omitempty"`

    // "created_at" field predicates.
    CreatedAt      *time.Time  `json:"createdAt,omitempty"`
    CreatedAtNEQ   *time.Time  `json:"createdAtNEQ,omitempty"`
    CreatedAtIn    []time.Time `json:"createdAtIn,omitempty"`
    CreatedAtNotIn []time.Time `json:"createdAtNotIn,omitempty"`
    CreatedAtGT    *time.Time  `json:"createdAtGT,omitempty"`
    CreatedAtGTE   *time.Time  `json:"createdAtGTE,omitempty"`
    CreatedAtLT    *time.Time  `json:"createdAtLT,omitempty"`
    CreatedAtLTE   *time.Time  `json:"createdAtLTE,omitempty"`

    // "status" field predicates.
    Status      *todo.Status  `json:"status,omitempty"`
    StatusNEQ   *todo.Status  `json:"statusNEQ,omitempty"`
    StatusIn    []todo.Status `json:"statusIn,omitempty"`
    StatusNotIn []todo.Status `json:"statusNotIn,omitempty"`

    // .. truncated ..
}
```

```graphql
"""
TodoWhereInput is used for filtering Todo objects.
Input was generated by ent.
"""
input TodoWhereInput {
  not: TodoWhereInput
  and: [TodoWhereInput!]
  or: [TodoWhereInput!]

  """created_at field predicates"""
  createdAt: Time
  createdAtNEQ: Time
  createdAtIn: [Time!]
  createdAtNotIn: [Time!]
  createdAtGT: Time
  createdAtGTE: Time
  createdAtLT: Time
  createdAtLTE: Time

  """status field predicates"""
  status: Status
  statusNEQ: Status
  statusIn: [Status!]
  statusNotIn: [Status!]

  # .. truncated ..
}
```

--------------------------------

### Access Injected Dependencies in Application Code

Source: https://entgo.io/docs/code-gen

Demonstrates how to pass injected dependencies during client initialization and access them within hooks.

```go
func Example_Deps() {  
    client, err := ent.Open(  
        "sqlite3",  
        "file:ent?mode=memory&cache=shared&_fk=1",  
        ent.Writer(os.Stdout),  
        ent.HTTPClient(http.DefaultClient),  
    )  
    if err != nil {  
        log.Fatalf("failed opening connection to sqlite: %v", err)  
    }  
    defer client.Close()  
    // An example for using the injected dependencies in the generated builders.  
    client.User.Use(func(next ent.Mutator) ent.Mutator {  
        return hook.UserFunc(func(ctx context.Context, m *ent.UserMutation) (ent.Value, error) {  
            _ = m.HTTPClient  
            _ = m.Writer  
            return next.Mutate(ctx, m)  
        })  
    })  
    // ...  
}  
```
Tokens:
Raw