goent

GoEnt

GO Entity or just "GoEnt" is an easy-to-use ORM for Go

Requirements

• go v1.26 or above

Real world examples

GoEnt has examples of queries and integrations, if you have a nice example and want to see if GoEnt can handle it, just try out.

Common examples are:

• How to use GoEnt with other frameworks;
• Where GoEnt key features can shine;

Features

Check out the Benchmarks section for an overview of GoEnt performance compared to other packages like ent, GORM, sqlc, and others.

• 🔖 Type Safety;
  • Get errors at compile time
• 📦 Auto Migrations;
  • Automatically generate tables from your structs
• 📄 SQL Like queries;
  • Use Go code to write queries with well-known functions
• 🗂️ Iterator
  • Range over function to iterate over rows
• 📚 Pagination
  • Paginate your large selects with just a function call
• ♻️ Wrappers
  • Wrappers for simple queries and builders for complex ones

Content

• Install
• Available Drivers
  • PostgreSQL
  • SQLite
• Quick Start
• Database
  • Supported Types
  • Struct Mapping
  • Setting primary key
  • Setting type
  • Setting null
  • Setting default
  • Relationship
    • One to One
    • Many to One
    • Many to Many
    • Self Referential
  • Index
    • Create Index
    • Unique Index
    • Two Columns Index
    • Function Index
  • Schemas
  • Logging
  • Open
  • Migrate
    • Auto Migrate
    • Drop and Rename
    • Migrate to a SQL file
• Select
  • Find
  • Select Specific Fields
  • Select Iterator
  • Where
  • Filter (Non-Zero Dynamic Where)
  • Match (Non-Zero Dynamic Where)
  • Join
  • Order By
  • Group By
  • Pagination
  • Aggregates
  • Functions
• Insert
  • Insert One
  • Insert Batch
• Update
  • Save
  • Update Set
• Delete
  • Delete Batch
• Transaction
  • Begin Transaction
  • Manual Transaction
    • Commit and Rollback
    • Save Point
• Benchmarks
• Code Generation

Install

go get github.com/azhai/goent

As with any database/sql support in Go, you have to get a specific driver for your database. Check Available Drivers

Available Drivers

• PostgreSQL
• SQLite

go get github.com/azhai/goent

Usage

import (
	"github.com/azhai/goent"
	"github.com/azhai/goent/drivers/pgsql"
)

type Animal struct {
	// animal fields
}

type Database struct {
	Animal *goent.Table[Animal]
	*goent.DB
}

dsn := "postgres://dba:[email protected]:5432/test?sslmode=disable"
db, err := goent.Open[Database](pgsql.Open(dsn), "stdout")
// db, err := goent.Open[Database](sqlite.Open("goent.db"), "stdout")

Quick Start

package main

import (
	"fmt"

	"github.com/azhai/goent"
	"github.com/azhai/goent/drivers/sqlite"
)

type Animal struct {
	ID    int
	Name  string
	Emoji string
}

type PublicSchema struct {
	Animal *goent.Table[Animal]
}

type Database struct {
	PublicSchema `goe:"public"`
	*goent.DB
}

func main() {
	db, err := goent.Open[Database](sqlite.Open("goent.db"), "stdout")
	if err != nil {
		panic(err)
	}
	defer goent.Close(db)

	err = goent.AutoMigrate(db)
	if err != nil {
		panic(err)
	}

	err = db.Animal.Delete().Exec()
	if err != nil {
		panic(err)
	}

	animals := []*Animal{
		{Name: "Cat", Emoji: "🐈"},
		{Name: "Dog", Emoji: "🐕"},
		{Name: "Rat", Emoji: "🐀"},
		{Name: "Pig", Emoji: "🐖"},
		{Name: "Whale", Emoji: "🐋"},
		{Name: "Fish", Emoji: "🐟"},
		{Name: "Bird", Emoji: "🐦"},
	}

	// Insert all animals in a single transaction
	// retPK = false is 5 times faster than retPK = true
	err = db.Animal.Insert().All(false, animals)
	if err != nil {
		panic(err)
	}

	animals, err = db.Animal.Select().All()
	if err != nil {
		panic(err)
	}
	fmt.Println(animals)
}

To run the quick start follow this steps:

1. Init the go.mod file

   go mod init quickstart
   

2. Get the necessary packages:

   go mod tidy
   

3. Run the example:

   go run main.go
   

