oca

README

OCA

Lightweight generic ORM for Go, simple CRUD, extensible design

Documentation

Index

• type FieldMeta
• type FilterOptions
  • func Limit(limit int) FilterOptions
  • func Offset(offset int) FilterOptions
  • func OrderBy(order string) FilterOptions
  • func Where(cond query.Condition) FilterOptions
• type FindFilter
• type GenericStore
  • func NewRepository[T any](db *sql.DB) GenericStore[T]
• type Repository
  • func (r *Repository[T]) FindOne(ctx context.Context, opts ...FilterOptions) (*T, error)
  • func (r *Repository[T]) Finds(ctx context.Context, opts ...FilterOptions) ([]T, error)
  • func (r *Repository[T]) Insert(ctx context.Context, entity *T) error
• type Tabler

Types

type FieldMeta

type FieldMeta struct {
	Name      string            // Go struct field name
	Column    string            // DB column name from `db` tag
	Index     int               // field index in struct
	IsPrimary bool              // true if marked as primary key
	IsAuto    bool              // true if marked as auto increment
	Schema    map[string]string // parsed key:value pairs from `schema` tag
}

FieldMeta holds metadata about a struct field for ORM mapping.

type FilterOptions

type FilterOptions func(*FindFilter)

FilterOptions modifies a FindFilter.

func Limit

func Limit(limit int) FilterOptions

Limit sets the LIMIT clause.

func Offset

func Offset(offset int) FilterOptions

Offset sets the OFFSET clause.

func OrderBy

func OrderBy(order string) FilterOptions

OrderBy sets the ORDER BY clause.

func Where

func Where(cond query.Condition) FilterOptions

Where adds a WHERE condition using the query DSL.

Example:

Where(query.C("age").Gt(18))

type FindFilter

type FindFilter struct {
	Where  []query.Condition // WHERE conditions (multiple)
	Order  string            // ORDER BY clause
	Limit  int               // LIMIT
	Offset int               // OFFSET
}

FindFilter defines filters for the Find method.

type GenericStore

type GenericStore[T any] interface {
	// Insert inserts a new record into the database and sets auto-increment fields
	// or other schema defaults if applicable. It respects tags like `db:"...,auto"`
	// and `schema:"default:now()"`.
	//
	// Example:
	//
	//	type User struct {
	//	    ID        int64  `db:"id,pk,auto"`
	//	    Name      string `db:"name"`
	//	    CreatedAt time.Time `db:"created_at" schema:"default:now()"`
	//	}
	//
	//	repo := NewRepository[User](db)
	//	u := &User{Name: "Alice"}
	//	err := repo.Insert(ctx, u)
	//
	// After insertion, u.ID and u.CreatedAt will be automatically populated if applicable.
	Insert(ctx context.Context, entity *T) error

	// Finds retrieves multiple records from the database matching the provided filters.
	// It automatically maps database rows to struct fields based on the `db` tags.
	//
	// Example:
	//
	//	todos, err := repo.Finds(ctx, oca.Where(query.C("name").Eq("Hanida Alya")))
	Finds(ctx context.Context, filter ...FilterOptions) ([]T, error)

	// FindOne retrieves a single record from the database matching the provided filters.
	// Returns sql.ErrNoRows if no record is found.
	//
	// Example:
	//
	//	todo, err := repo.FindOne(ctx, oca.Where(query.C("id").Eq(28)))
	FindOne(ctx context.Context, opts ...FilterOptions) (*T, error)
}

GenericStore defines a generic interface for basic CRUD operations on any model T. This allows repositories to be abstracted and easily mocked for testing.

T can be any struct that represents a database model, annotated with `db` tags for mapping to database columns.

func NewRepository

func NewRepository[T any](db *sql.DB) GenericStore[T]

NewRepository returns a new generic repository.

type Repository

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

Repository provides basic CRUD operations for any model T. If T implements Tabler, its TableName() will be used. Otherwise, the struct name is used as the table name (lowercased + "s").

func (*Repository[T]) FindOne

func (r *Repository[T]) FindOne(ctx context.Context, opts ...FilterOptions) (*T, error)

FindOne retrieves a single record from the database based on the filter. Returns sql.ErrNoRows if nothing is found.

func (*Repository[T]) Finds

func (r *Repository[T]) Finds(ctx context.Context, opts ...FilterOptions) ([]T, error)

Finds retrieves multiple records from the database matching the filter. It automatically maps database rows to struct fields based on the `db` tags. Finds retrieves records from the database based on provided filter options. It returns a slice of T or an error.

func (*Repository[T]) Insert

func (r *Repository[T]) Insert(ctx context.Context, entity *T) error

Insert inserts the entity into the database. It automatically handles auto-increment fields and schema defaults (e.g., default:now()). Multiple auto fields are supported and populated after insertion.

type Tabler

type Tabler interface {
	// TableName returns the name of the database table.
	TableName() string
}

Tabler is implemented by any struct that wants to define its own database mapping. It provides the table name used in queries.

Example:

func (User) TableName() string   { return "users" }