grove

Grove: polyglot Go ORM with native query syntax

Grove is an open-source Go ORM for PostgreSQL, MySQL, SQLite, Turso, MongoDB, ClickHouse and Elasticsearch. Each driver builds queries in its own database's syntax, so you write $1 and DISTINCT ON against Postgres and BSON filters against MongoDB, through one model layer. You also get Go-code database migrations with dependency ordering, query hooks for multi-tenancy and audit logging, a key-value store over Redis, Badger, BoltDB, DynamoDB and Memcached, and CRDT sync for offline-first apps. It runs standalone or as a Forge extension.

Documentation · Quick start · Drivers · Migrations · Hooks · KV store · CRDT sync · Forge · FAQ

Quick start

You need Go 1.25 or later. This example uses the SQLite driver, which is pure Go, so you don't need a database server or cgo to try it:

mkdir hello-grove
cd hello-grove
go mod init example.com/hello-grove
go get github.com/xraph/grove@latest
go get github.com/xraph/grove/drivers/sqlitedriver@latest

Save this as main.go:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/xraph/grove"
	"github.com/xraph/grove/drivers/sqlitedriver"
)

type User struct {
	grove.BaseModel `grove:"table:users,alias:u"`

	ID    int64  `grove:"id,pk,autoincrement"`
	Name  string `grove:"name,notnull"`
	Email string `grove:"email,notnull,unique"`
	Role  string `grove:"role,notnull"`
}

func main() {
	ctx := context.Background()

	sqlite := sqlitedriver.New()
	if err := sqlite.Open(ctx, "file:hello.db"); err != nil {
		log.Fatal(err)
	}

	db, err := grove.Open(sqlite)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	q := sqlitedriver.Unwrap(db)

	if _, err := q.NewCreateTable((*User)(nil)).IfNotExists().Exec(ctx); err != nil {
		log.Fatal(err)
	}

	alice := &User{Name: "Alice", Email: "alice@example.com", Role: "admin"}
	if _, err := q.NewInsert(alice).OnConflict("DO NOTHING").Exec(ctx); err != nil {
		log.Fatal(err)
	}

	var admins []User
	err = q.NewSelect(&admins).
		Where("role = ?", "admin").
		OrderExpr("id ASC").
		Limit(10).
		Scan(ctx)
	if err != nil {
		log.Fatal(err)
	}

	for _, u := range admins {
		fmt.Printf("%d %s <%s>\n", u.ID, u.Name, u.Email)
	}
}

Run it:

go run .
# 1 Alice <alice@example.com>

Run it twice and you still get one row, because the second insert hits the unique email and ON CONFLICT DO NOTHING skips it. The data lives in hello.db next to your code.

That's the whole pattern. You open a driver, hand it to grove.Open, and call Unwrap on the *grove.DB to get that driver's typed query builder. Swap sqlitedriver for pgdriver and you get pgdriver.Unwrap(db).NewSelect(...), with Postgres-only methods like DistinctOn, ForUpdate and ForShare on it.

Why Grove?

Most Go ORMs give you one query API and translate it for every database. Grove gives each database its own builder, so the SQL (or BSON, or Elasticsearch DSL) you'd write by hand in a console is what you write in Go, and when a database has a feature the others lack, its builder has a method for it and the other builders don't have one.

The architecture guide explains how the root package, the driver interfaces and the driver modules fit together.

Database drivers

Each driver is its own Go module. You only download the client libraries for the databases you use, so a service that talks to SQLite never pulls in the MongoDB or ClickHouse drivers, and your go.sum stays short.

Importing a driver package registers it under the names above. That's what lets you open a database by name, from config, without naming the package in your code:

import _ "github.com/xraph/grove/drivers/pgdriver"

drv, err := grove.OpenDriver(ctx, "postgres", "postgres://localhost:5432/app?sslmode=disable")
db, err := grove.Open(drv)

The SQL drivers also accept ? in Where, and pgdriver rewrites each one to the next $n for you.

Migrations

Migrations are Go functions. You put them in a named group, and a group can depend on other groups, which is how a library ships its own tables and still runs after your core schema:

var Migrations = migrate.NewGroup("billing", migrate.DependsOn("core"))

func init() {
	Migrations.MustRegister(&migrate.Migration{
		Name:    "create_invoices",
		Version: "20260101000000",
		Up: func(ctx context.Context, exec migrate.Executor) error {
			_, err := exec.Exec(ctx, `CREATE TABLE invoices (id BIGSERIAL PRIMARY KEY, total BIGINT NOT NULL)`)
			return err
		},
		Down: func(ctx context.Context, exec migrate.Executor) error {
			_, err := exec.Exec(ctx, `DROP TABLE invoices`)
			return err
		},
	})
}