4. If everything was ok, you should see a output like this:

   [{1 Cat 🐈} {2 Dog 🐕} {3 Rat 🐀} {4 Pig 🐖} {5 Whale 🐋} {6 Fish 🐟} {7 Bird 🐦}]
   

Database

type Database struct {
	User    	*goent.Table[User]
	Role    	*goent.Table[Role]
	UserLog 	*goent.Table[UserLog]
	*goent.DB
}

In GoEnt, it's necessary to define a Database struct, this struct implements *goent.DB and pointers to all the structs that are to be mapped.

It's through the Database struct that you will interact with your database.

Supported Types

GoEnt supports any type that implements the Scanner Interface. Most common are sql.Null types from database/sql package.

type Table struct {
	Price      decimal.Decimal     `goe:"type:decimal(10,4)"`
	NullID     sql.Null[uuid.UUID] `goe:"type:uuid"`
	NullString sql.NullString      `goe:"type:varchar(100)"`
}

Back to Contents

Struct mapping

type User struct {
	ID        	uint //this is primary key
	Login     	string
	Password  	string
}

[!NOTE] By default, the field "ID" is the primary key and all integer IDs are auto-incrementing.

Back to Contents

Table Name Resolution

Table names are resolved in the following order:

1. TableName() method - If the struct implements TableName() string, that value is used directly
2. Struct name in snake_case with prefix - If no TableName() method, the struct name is converted to snake_case, with optional prefix: from schema tag prepended

The schema tag format is: goe:"schema_name;prefix:table_prefix"

// Method 1: TableName() method (returns exact table name, no prefix added)
type OrderDetail struct {
    OrderID   int64 `goe:"pk;not_incr"`
    ProductID int64 `goe:"pk;not_incr"`
}

func (*OrderDetail) TableName() string {
    return "t_order_detail"  // Exact table name, prefix is ignored
}

// Method 2: Auto-generated from struct name with prefix
type PublicSchema struct {
    User     *goent.Table[User]     // Table: t_user (with prefix t_)
    Category *goent.Table[Category] // Table: t_category
}

type Database struct {
    PublicSchema `goe:"public;prefix:t_"`  // schema=public, prefix=t_
    *goent.DB
}

// Without prefix
type AuthSchema struct {
    Role *goent.Table[Role]  // Table: role (no prefix)
}

type Database struct {
    AuthSchema `goe:"auth"`  // schema=auth, no prefix
    *goent.DB
}

Back to Contents

Setting primary key

type User struct {
	Identifier	uint `goe:"pk"`
	Login     	string
	Password	string
}

If you want to specify a primary key, use the tag value "pk".

Composite Primary Key

type OrderDetail struct {
	OrderID   int `goe:"pk;not_incr"`
	ProductID int `goe:"pk;not_incr"`
	Quantity  int
}

Use multiple pk tags to create a composite primary key. Add not_incr to prevent auto-incrementing on primary key columns.

Non-Auto-Increment Primary Key

type User struct {
	ID   string `goe:"pk;not_incr;default:uuid_generate_v4()"`
	Name string
}

Use the not_incr tag to prevent auto-incrementing behavior on primary key columns. This is useful for UUID or string primary keys.

Back to Contents

Setting type

type User struct {
	ID       	string `goe:"pk;type:uuid"`
	Login    	string `goe:"type:varchar(10)"`
	Name     	string `goe:"type:varchar(150)"`
	Password 	string `goe:"type:varchar(60)"`
}

You can specify a type using the tag value "type"

Back to Contents

Setting null

type User struct {
	ID        int
	Name      string
	Email     *string // this will be a null column
	Phone     sql.NullString `goe:"type:varchar(20)"` // also null
}

[!IMPORTANT] A pointer is considered a null column in Database.

Back to Contents

Setting default

type User struct {
	ID        int
	Name      string
	Email     *string
	CreatedAt  time.Time `goe:"default:current_timestamp"`
}

A default value is used when the field is inserted without a value.

// CreatedAt will have the default value
err = db.User.Insert().One(&User{Name: "Rose"})

if err != nil {
	// Handle error
}

Primary Key with Default Value

For non-auto-increment primary keys, you can specify a default value:

type Default struct {
	ID   string `goe:"default:'Default'"` // Primary key with default value
	Name string
}

When inserting, the default value is automatically set on the struct:

// d := Default{Name: "Test"}
// err = db.Default.Insert().One(&d)

// recommend:
d := &Default{Name: "Test"}
err = db.Default.Insert().One(d)

// d.ID == "Default" (set from default value)

if err != nil {
	// Handle error
}

