requests

README

Requests

A structure and its methods, to simplify SQL requests.

Installation

Simply use the go get command to install the package to your $GOPATH:

go get github.com/mlantonn/requests

Usage

Here is what a basic usage looks like:

type Users []User
type User {
    ID    uint64 `db:"id"`
    Login string `db:"login"`
}

func (users Users) Insert(handler requests.Handler) error {
    rq := requests.FromHandler(handler)
    rq.Table = "user"
    return rq.InsertStructs(users)
}

The Request structure

Request is a structure which contains:

• The Handler (can be *sql.DB or *sql.Tx), used to make requests during or outside transactions.
• The query, taking form either:
  • As a whole: Query
  • In split parts: Statement, Table, Set and Condition
• An optional Arg (eg: to store query results)

Here's the full architecture:

type (
    // Handler implements Prepare (from either *sql.DB or *sql.Tx)
    Handler interface {
        Prepare(query string) (*sql.Stmt, error)
    }

    // Request is used to prepare (and optionnaly make) queries via Handler
    // (which can be *sql.DB or *sql.Tx), during or outside transactions.
    Request struct {
        Handler             // might be *sql.Tx or *sql.DB
        query               // Query structure
        Arg     interface{} // for scan functions
    }

    // query is a structure used to concatenate queries
    query struct {
        Query     string // full Query string
        Statement string // statement part of query
        Table     string // targetted table of query
        Set       string // optionnal set parameter of query
        Condition string // optionnal condition of query
    }
)

Methods

// PrepareStmt prepares rq.Query via rq.Handler. If rq.Query is empty, it
// will concatenate the query with its subparts (Statement, Table, ...)
func (rq Request) PrepareStmt() (*sql.Stmt, error) {}

// InsertStructs inserts a slice of structures into the given table. Can insert
// sub structures, if they have the tag `req:"include"`
func (rq Request) InsertStructs(slice interface{}) error {}

// InsertOneStruct inserts one structure into the given table. Can insert sub
// structures, if they have the tag `req:"include"`
func (rq Request) InsertOneStruct(structure interface{}) error {}

// GetRows prepares and makes a query, and returns the resulted rows
func (rq Request) GetRows(args ...interface{}) (*sql.Rows, error) {}

// GetOneRow prepares and makes a query, and returns the resulted row
func (rq Request) GetOneRow(args ...interface{}) (*sql.Row, error) {}

// GetIntoStructs prepares and makes a query, retrieves Rows, and scan them into
// a pointer to a slice of structures. Should be used for queries selecting
// multiple fields from multiple rows
func (rq Request) GetIntoStructs(args ...interface{}) error {}

// GetIntoSlice prepares and makes a query, retrieves Rows, and scan them into
// a pointer to a slice of any type. Should be used for queries selecting one
// field from multiple rows
func (rq Request) GetIntoSlice(args ...interface{}) error {}

// GetOneField prepares and makes a query, retrieves a Row, and scan it into
// the passed pointer. Should be used for queries selecting one field from one
// row
func (rq Request) GetOneField(args ...interface{}) error {}

// GetFields prepares and makes a query, retrieves a Row, and scan it into
// a slice of any pointers. Should be used for queries selecting multiple fields
// from a single row
func (rq Request) GetFields(args ...interface{}) error {}

// GetIntoOneStruct prepares and makes a query, retrieves a Row, and scan it
// into a pointer to one struct. Should be used for queries selecting multiple
// fields from a single row (if this query is unique, consider using GetFields
// instead)
func (rq Request) GetIntoOneStruct(args ...interface{}) error {}

// ExecQuery prepares and makes a query which does not need to return any row
func (rq Request) ExecQuery(args ...interface{}) (sql.Result, error) {}

Documentation

Index

• Variables
• type Handler
• type QueryStruct
  • func (q QueryStruct) String() string
