Help us shape the future of Go! Take the 2026 Go Developer Survey

orm

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: MIT Imports: 19 Imported by: 1

Documentation

Overview

Package orm is a generic query builder and model mapper over database/sql. Queries are typed (Query[T] returns T values), always use bound parameters, and validate column names against the model so input can never become SQL (A05). Models are plain structs; persistence functions take an Executor (*database.DB or *database.Tx), so there is no Active Record handle hidden in models.

Index

Constants

This section is empty.

Variables

View Source 
var ErrConflict error = &conflictError{}

ErrConflict is returned (wrapped) when a write violates a unique constraint; it reports HTTP status 409 so handlers answer Conflict.

View Source 
var ErrInvalidCursor = &errs.HTTPError{Status: 400, Message: "Invalid pagination cursor."}

ErrInvalidCursor is returned (400) when a cursor cannot be decoded.

View Source 
var ErrNotFound = &errs.HTTPError{Status: 404, Message: "Record not found."}

ErrNotFound is returned when First/Find match no row. It matches errs.ErrNotFound, so handlers answer 404 by returning it.

Functions

func Columns 

func Columns[T any]() []string

Columns returns the column names of model T in field order.

func Create 

func Create[T any](ctx context.Context, ex database.Executor, model *T) error

Create inserts model, filling the auto-increment id and timestamps.

func Delete 

func Delete[T any](ctx context.Context, ex database.Executor, model *T) error

Delete removes model, or sets deleted_at when the model embeds SoftDeletes.

func ForceDelete 

func ForceDelete[T any](ctx context.Context, ex database.Executor, model *T) error

ForceDelete removes model even when it uses soft deletes.

func Restore 

func Restore[T any](ctx context.Context, ex database.Executor, model *T) error

Restore clears deleted_at on a soft-deleted model.

func TableOf 

func TableOf[T any]() string

TableOf returns the table name of model T.

func Update 

func Update[T any](ctx context.Context, ex database.Executor, model *T) error

Update writes every column of model (except the primary key and created_at) and refreshes updated_at.

func WithClock 

func WithClock(ctx context.Context, now func() time.Time) context.Context

WithClock makes writes in ctx use now for timestamps (tests).

Types

type AfterCreater 

type AfterCreater interface {
	AfterCreate(ctx context.Context) error
}

AfterCreater runs after INSERT.

type AfterUpdater 

type AfterUpdater interface {
	AfterUpdate(ctx context.Context) error
}

AfterUpdater runs after UPDATE.

type BeforeCreater 

type BeforeCreater interface {
	BeforeCreate(ctx context.Context) error
}

BeforeCreater runs before INSERT.

type BeforeDeleter 

type BeforeDeleter interface {
	BeforeDelete(ctx context.Context) error
}

BeforeDeleter runs before DELETE (or soft delete).

type BeforeUpdater 

type BeforeUpdater interface {
	BeforeUpdate(ctx context.Context) error
}

BeforeUpdater runs before UPDATE.

type CursorPage 

type CursorPage[T any] struct {
	Items      []T    `json:"data"`
	PerPage    int    `json:"per_page"`
	NextCursor string `json:"next_cursor,omitempty"`
}

CursorPage is one page of keyset pagination. NextCursor is empty on the last page.

type Direction 

type Direction string

Direction orders results. 

const (
	Asc  Direction = "ASC"
	Desc Direction = "DESC"
)

Sort directions.

type JSON 

type JSON[T any] struct {
	V T
}

JSON stores T as JSON text in one column.

func (JSON[T]) MarshalJSON 