[!NOTE] For primary keys with default values, the value is set on the struct before INSERT, and the column is included in the INSERT statement. This is different from auto-increment primary keys, where the column is excluded and the ID is retrieved using last_insert_rowid().

Back to Contents

Relationship

In GoEnt relational fields are created using the pattern TargetTable+TargetTableID, so if you want to have a foreign key to User, you will have to write a field like UserID or UserIDOrigin.

One To One

type User struct {
	ID       	uint
	Login    	string
	Name     	string
	Password 	string
}

type UserDetails struct {
	ID       	uint
	Email   	string
	Birthdate 	time.Time
	UserID   	uint  // one to one with User
}

Back to Contents

Many To One

For simplifications all relational slices should be the last fields on struct.

type User struct {
	ID       	uint
	Name     	string
	Password 	string
	UserLogs 	[]UserLog // one User has many UserLogs
}

type UserLog struct {
	ID       	uint
	Action   	string
	DateTime 	time.Time
	UserID   	uint // if remove the slice from user, will become a one to one
}

The difference from one to one and many to one it's a slice field on the "many" struct.

Back to Contents

Many to Many

For simplifications all relational slices should be the last fields on struct.

Using implicit many to many:

type Person struct {
	ID   int
	Name string
	Jobs []Job // Person has a slice to Jobs
}

// Person and Job are implicit relational
type PersonJob struct {
	PersonID   int `goe:"pk"`
	JobID      int `goe:"pk"`
	CreatedAt  time.Time
}

type Job struct {
	Name    string
	ID      int
	Persons []Person // Job has a slice to Person
}

[!IMPORTANT] It's used the tags "pk" for ensure that the foreign keys will be both primary key.

Using many to one pattern:

type User struct {
	ID       	uint
	Name     	string
	Password 	string
	UserRoles 	[]UserRole
}

type UserRole struct {
	UserID  	uint `goe:"pk"`
	RoleID  	uint `goe:"pk"`
}

type Role struct {
	ID        	uint
	Name      	string
	UserRoles 	[]UserRole
}

Is used a combination of two many to one to generate a many to many. In this example, User has many UserRole and Role has many UserRole.

[!IMPORTANT] It's used the tags "pk" for ensure that the foreign keys will be both primary key.

Back to Contents

Self-Referential

One to Many

type Person struct {
	ID       int
	Name     string
	PersonID *int
	Family   []Person
}

One to One

type Page struct {
	ID         int
	Number     int
	PageIDNext *int
	PageIDPrev *int
}

Back to Contents

Index

Unique Index

type User struct {
	ID       	uint
	Name     	string
	Email    	string  `goe:"unique"`
}

To create a unique index you need the "unique" goe tag

Back to Contents

Create Index

type User struct {
	ID       uint
	Name     string
	Email 	 string `goe:"index"`
}

To create a common index you need the "index" goe tag

Back to Contents

Two Columns Index

type User struct {
	ID       uint
	Name    string `goe:"index(n:idx_name_status)"`
	Email   string `goe:"index(n:idx_name_status);unique"`
}

Using the goe tag "index()", you can pass the index infos as a function call. "n:" is a parameter for name, to have a two column index just need two indexes with same name. You can use the semicolon ";" to create another single index for the field.

Back to Contents

Two Columns Unique Index

type User struct {
	ID       uint
	Name    string `goe:"index(unique n:idx_name_status)"`
	Email   string `goe:"index(unique n:idx_name_status);unique"`
}

Just as creating a Two Column Index but added the "unique" value inside the index function.

Back to Contents

Function Index

type User struct {
	Id        int
	Name      string `goe:"index(n:idx_name_lower f:lower)"`
	Email     string `goe:"unique"`
	UserRoles []UserRole
}

Use the f: parameter to pass a function in the index tag.

Back to Contents

Schemas

On GoEnt it's possible to create schemas by the database struct, all schemas should have the suffix Schema or a tag goe:"schema".

[!IMPORTANT] Tables must be nested under schema structs. The hierarchy is: Database -> Schema -> Table. SQLite ignores schema names (tables are created directly in the main database).

type User struct {
	...
}

type UserRole struct {
	...
}

type Role struct {
	...
}
// schema with suffix Schema
type UserSchema struct {
	User     *goent.Table[User]
	UserRole *goent.Table[UserRole]
	Role     *goent.Table[Role]
}
// schema with any name
type Authentication struct {
	User     *goent.Table[User]
	UserRole *goent.Table[UserRole]
	Role     *goent.Table[Role]
}

