Thing ORM

Thing is a Go ORM focused on fast CRUD, ID-based loading, list queries, and built-in cache invalidation. It uses generics for type-safe model access and supports SQLite, MySQL, and PostgreSQL.

For detailed usage, model tags, relationships, cache-friendly query patterns, and raw SQL guidance, see the usage guides:

• English
• 中文

Install

go get github.com/burugo/thing

Quick Start

package main

import (
	"log"

	"github.com/burugo/thing"
	"github.com/burugo/thing/drivers/db/sqlite"
)

type User struct {
	thing.BaseModel
	Name  string `db:"name,index"`
	Email string `db:"email,unique"`
}

func main() {
	db, err := sqlite.NewSQLiteAdapter("app.db")
	if err != nil {
		log.Fatal(err)
	}

	if err := thing.Configure(db, nil); err != nil { // nil uses the built-in memory cache
		log.Fatal(err)
	}

	if err := thing.AutoMigrate(&User{}); err != nil {
		log.Fatal(err)
	}

	users, err := thing.Use[*User]()
	if err != nil {
		log.Fatal(err)
	}

	alice := &User{Name: "Alice", Email: "alice@example.com"}
	if err := users.Save(alice); err != nil {
		log.Fatal(err)
	}

	cachedUser, err := users.ByID(alice.ID)
	if err != nil {
		log.Fatal(err)
	}
	_ = cachedUser

	activeUsers, err := users.
		Where("name LIKE ?", "A%").
		Order("id DESC").
		Fetch(0, 20)
	if err != nil {
		log.Fatal(err)
	}
	_ = activeUsers
}

What Thing Optimizes For

• Save, SaveMany, ByID, ByIDs, Delete, DeleteMany, and SoftDelete
• Paginated list queries through Query(...).Fetch(offset, limit)
• Count caching through Query(...).Count()
• Model cache reuse when list results are hydrated
• Cache invalidation for common WHERE and ORDER BY patterns
• Relationship preloading without hand-written joins

Thing intentionally keeps the ORM surface small. For reporting queries, database-specific SQL, or one-off joins, use the raw DBAdapter / *sql.DB accessors and treat those reads as outside the ORM cache path.

Cache-Friendly Pattern

Prefer this shape:

ids := []int64{1, 2, 3}
usersByID, err := users.ByIDs(ids)

or:

page, err := users.Where("id IN (?)", ids).Fetch(0, len(ids))

Avoid replacing repeated application reads with SELECT * ... JOIN ... when the same data can be loaded as an ID list and hydrated through ByID / ByIDs. That is the path where Thing can reuse model cache and maintain query cache invalidation.

More examples are in Cache Utilization / 提高缓存利用率.

Documentation

• Usage Guide (English)
• 使用指南（中文）
• API Reference
• Partial Indexes Spec

Development

Run the test suite:

go test ./...

License

MIT