ormlite

README

ormlite

Lightweight package implementing some ORM-like features and helpers for sqlite databases.

Model

type Model interface {
    Table() string
}

This package operates models which are described by Model interface. We call any entry a model if it's a struct and has a table where data is stored.

CRUD

This package provides a bunch of functions to allow you create, read, update and delete data.

QueryStruct

Loads data from table and scans it into provided struct. If query was too broad to load more than one rows, the latest of them will be scanned. Also this function supports loading relations which will be described below.

type SimpleStruct struct {
  IntField int `ormlite:"col=rowid,primary"`
  Text string
  UnusedField bool `ormlite:"-"
}

var s SimpleStruct
err := QueryStruct(db, "", nil, &s)

Let's describe some tags used in example struct:

• col - let you specify custom column name to be scanned to the field
• primary - indicates model primary key, it's basically used when saving model
• - - hide field for package so it won't be affected at any kind

QuerySlice

This is very similar to QueryStruct except that it loads multiple rows in a slice.

Upsert

This function is used to save or update existing model, if model has primary field and it's value is zero - this model will be inserted to the model's table. Otherwise model's row will be updated according it's current values. This function also supports relations except hasMany.

err := Upsert(db, &s)

Delete

This function... yea, it deletes model from database using it's primary key value. If model does not have primary key or it has zero value an error will ne returned. Since sometimes it's useful to know that delete operation is really took place in database, function will check number of affected rows and return a special ErrNoRowsAffected if it's not positive.

Options

type Options struct {
   // Add where clause to query
   Where         Where    
   Limit         int      
   Offset        int      
   OrderBy       *OrderBy 
   // Load relations to specified depth,
   // if depth is 0 don't load any relations
   RelationDepth int      
}

For most queries is't enough to use DefaultOptions() which has relation depth equal to 1.

If you already have variable containing Options, you can extend them with additional settings with following functions:

• WithLimit
• WithOffset
• WithOrder
• WithWhere

For example:

opts := ormlite.WithWhere(ormlite.DefaultOptions(), ormlite.Where{"id": 1})

Relations

QueryStruct, QuerySlice and Upsert support loading relations between models, the supported relation types are:

• Has One
• Has Many
• Many To Many

Since you can control depth of loaded relations, there is no need to be afraid of cycle loading. But there are several tags to configure relations.

Has One

type Model struct {
   Related ormlite.Model `ormlite:"has_one,col=related_model_id"`
}

has_one indicates that this field represents has one relations type to other model.

col is an optional parameter to specify custom column name of foreign id of related model.

Has Many

type Model struct {
   Related []ormlite.Model `ormlite:"has_many"`
}

has_many is the only parameter to indicate has many relation, however there is a requirement that related model must have primary field.

Many To Many

type Model struct {
  Related []ormlite.Model `ormlite:"many_to_many,table=mapping_table,field=model_id"`
}

many_to_many indicates that field represents many to many relation.

table should contain mapping table name to retrieve relation information.

field should specify column in mapping table that has foreign key of original model

Also there is a requirement to related model primary key field to contain ref setting that specifies column name of it's foreign key in mapping table.

Examples

See tests.

Documentation

Index

• Variables
• func Delete(db *sql.DB, m Model) error
• func QuerySlice(db *sql.DB, opts *Options, out interface{}) error
• func QuerySliceContext(ctx context.Context, db *sql.DB, opts *Options, out interface{}) error
• func QueryStruct(db *sql.DB, opts *Options, out Model) error
• func QueryStructContext(ctx context.Context, db *sql.DB, opts *Options, out Model) error
• func Upsert(db *sql.DB, m Model) error
• func UpsertContext(ctx context.Context, db *sql.DB, m Model) error
• type Model
• type Options
  • func DefaultOptions() *Options
  • func WithLimit(options *Options, limit int) *Options
  • func WithOffset(options *Options, offset int) *Options
  • func WithOrder(options *Options, by OrderBy) *Options
  • func WithWhere(options *Options, where Where) *Options
• type OrderBy
• type Where

Variables

var ErrNoRowsAffected = errors.New("no rows affected")

Functions

func Delete

func Delete(db *sql.DB, m Model) error

Delete removes model object from database by it's primary key

func QuerySlice

func QuerySlice(db *sql.DB, opts *Options, out interface{}) error

QuerySlice scans rows into the slice of structs

func QuerySliceContext

func QuerySliceContext(ctx context.Context, db *sql.DB, opts *Options, out interface{}) error

QuerySliceContext scans rows into the slice of structs with given context

func QueryStruct

func QueryStruct(db *sql.DB, opts *Options, out Model) error

QueryStruct looks up for rows in given table and scans it to provided struct or slice of structs

func QueryStructContext

func QueryStructContext(ctx context.Context, db *sql.DB, opts *Options, out Model) error

QueryStruct looks up for rows in given table and scans it to provided struct or slice of structs

func Upsert

func Upsert(db *sql.DB, m Model) error

func UpsertContext

func UpsertContext(ctx context.Context, db *sql.DB, m Model) error

Upsert inserts object into table or updates it's values if it's not exist or updates it

Types

type Model

type Model interface {
	Table() string
}

Model is an interface that represents model of database

type Options

type Options struct {
	Where         Where    `json:"where"`
	Limit         int      `json:"limit"`
	Offset        int      `json:"offset"`
	OrderBy       *OrderBy `json:"order_by"`
	RelationDepth int      `json:"relation_depth"`
}

Options represents query options

func DefaultOptions

func DefaultOptions() *Options

DefaultOptions returns default options for query

func WithLimit

func WithLimit(options *Options, limit int) *Options

WithLimit modifies existing options by adding limit parameter to them

func WithOffset

func WithOffset(options *Options, offset int) *Options

WithOffset modifies existing options by adding offset parameter to them. If options does not have positive limit parameter the offset will remain unchanged to avoid sql query correctness.

func WithOrder

func WithOrder(options *Options, by OrderBy) *Options

WithOrder modifies existing options by adding ordering options to them

func WithWhere

func WithWhere(options *Options, where Where) *Options

WithWhere modifies existing options by adding where clause to them

type OrderBy

type OrderBy struct {
	Field string `json:"field"`
	Order string `json:"order"`
}

OrderBy describes ordering rule

type Where

type Where map[string]interface{}