type Database struct {
	*UserSchema // all structs on UserSchema will be created inside user schema
	*Authentication `goe:"schema"` // will create Authentication schema
	*goent.DB
}

[!TIP] On SQLite any schema will be a new attached db file.

Back to Contents

Logging

GoEnt supports any logger that implements the Logger interface

type Logger interface {
	InfoContext(ctx context.Context, msg string, kv ...any)
	WarnContext(ctx context.Context, msg string, kv ...any)
	ErrorContext(ctx context.Context, msg string, kv ...any)
}

The logger is defined on database opening

	db, err := drivers.QuickOpen[Database]("sqlite", "goent.db", "stdout")

[!TIP] You can use slog as your standard logger or make a adapt over the Logger interface.

Back to Contents

Open

To open a database use goent.Open function, it's require a valid driver. Most of the drives will require a dsn/path connection and a config setup. On goent.Open needs to specify the struct database.

If you don't need the database connection anymore, call goent.Close to ensure that all the database resources will be removed from memory.

type Database struct {
	Animal         *goent.Table[Animal]
	AnimalFood     *goent.Table[AnimalFood]
	Food           *goent.Table[Food]
	*goent.DB
}

dsn := "user=postgres password=postgres host=localhost port=5432 database=postgres"
db, err := facade.QuickOpen[Database]("pgsql", dsn, "")

if err != nil {
	// Handle error
}

Back to Contents

Migrate

Auto Migrate

To auto migrate the structs, use the goent.AutoMigrate(db) passing the database returned by goent.Open.

// migrate all database structs
err = goent.AutoMigrate(db)
if err != nil {
	// Handle error
}

Back to Contents

Drop and Rename

type Select struct {
	ID   int
	Name string
}

type Database struct {
	Select         *goent.Table[Select]
	*goent.DB
}

err = goent.AutoMigrate(db).OnTable("Select").RenameColumn("Name", "NewName")
if err != nil {
	// Handle error
}

err = goent.AutoMigrate(db).OnTable("Select").DropColumn("NewName")
if err != nil {
	// Handle error
}

err = goent.AutoMigrate(db).OnTable("Select").RenameTable("NewSelect")
if err != nil {
	// Handle error
}

err = goent.AutoMigrate(db).OnTable("NewSelect").DropTable()
if err != nil {
	// Handle error
}

Back to Contents

Migrate to a SQL file

GoEnt drivers supports a output migrate path to specify a directory to store the generated SQL. In this way, calling the "AutoMigrate" function goe WILL NOT auto apply the migrations and output the result as a sql file in the specified path.

// open the database with the migrate path config setup
db, err := goent.Open[Database](sqlite.Open("goent.db", sqlite.Config{
	MigratePath: "migrate/",
}))
if err != nil {
	// Handle error
}

// AutoMigrate will output the result as a sql file, and not auto apply the migration
err = goent.AutoMigrate(db)
if err != nil {
	// Handle error
}

In this example the file will be output in the "migrate/" path, as follow:

📂 migrate
|   ├── SQLite_1760042267.sql
go.mod

[!TIP] Any other migration like "DropTable", "RenameColumn" and others... will have the same result as "AutoMigrate", and will generate the SQL file.

Back to Contents

Select

Find

Find is used when you want to return a single result.

// one primary key
animal, err := db.Animal.Select().Match(Animal{ID: 2}).One()

// two primary keys
animalFood, err := db.AnimalFood.Select().Match(AnimalFood{IDAnimal: 3, IDFood: 2}).One()

// find record by value, if have more than one it will returns the first
cat, err := db.Animal.Select().Match(Animal{Name: "Cat"}).One()

[!TIP] Use goent.SelectContext for specify a context.

Back to Contents

Select

Select has support for OrderBy, Pagination and Join.

// select all animals
animals, err = db.Animal.Select().All()

// select the animals with name "Cat", ID "3" and IDHabitat "4"
animals, err = db.Animal.Select().Filter(EqualsMap(db.Animal.Field("id"), map[string]any{"name": "Cat", "id": 3})).All()

// when using % on filter, goent makes a like operation
animals, err = db.Animal.Select().Match(Animal{Name: "%Cat%"}).All()

[!TIP] Use goent.SelectContext for specify a context.

Back to Contents

Select Iterator

Iterate over the rows

for row, err := range db.Animal.Select().IterRows(nil) {
	// iterator rows
 }

Back to Contents

Select Specific Fields

var result []struct {
	User    string
	Role    *string
	EndTime *time.Time
}