• type Request
  • func FromHandler(handler Handler) Request
  • func (rq Request) ExecQuery(args ...interface{}) (sql.Result, error)
  • func (rq Request) GetFields(args ...interface{}) error
  • func (rq Request) GetIntoOneStruct(args ...interface{}) error
  • func (rq Request) GetIntoSlice(args ...interface{}) error
  • func (rq Request) GetIntoStructs(args ...interface{}) error
  • func (rq Request) GetOneField(args ...interface{}) error
  • func (rq Request) GetOneRow(args ...interface{}) (*sql.Row, error)
  • func (rq Request) GetRows(args ...interface{}) (*sql.Rows, error)
  • func (rq Request) InsertOneStruct(structure interface{}) error
  • func (rq Request) InsertStructs(slice interface{}) error
  • func (rq Request) PrepareStmt() (*sql.Stmt, error)

Variables

var ErrNoArg = errors.New("no passed argument, can not scan")

ErrNoArg is for functions that should scan rows but have no passed argument

Types

type Handler

type Handler interface {
	Prepare(query string) (*sql.Stmt, error)
}

Handler implements Prepare (from either *sql.DB or *sql.Tx)

type QueryStruct

type QueryStruct struct {
	Query     string // full Query string
	Statement string // statement part of query
	Table     string // targeted table of query
	Set       string // optionnal set parameter of query
	Condition string // optionnal condition of query
}

QueryStruct is a structure used to concatenate queries

func (QueryStruct) String

func (q QueryStruct) String() string

String returns a Query string from QueryStruct. If the Query field is not empty, it is returned, else a concatenation of other fields is returned

type Request

type Request struct {
	Handler                 // might be *sql.Tx or *sql.DB
	QueryStruct             // Query structure
	Arg         interface{} // for scan functions
}

Request is used to prepare (and optionnaly make) queries via Handler (which can be *sql.DB or *sql.Tx), during or outside transactions.

func FromHandler

func FromHandler(handler Handler) Request

FromHandler returns an initialized Request with given Handler (*Tx or *DB)

func (Request) ExecQuery

func (rq Request) ExecQuery(args ...interface{}) (sql.Result, error)

ExecQuery prepares and makes a query which does not need to return any row

func (Request) GetFields

func (rq Request) GetFields(args ...interface{}) error

GetFields prepares and makes a query, retrieves a Row, and scan it into a slice of any pointers. Should be used for queries selecting multiple fields from a single row

func (Request) GetIntoOneStruct

func (rq Request) GetIntoOneStruct(args ...interface{}) error

GetIntoOneStruct prepares and makes a query, retrieves a Row, and scan it into a pointer to one struct. Should be used for queries selecting multiple fields from a single row (if this query is unique, consider using GetFields instead)

func (Request) GetIntoSlice

func (rq Request) GetIntoSlice(args ...interface{}) error

GetIntoSlice prepares and makes a query, retrieves Rows, and scan them into a pointer to a slice of any type. Should be used for queries selecting one field from multiple rows

func (Request) GetIntoStructs

func (rq Request) GetIntoStructs(args ...interface{}) error

GetIntoStructs prepares and makes a query, retrieves Rows, and scan them into a pointer to a slice of structures. Should be used for queries selecting multiple fields from multiple rows

func (Request) GetOneField

func (rq Request) GetOneField(args ...interface{}) error

GetOneField prepares and makes a query, retrieves a Row, and scan it into the passed pointer. Should be used for queries selecting one field from one row

func (Request) GetOneRow

func (rq Request) GetOneRow(args ...interface{}) (*sql.Row, error)

GetOneRow prepares and makes a query, and returns the resulted row

func (Request) GetRows

func (rq Request) GetRows(args ...interface{}) (*sql.Rows, error)

GetRows prepares and makes a query, and returns the resulted rows

func (Request) InsertOneStruct

func (rq Request) InsertOneStruct(structure interface{}) error

InsertOneStruct inserts one structure into the given table. Can insert sub structures, if they have the tag `req:"include"`

func (Request) InsertStructs

func (rq Request) InsertStructs(slice interface{}) error

InsertStructs inserts a slice of structures into the given table. Can insert sub structures, if they have the tag `req:"include"`

func (Request) PrepareStmt

func (rq Request) PrepareStmt() (*sql.Stmt, error)

PrepareStmt prepares rq.Query via rq.Handler. If rq.Query is empty, it will concatenate the query with its subparts (Statement, Table, ...). Always called in other methods