func (j JSON[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes the inner value.

func (*JSON[T]) Scan 

func (j *JSON[T]) Scan(src any) error

Scan implements sql.Scanner.

func (*JSON[T]) UnmarshalJSON 

func (j *JSON[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes into the inner value.

func (JSON[T]) Value 

func (j JSON[T]) Value() (driver.Value, error)

Value implements driver.Valuer.

type Keyer 

type Keyer interface{ PrimaryKey() string }

Keyer overrides the primary key column (default "id").

type Model 

type Model struct {
	ID        int64     `db:"id"         json:"id"`
	CreatedAt time.Time `db:"created_at" json:"created_at"`
	UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
}

Model provides an auto-increment id and timestamps; embed it in models.

type Page 

type Page[T any] struct {
	Items    []T   `json:"data"`
	Total    int64 `json:"total"`
	Page     int   `json:"page"`
	PerPage  int   `json:"per_page"`
	LastPage int   `json:"last_page"`
}

Page is one page of results.

type Query 

type Query[T any] struct {
	// contains filtered or unexported fields
}

Query builds a SELECT for model T. Builders are values: every method returns a modified copy, so a base query can be shared and refined.

func QueryOf 

func QueryOf[T any](ex database.Executor) Query[T]

QueryOf starts a query for model T on ex.

func (Query[T]) Chunk 

func (q Query[T]) Chunk(ctx context.Context, size int, fn func([]T) error) error

Chunk processes rows in batches of size ordered by primary key; fn may stop early by returning an error.

func (Query[T]) Count 

func (q Query[T]) Count(ctx context.Context) (int64, error)

Count returns the number of matching rows.

func (Query[T]) CursorPaginate 

func (q Query[T]) CursorPaginate(
	ctx context.Context,
	cursor string,
	perPage int,
	dir Direction,
) (CursorPage[T], error)

CursorPaginate returns perPage rows after cursor, ordered by the primary key in dir. Unlike Paginate it needs no COUNT and stays fast and stable on large or changing tables. Pass "" for the first page and the returned NextCursor for the following ones. The query must not have its own OrderBy: the keyset order is the primary key.

func (Query[T]) Delete 

func (q Query[T]) Delete(ctx context.Context) (int64, error)

Delete removes every matching row (soft-deleting for SoftDeletes models unless WithTrashed/OnlyTrashed was used, which deletes for real) and returns the count.

func (Query[T]) Each 

func (q Query[T]) Each(ctx context.Context) iter.Seq2[T, error]

Each streams rows without loading them all; breaking out of the loop closes the rows. 

for post, err := range orm.QueryOf[Post](db).Each(ctx) { ... }

func (Query[T]) Exists 

func (q Query[T]) Exists(ctx context.Context) (bool, error)

Exists reports whether any row matches.

func (Query[T]) Find 

func (q Query[T]) Find(ctx context.Context, id any) (T, error)

Find returns the row with the given primary key or ErrNotFound.

func (Query[T]) First 

func (q Query[T]) First(ctx context.Context) (T, error)

First returns the first matching row or ErrNotFound.

func (Query[T]) Get 

func (q Query[T]) Get(ctx context.Context) ([]T, error)

Get returns every matching row.

func (Query[T]) Latest 

func (q Query[T]) Latest() Query[T]

Latest orders by created_at (or the primary key) descending.

func (Query[T]) Limit 

func (q Query[T]) Limit(n int) Query[T]

Limit sets the maximum number of rows.

func (Query[T]) Offset 

func (q Query[T]) Offset(n int) Query[T]

Offset skips n rows.

func (Query[T]) OnlyTrashed 

func (q Query[T]) OnlyTrashed() Query[T]

OnlyTrashed returns only soft-deleted rows.

func (Query[T]) OrWhere 

func (q Query[T]) OrWhere(col string, args ...any) Query[T]

OrWhere is Where joined with OR.

func (Query[T]) OrderBy 

func (q Query[T]) OrderBy(colName string, dir Direction) Query[T]

OrderBy adds an ORDER BY column (validated) and direction.

func (Query[T]) Paginate 

func (q Query[T]) Paginate(ctx context.Context, page, perPage int) (Page[T], error)

Paginate returns page (1-based) with perPage items and the total count.

func (Query[T]) Pluck 

func (q Query[T]) Pluck[V any](ctx context.Context, colName string) ([]V, error)

Pluck returns one column of every matching row as []V.

func (Query[T]) SQL 

func (q Query[T]) SQL() (string, []any, error)

SQL returns the SELECT statement and its arguments (debugging, tests).

func (Query[T]) Scope 

func (q Query[T]) Scope(fns ...func(Query[T]) Query[T]) Query[T]

Scope applies reusable query functions: q.Scope(Published, ByAuthor(id)).

func (Query[T]) Select 

func (q Query[T]) Select(cols ...string) Query[T]

Select limits the selected columns (validated against the model).

func (Query[T]) Update 

func (q Query[T]) Update(ctx context.Context, set Set) (int64, error)

Update sets columns on every matching row and returns the count. updated_at is refreshed unless set explicitly.

func (Query[T]) Where 

func (q Query[T]) Where(col string, args ...any) Query[T]

Where adds "col = value", or "col op value" when three arguments are given: Where("age", ">=", 18). Operators are allow-listed.

func (Query[T]) WhereBetween 

func (q Query[T]) WhereBetween(colName string, low, high any) Query[T]

WhereBetween adds "col BETWEEN low AND high".

func (Query[T]) WhereGroup 

func (q Query[T]) WhereGroup(fn func(g Query[T]) Query[T]) Query[T]

WhereGroup adds a parenthesised group built by fn.

func (Query[T]) WhereIn 

func (q Query[T]) WhereIn(col string, values ...any) Query[T]

WhereIn adds "col IN (...)". An empty list matches nothing.

func (Query[T]) WhereNotIn 

func (q Query[T]) WhereNotIn(col string, values ...any) Query[T]

WhereNotIn adds "col NOT IN (...)". An empty list matches everything.

func (Query[T]) WhereNotNull 

func (q Query[T]) WhereNotNull(col string) Query[T]

WhereNotNull adds "col IS NOT NULL".

func (Query[T]) WhereNull 

func (q Query[T]) WhereNull(col string) Query[T]

WhereNull adds "col IS NULL".

func (Query[T]) WhereRaw 

func (q Query[T]) WhereRaw(sqlFrag string, args ...any) Query[T]

WhereRaw adds a raw condition. It must use "?" placeholders for every value; never concatenate input into sql.

func (Query[T]) WithTrashed 

func (q Query[T]) WithTrashed() Query[T]

WithTrashed includes soft-deleted rows.

type Set 

type Set map[string]any

Set is a column → value map for bulk updates.

type SoftDeletes 

type SoftDeletes struct {
	DeletedAt sql.Null[time.Time] `db:"deleted_at" json:"deleted_at"`
}

SoftDeletes makes Delete set deleted_at instead of removing rows; queries exclude deleted rows unless WithTrashed or OnlyTrashed is used.

type Tabler 

type Tabler interface{ Table() string }

Tabler overrides the table name (default: snake_case plural of the type).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.