// row is the generic struct
for row, err := range goent.Select[struct {
		User    string     // output row
		Role    *string    // output row
		EndTime *time.Time // output row
	}](db.User.Field("Name"), db.Role.Field("Name"), db.UserRole.Field("EndDate")).
	Join(goent.InnerJoin, db.UserRole.Table(), EqualsField(db.User.Field("id"), db.UserRole.Field("user_id"))).
	Join(goent.InnerJoin, db.Role.Table(), EqualsField(db.UserRole.Field("role_id"), db.Role.Field("id"))).
	OrderBy("id").IterRows(nil) {

	if err != nil {
		//handler error
	}
	//handler rows
	result = append(result, row)
}

For specific field is used a new struct, each new field guards the reference for the database attribute.

Back to Contents

Where

Where conditions are created using goent functions like Equals, And, Or, In, Like, etc.

animals, err = db.Animal.Select().Where("id = %s", 2).All()

if err != nil {
	//handler error
}

It's possible to group a list of where operations inside Filter()

animals, err = db.Animal.Select().Filter(
		goent.And(
			goent.LessEquals(db.Animal.Field("ID"), 2), 
			goent.In(db.Animal.Field("Name"), []string{"Cat", "Dog"}),
		),
	).All()

if err != nil {
	//handler error
}

You can use a if to call a where operation only if it's match

selectQuery := db.Animal.Select().Filter(goent.LessEquals(db.Animal.Field("ID"), 30))

if filter.In {
	selectQuery = selectQuery.Filter(
		goent.And(
			goent.LessEquals(db.Animal.Field("ID"), 30), 
			goent.In(db.Animal.Field("Name"), []string{"Cat", "Dog"}),
		),
	)
}

animals, err = selectQuery.All()

if err != nil {
	//handler error
}

It's possible to use a query inside a goent.In

// use AsQuery() for get a result as a query
querySelect := goent.Select[any](db.Animal.Field("Name")).
					Join(goent.InnerJoin, db.AnimalFood.Table(), EqualsField(db.Animal.Field("id"), db.AnimalFood.Field("animal_id"))).
					Join(goent.InnerJoin, db.Food.Table(), EqualsField(db.AnimalFood.Field("food_id"), db.Food.Field("id"))).
					Filter(
						goent.In(db.Food.Field("Name"), []string{foods[0].Name, foods[1].Name})).
					AsQuery()

// where in with another query
a, err := db.Animal.Select().Filter(goent.In(db.Animal.Field("Name"), querySelect)).All()

if err != nil {
	//handler error
}

On where, GoEnt supports operations on two columns, all where operations that have Arg as suffix it's used for operation on columns.

In the example, the operator greater (>) on the columns Score and Minimum is used to return all exams that have a score greater than the minimum.

err = db.Exam.Select().
	Filter(goent.GreaterArg[float32](db.Exam.Field("Score"), db.Exam.Field("Minimum"))).All()

Back to Contents

Filter (Non-Zero Dynamic Where)

Filter creates where operations on non-zero values, so if you want a dynamic where to show up only if has values, filter is the call.

var s []string
a, err = db.Animal.Select().
	Filter(
		goent.And(goent.In(db.Animal.Field("Name"), s),
			goent.And(goent.Equals(db.Animal.Field("Id"), 0),
				goent.And(
					goent.Equals(db.Animal.Field("Name"), ""),
					goent.Like(db.Animal.Field("Name"), "%o%"), // valid filter
				),
			),
		),
	).
	OrderBy("id DESC").All()

if err != nil {
	//handler error
}

[!TIP] It's possible to call Filter and Where on the same query.

Back to Contents

Match (Non-Zero Dynamic Where)

Match creates where operations on non-zero values using the query model. Match uses a LIKE operator with the ToUpper function on all string values.

// SELECT * FROM "status" where UPPER("status"."name") LIKE '%A%'
result, err := db.Status.Select().Match(Status{Name: "a"}).All()
if err != nil {
	//handler error
}

It's possible to use Match on Select

// SELECT "animals"."name", "foods"."name" FROM "animals"
// JOIN "animal_foods" on ("animals"."id" = "animal_foods"."animal_id")
// JOIN "food_habitat_schema"."foods" on ("animal_foods"."food_id" = "foods"."id")
// WHERE UPPER("foods"."name") LIKE '%A%'
result, err := goent.Select[struct {
	AnimalName string
	FoodName   string
}](db.Animal.Field("Name"), db.Food.Field("Name")).Match(struct {
	AnimalName string
	FoodName   string
}{FoodName: "a"}).
	Join(goent.InnerJoin, db.AnimalFood.Table(), EqualsField(db.Animal.Field("id"), db.AnimalFood.Field("animal_id"))).
	Join(goent.InnerJoin, db.Food.Table(), EqualsField(db.AnimalFood.Field("food_id"), db.Food.Field("id"))).All()