migrate.NewOrchestrator(executor, groups...) plans every group in dependency order and gives you Migrate, Rollback and Status. Each SQL driver and MongoDB has a <name>migrate package (pgmigrate, sqlitemigrate, mongomigrate and so on) with the executor, and importing it lets migrate.NewExecutorFor(drv) find the right one. Applied versions go in a tracking table, and a lock table stops two instances from migrating at once. The migrations guide and multi-module migrations cover the rest.

Query hooks

A hook is any type that implements one or more of hook.PreQueryHook, hook.PostQueryHook, hook.PreMutationHook, hook.PostMutationHook or hook.StreamRowHook. You add it to the database with a scope, and it runs on every matching query the drivers build.

This one scopes reads on the orders table to the tenant in the request context, and refuses the query when there isn't one:

type tenantKey struct{}

type TenantScope struct{}

func (TenantScope) BeforeQuery(ctx context.Context, qc *hook.QueryContext) (*hook.HookResult, error) {
	tenant, _ := ctx.Value(tenantKey{}).(string)
	if tenant == "" {
		return &hook.HookResult{Decision: hook.Deny, Error: grove.ErrHookDenied}, nil
	}

	return &hook.HookResult{
		Decision: hook.Modify,
		Filters:  []hook.ExtraFilter{{Clause: "tenant_id = ?", Args: []any{tenant}}},
	}, nil
}

db.Hooks().AddHook(TenantScope{}, hook.Scope{Tables: []string{"orders"}})

Scopes filter by table and by operation (hook.OpSelect, hook.OpInsert, hook.OpUpdate, hook.OpDelete and the bulk variants), and a lower Priority runs first. The audit package is a hook too, for audit logs. See hooks and tenant isolation.

Key-value store

github.com/xraph/grove/kv is a separate module with its own drivers. It gives you Get, Set, MGet, MSet, Delete, Exists, TTL, Expire and Scan over any of them, with values encoded by a codec (JSON by default):

rdb := redisdriver.New()
if err := rdb.Open(ctx, "redis://localhost:6379/0"); err != nil {
	log.Fatal(err)
}

store, err := kv.Open(rdb)
if err != nil {
	log.Fatal(err)
}
defer store.Close()

err = store.Set(ctx, "session:abc", Session{UserID: "u_1"}, kv.WithTTL(30*time.Minute))

Start with the KV overview.

CRDT sync

Tag a field with a CRDT type and Grove records its merge state in a shadow table next to yours. Your table's schema doesn't change. When two devices edit the same record offline and sync later, the field's type decides the result: the latest write wins for lww, increments from both sides add up for counter, and an element added on one side and removed on the other stays in a set.

type Document struct {
	grove.BaseModel `grove:"table:documents"`

	ID        string   `grove:"id,pk"`
	Title     string   `grove:"title,crdt:lww"`
	ViewCount int64    `grove:"view_count,crdt:counter"`
	Tags      []string `grove:"tags,type:jsonb,crdt:set"`
}

crdt.New(crdt.WithNodeID("node-1")) creates the plugin, which you add as a hook on the CRDT tables. Nodes exchange changes through crdt.NewSyncer over HTTP pull and push, with an SSE stream for live updates, and every change carries a hybrid logical clock so nodes agree on order without coordinating. Beyond LWW registers, counters and sets, there are list, document and collaborative text types, plus presence and rooms.

Your frontend talks to the same sync endpoints through @grove-js/crdt (TypeScript, with React hooks) or grove_crdt (Dart and Flutter). The CRDT guide walks through a full setup.

Use it with Forge

The github.com/xraph/grove/extension module plugs Grove into a Forge app. It opens the database during Register, provides *grove.DB through Forge's DI container, adds your hooks and migration groups, reports health, and closes the connection on shutdown. It needs Go 1.26, the same as Forge.

go get github.com/xraph/grove/extension@latest
go get github.com/xraph/grove/drivers/pgdriver@latest

import (
	"github.com/xraph/forge"
	"github.com/xraph/grove"
	"github.com/xraph/grove/drivers/pgdriver"
	_ "github.com/xraph/grove/drivers/pgdriver/pgmigrate"
	groveext "github.com/xraph/grove/extension"
)

