ormlite

README

ormlite

Simple package that contains some ORM like functionality for database/sql especially for sqlite3

Model

type Model interface {
    Table() string
}

This package mainly operates with a Model interface. Though there is an ability to load data specifing custom table, Model is used to process relations.

CRUD

This package provides a bunch of funcs 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 basicly 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. Also QuerySlice for now does not support loading relations due cyclic dependency.

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 accordint 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 all it's fields except relational as identification condition. So if you loaded any model and changed it and then will call Delete nothing will hapen.

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

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 contains 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.

Documentation

Index

• func Delete(db *sql.DB, m Model) error
• func QuerySlice(db *sql.DB, opts *Options, out interface{}) error
• func QueryStruct(db *sql.DB, opts *Options, out Model) error
• func Upsert(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

Functions

func Delete

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

Delete removes model object from database, if object was changed before saving it won't be deleted.

func QuerySlice

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

QuerySlice scans rows into the slice of structs

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 Upsert

func Upsert(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{}