if err != nil {
	//handler error
}

[!TIP] It's possible to call Match and Where on the same query.

Back to Contents

Join

Join operations use goent constants like InnerJoin, LeftJoin, RightJoin.

For the join operations, you need to specify the type, this make the joins operations more safe. So if you change a type from a field, the compiler will throw a error.

animals, err = db.Animal.Select().
				Join(goent.InnerJoin, db.AnimalFood.Table(), EqualsField(db.Animal.Field("id"), db.AnimalFood.Field("animal_id"))).
				Join(goent.InnerJoin, db.Food.Table(), EqualsField(db.AnimalFood.Field("food_id"), db.Food.Field("id"))).
			   All()

if err != nil {
	//handler error
}

Same as where, you can use a if to only make a join if the condition match.

LeftJoin Helper Method

The LeftJoin method is a convenient helper for LEFT JOIN operations with automatic column selection:

// LeftJoin automatically selects columns from the joined table
orderDetails, err := db.OrderDetail.Select().
    LeftJoin("product_id", db.Product.Field("id")).
    Filter(goent.Equals(db.OrderDetail.Field("order_id"), orderID)).
    All()

// The Product field will be populated for each OrderDetail
for _, detail := range orderDetails {
    if detail.Product != nil {
        fmt.Printf("Product: %s, Price: %.2f\n", detail.Product.Name, detail.Product.Price)
    }
}

The LeftJoin method:

• Automatically adds the joined table's columns to the SELECT list
• Creates the JOIN condition using the local foreign key field and the referenced field
• Supports chaining multiple joins

// Multiple joins example
results, err := db.Person.Select().
    LeftJoin("id", db.PersonJobTitle.Field("person_id")).
    LeftJoin("job_title_id", db.JobTitle.Field("id")).
    Filter(goent.Equals(db.JobTitle.Field("name"), "Developer")).
    All()

[!NOTE] LeftJoin only populates non-slice foreign fields. For slice relationships (e.g., Jobs []JobTitle), use the standard Join method with manual column selection.

Back to Contents

Order By

For OrderBy you need to pass a reference to a mapped database field.

It's possible to OrderBy desc and asc. Select has support for OrderBy queries.

animals, err = db.Animal.Select().OrderBy("id DESC").All()

if err != nil {
	//handler error
}

Group By

For GroupBy you need to pass a reference to a mapped database field.

It's possible to GroupBy by a aggregate.

Select

habitatCount, err := goent.Select[struct {
	Name  string
	Count int64
}](db.Habitat.Field("Name"), aggregate.Count(db.Animal.Field("Id"))).Join(goent.InnerJoin, db.Habitat.Table(), EqualsField(db.Animal.Field("habitat_id"), db.Habitat.Field("id"))).
	OrderBy("count DESC").
	GroupBy("name").All()

if err != nil {
	//handler error
}

Back to Contents

Pagination

For pagination, it's possible to run on Select function

Select Pagination

// page 1 of size 10
page, err := db.Animal.Select().Pagination(1, 10)

if err != nil {
	//handler error
}

[!NOTE] Pagination default values for page and size are 1 and 10 respectively.

Back to Contents

Aggregates

Aggregate functions like Count, Sum, Avg are available as table methods.

count, err := db.Animal.Count("id") // (int64, error)

Back to Contents

Functions

SQL functions like ToUpper can be called as table methods.

names, err := db.Animal.ToUpper("name") // ([]string, error)

Functions can be used inside where.

animals, err = db.Animal.Select().
			   Filter(
					goent.Expr("ToUpper(name) LIKE '%CAT%'"),
			   ).All()

if err != nil {
	//handler error
}

[!NOTE] where like expected a second argument always as string.

animals, err = db.Animal.Select().
			   Filter(
					goent.Expr("ToUpper(name) LIKE ?", "%CAT%"),
			   ).All()

if err != nil {
	//handler error
}

[!IMPORTANT] to by pass the compiler type warning, use function.Argument. This way the compiler will check the argument value.

Back to Contents

Insert

On Insert if the primary key value is auto-increment, the new ID will be stored on the object after the insert.

