gen

GORM Gen

Friendly & Safer GORM powered by Code Generation.

Overview

• Generate idiomatic, reusable DAO APIs from database schema and/or interface-based SQL templates
• Type-safe query DSL (fields, conditions, assignments) with strong static typing (including generics mode)
• Database-to-struct follows GORM conventions (tags, nullable/default/unsigned/index/type, etc.)
• Built on top of GORM: use the same plugins, dialectors, and ecosystem you already have

Documentation

• Gen Guides (official site): https://gorm.io/gen/index.html
• GORM Guides: https://gorm.io/docs

Quick Start

Install as a library:

go get gorm.io/gen@latest

1) Generate code

Create a generator entry (recommended: cmd/gen/main.go):

package main

import (
	"gorm.io/driver/mysql"
	"gorm.io/gen"
	"gorm.io/gorm"
)

func main() {
	db, err := gorm.Open(mysql.Open("dsn"), &gorm.Config{})
	if err != nil {
		panic(err)
	}

	g := gen.NewGenerator(gen.Config{
		OutPath: "internal/dal/query",
		Mode:    gen.WithDefaultQuery | gen.WithQueryInterface, // enable query.SetDefault(db)
	})

	g.UseDB(db)
	g.ApplyBasic(g.GenerateAllTable()...)
	g.Execute()
}

Run generation:

go run ./cmd/gen

2) Use generated code

If you enabled WithDefaultQuery, initialize once at startup:

package main

import (
	"context"

	"gorm.io/driver/mysql"
	"gorm.io/gorm"

	"your/module/internal/dal/query"
)

func main() {
	db, err := gorm.Open(mysql.Open("dsn"), &gorm.Config{})
	if err != nil {
		panic(err)
	}

	query.SetDefault(db)

	u := query.User
	_, _ = u.WithContext(context.Background()).
		Where(u.Age.Gt(18)).
		Find()
}

query.SetDefault(db) only needs to run once (e.g. during service startup). After that, use query.<Table> directly.

If you don’t want a global default, skip WithDefaultQuery and use:

q := query.Use(db)
_, _ = q.User.WithContext(ctx).Where(q.User.Age.Gt(18)).Find()

More runnable examples: examples

Common Setups

Gen has one generator entry point (gen.NewGenerator(gen.Config{...})). The main knobs you typically use are:

• What to generate: DB schema → models/query; plus optional interface-SQL methods
• How the query API looks: Config.Mode flags (WithDefaultQuery, WithoutContext, WithQueryInterface, WithGeneric)
• Code style: Config.UseAny emits any instead of interface{} in generated code (opt-in; target module needs Go 1.18+; also rewrites the literal text interface{} in comments and string literals)

Setup A: DB schema → model + query (recommended baseline)

g := gen.NewGenerator(gen.Config{
	OutPath: "internal/dal/query",
	Mode:    gen.WithDefaultQuery | gen.WithQueryInterface,

	FieldNullable:     true,
	FieldCoverable:    true,
	FieldWithIndexTag: true,
})
g.UseDB(db)
g.ApplyBasic(g.GenerateAllTable()...)
g.Execute()

Setup B: Interface SQL templates → reusable typed methods

Define an interface with SQL comments/templates:

package dal

import "gorm.io/gen"

type UserMethods interface {
	// FindByID
	//
	// SELECT * FROM users WHERE id=@id
	FindByID(id int) gen.T

	// FindByOptionalName
	//
	// SELECT * FROM users
	// {{where}}
	// {{if name != ""}}
	// name=@name
	// {{end}}
	// {{end}}
	FindByOptionalName(name string) []gen.T
}

Bind the interface to a generated model/table:

g.ApplyInterface(func(m UserMethods) {}, g.GenerateModel("users"))

Template syntax reference exists in the test corpus: method.go.

Setup C: Generics query API

Generics is not a separate “workflow”; it changes the generated query API surface for stronger typing.

g := gen.NewGenerator(gen.Config{
	OutPath: "internal/dal/query",
	Mode:    gen.WithDefaultQuery | gen.WithGeneric,
})

Recommended Project Layout

Keep code generation isolated and reproducible (works well with go:generate and CI).

your-repo/
  internal/
    dal/
      model/        # generated model structs (optional)
      query/        # generated query (+ DIY methods)
  cmd/
    gen/
      main.go       # generator entry (checked in)

CLI Tool

If you prefer a CLI workflow, use GenTool:

• GenTool README
• GenTool README (ZH-CN)

Maintainers

@riverchu @iDer @qqxhb @dino-ma

@jinzhu

Contributing

You can help to deliver a better GORM/Gen, check out things you can do

License

Released under the MIT License