app := forge.NewApp(forge.AppConfig{
	Name:        "accounts",
	HTTPAddress: ":8080",
	Extensions: []forge.Extension{
		groveext.New(
			groveext.WithDSN("postgres", "postgres://localhost:5432/accounts?sslmode=disable"),
			groveext.WithMigrations(Migrations),
			groveext.WithHook(TenantScope{}, hook.Scope{Tables: []string{"orders"}}),
		),
	},
})

err := app.Router().GET("/users/count", func(ctx forge.Context) error {
	db, err := forge.Inject[*grove.DB](app.Container())
	if err != nil {
		return err
	}

	n, err := pgdriver.Unwrap(db).NewSelect((*User)(nil)).Count(ctx.Context())
	if err != nil {
		return err
	}

	return ctx.JSON(http.StatusOK, map[string]int64{"users": n})
})

The extension doesn't import any driver itself. You import the driver you want (blank, or by name as above), plus its <name>migrate package if you have migrations. Otherwise WithDSN fails with an unknown-driver error, or migrations fail with no executor.

You get tracing and metrics for free. Every query runs as a client span (SELECT users, COMMIT) under the request or job that issued it, and /_/metrics gets db_client_operation_duration_seconds, labelled by system, operation, table and error type. Outside Forge, pass grove.WithMetrics(m) to grove.Open. The spans go to whatever OpenTelemetry tracer provider is installed. Grove never records the query text or a bound value. See tracing and metrics.

The extension implements forge.MigratableExtension, but a plain app.Run() doesn't apply migrations. Run your app through Forge's cli.NewAppRunner to get migrate up, migrate down and migrate status commands, and call AutoMigrate() on the runner if you want pending migrations applied before the server starts.

Configuration

The extension reads extensions.grove from your Forge config, then falls back to a top-level grove key. YAML wins for the driver and DSN, and options you pass in code fill whatever YAML leaves empty.

extensions:
  grove:
    driver: postgres
    dsn: postgres://localhost:5432/accounts?sslmode=disable
    lock_timeout: 30s

WithCRDT(plugin, scope), WithCRDTEntity, WithSyncer and WithDriverFactory are code-only. With WithCRDT, the extension mounts POST /sync/pull, POST /sync/push, GET /sync/stream (SSE) and /sync/ws (WebSocket) under the base path, plus presence, history and room routes. The Forge extension guide and configuration reference go deeper.

Benchmarks

All benchmarks run against in-memory SQLite, comparing Grove with raw database/sql, bun and GORM. You don't need any external services. Run them yourself with make bench, and make bench-update rewrites the tables below and the benchmarks page.

Documentation

The exported Go API is on pkg.go.dev. The docs source lives in docs/ in this repository.

FAQ

Can I use Grove without Forge?

Yes. The root module depends only on github.com/xraph/go-utils, and none of the driver modules import Forge. You need Forge only if you use extension or kv/extension.

How do I migrate from bun to Grove?

Keep your models as they are. Grove reads bun:"..." tags when a field has no grove:"..." tag, so you can switch the query code first and rename tags later, one model at a time. The bun migration guide has the details.

Does Grove work with MongoDB and Elasticsearch, or only SQL?

Both. mongodriver builds BSON filters, find queries and aggregation pipelines, and esdriver builds search, aggregation and bulk requests. They share the model layer and hooks with the SQL drivers.

How do I add multi-tenancy to a Go ORM?

Write a pre-query hook that reads the tenant from the context and returns an extra WHERE filter, as in Query hooks, and scope it to your tenant tables. A hook that returns hook.Deny blocks the query outright.

Does Grove generate IDs for my models?

No. You declare the key in a tag, such as grove:"id,pk,autoincrement", and pick the Go type yourself.

Contributing

Issues and focused pull requests are welcome on GitHub. Every driver and the KV layer are separate Go modules, so run commands from the module you changed, with GOWORK=off:

git clone https://github.com/xraph/grove.git
cd grove
GOWORK=off go test -race -count=1 ./...
(cd drivers/pgdriver && GOWORK=off go test -race -count=1 ./...)
make test-all
golangci-lint run ./...
goimports -l -local github.com/xraph/grove .

The Postgres and Redis container tests need a running Docker daemon and skip without one, so check the -v output for SKIP lines. Skip make build, make run and make dev: they point at a cmd/grove that doesn't exist. AGENTS.md has the module list, lint rules and the release workflow. Commits follow Conventional Commits.

License

Grove is available under the MIT License.

Built by Rex Raphael and contributors, as part of the Forge forgery stack.