[!NOTE] For auto-increment primary keys, the column is excluded from INSERT and the ID is retrieved using last_insert_rowid(). For primary keys with default values, the value is set before INSERT and the column is included in the statement.

Insert One

a := &Animal{Name: "Cat", Emoji: "🐘"}
err = db.Animal.Insert().One(a)

if err != nil {
	//handler error
}

// new generated id
a.ID

[!TIP] Use goent.InsertContext for specify a context.

Back to Contents

Insert Batch

foods := []*Food{
		{Name: "Meat", Emoji: "🥩"},
		{Name: "Hotdog", Emoji: "🌭"},
		{Name: "Cookie", Emoji: "🍪"},
	}
err = db.Food.Insert().All(true, foods)

if err != nil {
	//handler error
}

[!NOTE] The first parameter of All() is autoIncr. When true, it only applies to tables with auto-increment primary keys. For tables with non-auto-increment primary keys (like UUID or string with default), the primary key column is included in the INSERT statement.

[!TIP] Use goent.InsertContext for specify a context.

Back to Contents

Update

Save

Save is the basic function for updates a single record; only updates the non-zero values.

a := &Animal{ID: 2}
a.Name = "Update Cat"

// update animal of id 2
err = db.Animal.Save().One(a)
changes := map[string]any{
	"name": a.Name,
}
filter := goent.Equals(db.Animal.Field("id"), a.ID)
err = db.Animal.Save().Filter(filter).SetMap(changes).Exec()

if err != nil {
	//handler error
}

[!TIP] Use goent.SaveContext for specify a context.

Back to Contents

Update Set

Update with set uses Set method. This is used for more complex updates, like updating a field with zero/nil values or make a batch update.

a := Animal{ID: 2}

// a.IDHabitat is nil, so is ignored by Save
err = db.Animal.Update().
	  Set(goent.Pair{Key: "habitat_id", Value: a.IDHabitat}).
	  Filter(goent.Equals(db.Animal.Field("id"), a.ID)).Exec()

if err != nil {
	//handler error
}

Check out the Where section for more information about where operations.

[!CAUTION] The where call ensures that only the matched rows will be updated.

[!TIP] Use goent.UpdateContext for specify a context.

Back to Contents

Delete

Delete Batch

Delete all records from Animal

err = db.Animal.Delete().Exec()

if err != nil {
	//handler error
}

Delete one record by primary key

err = db.Animal.Delete().Match(Animal{ID: 2}).Exec()

if err != nil {
	//handler error
}

Delete all matched records

err = db.Animal.Delete().Filter(goent.Like(db.Animal.Field("name"), "%Cat%")).Exec()

if err != nil {
	//handler error
}

Check out the Where section for more information about where operations.

[!CAUTION] The filter call ensures that only the matched rows will be deleted.

[!TIP] Use goent.DeleteContext for specify a context.

Back to Contents

Transaction

Begin Transaction

	err = db.BeginTransaction(func(tx goent.Transaction) error {
		cat := &Animal{
			Name: "Cat",
		}
		if err = db.Animal.Insert().OnTransaction(tx).One(cat); err != nil {
			return err // try a rollback
		}

		dog := &Animal{
			Name: "Dog",
		}
		if err = db.Animal.Insert().OnTransaction(tx).One(dog); err != nil {
			return err // try a rollback
		}
		return nil // try a commit
	})

	if err != nil {
		//begin transaction error...
	}

Nested Transaction

err = db.BeginTransaction(func(tx goent.Transaction) error {
	cat := &Animal{
		Name: "Cat",
	}
	if err = db.Animal.Insert().OnTransaction(tx).One(cat); err != nil {
		return err // try a rollback
	}

	tx.BeginTransaction(func(tx2 goent.Transaction) error {
		meat := &Food{
			Name: "meat",
		}
		if err := db.Food.Insert().OnTransaction(tx2).One(meat); err != nil {
			return err // try a rollback in nested transaction
		}
		return nil // try a commit in nested transaction
	})

	dog := &Animal{
		Name: "Dog",
	}
	if err = db.Animal.Insert().OnTransaction(tx).One(dog); err != nil {
		return err // try a rollback
	}
	return nil // try a commit
})

if err != nil {
	//begin transaction error...
}

You need to call the OnTransaction() function to setup a transaction for Select, Insert, Update and Delete.

[!NOTE] Any select inside a transaction will be "FOR UPDATE".

[!TIP] Use goent.BeginTransactionContext for specify a context

Back to Contents

Manual Transaction

Setup the transaction with the database function db.NewTransaction()

tx, err = db.NewTransaction()
if err != nil {
	// Handle error
}

defer func() {
	if r := recover(); r != nil {
		tx.Rollback()
	}
}()

You need to call the OnTransaction() function to setup a transaction for Select, Insert, Update and Delete.

[!NOTE] Any select inside a transaction will be "FOR UPDATE".

[!TIP] Use goent.NewTransactionContext for specify a context

Back to Contents

Commit and Rollback

To Commit a Transaction just call tx.Commit()

err = tx.Commit()

if err != nil {
	// handler the error
}

To Rollback a Transaction just call tx.Rollback()

err = tx.Rollback()

if err != nil {
	// handler the error
}

Back to Contents

Save Point

sv, err := tx.SavePoint()
if err != nil {
	// handler the error
}
defer func() {
	if r := recover(); r != nil {
		sv.Rollback() // rollback save point
	}
}()

...

sv.Commit() // commit save point

Back to Contents

Code Generation

GoEnt provides a code generator that creates type-safe scan methods for your structs, eliminating reflection overhead and improving performance by up to 27x.

Quick Start

git clone --depth=1 https://github.com/azhai/goent.git
cd goent && go mod tidy && make
./bin/goent-gen ./example/models
# view file ./example/models/goent_gen.go

Install

go install github.com/azhai/goent/cmd/goent-gen@latest

Usage

1. Add //go:generate goent-gen . to your models package:

//go:generate goent-gen .

package models

type User struct {
    ID       int64  `goe:"pk"`
    Name     string `goe:"unique"`
    Email    string `goe:"unique"`
    StatusID int64  `goe:"m2o"`
}

1. Run the generator:

go generate ./models

1. This creates goent_gen.go with:

// Code generated by goent-gen. DO NOT EDIT.

package models

import "github.com/azhai/goent"

// ScanFields returns a slice of pointers to User fields for database scanning.
func (t *User) ScanFields() []any {
    return []any{
        &t.ID,
        &t.Name,
        &t.Email,
        &t.StatusID,
    }
}

// NewUser creates a new User with pre-allocated scan fields.
func NewUser() *User {
    return &User{}
}

// FetchUser creates a FetchFunc for User.
func FetchUser() goent.FetchFunc {
    return func(target any) []any {
        return target.(*User).ScanFields()
    }
}

Performance Comparison

Method	Time	Memory	Allocations
Generated ScanFields	1.68 ns/op	0 B/op	0 allocs/op
Reflection-based	25.04 ns/op	24 B/op	1 allocs/op
Generated FetchFunc	1.68 ns/op	0 B/op	0 allocs/op
Reflection-based	45.29 ns/op	48 B/op	2 allocs/op

Generated code is 15-27x faster than reflection with zero memory allocations.

Using Generated Code

GoEnt automatically uses generated ScanFields() methods when available, providing significant performance improvements without requiring manual changes to your code.

// Automatic usage - no changes needed!
users, err := db.User.Select().All()

// Manual usage with FetchFunc
query := db.User.Select()
for user, err := range query.IterRows(models.FetchUser()) {
	if err != nil {
		// Handle error
	}
	fmt.Printf("%+v\n", user)
}

// Or use ScanFields directly
user := models.NewUser()
rows.Scan(user.ScanFields()...)

Back to Contents

Benchmarks

Insprire from lauro-santana/go-orm-benchmarks.

cd tests/benchmark/run/
go run main.go -operation all --format both

Benchmark on MacMini M4

Operation	Package	N	Avg ns/op	Avg B/op	Avg allocs/op	percent
insert	raw	13765	88704	624	12	=
	goent	17432	76612	3127	55	-13.7%
	goe	13497	101881	2643	31	14.8%
insert-bulk	raw	136	9350581	6054818	39833	=
	goent	100	10389264	6809070	44052	11.1%
	goe	123	9511185	5202196	28013	1.7%
update	raw	13556	89232	696	14	=
	goent	13425	91718	3075	49	2.7%
	goe	13413	103288	2594	27	15.7%
delete	raw	13658	85000	256	8	=
	goent	406078	3435	3301	23	-96.0%
	goe	3054	697383	1066	17	720.4%
select-one	raw	48766	24801	1760	49	=
	goent	42130	27807	2366	43	12.1%
	goe	41710	28711	3508	54	15.7%
select-page	raw	3020	389815	57840	1350	=
	goent	3565	333716	59001	1080	-14.4%
	goe	2089	556273	55399	870	42.7%

Back to Contents