Documentation

Overview

Package sqlbuilder provides tools for building custom SQL queries.

Index

Constants

This section is empty.

Variables

var (
	// ValuerType is the reflection type for the driver.Valuer interface.
	ValuerType = reflect.TypeOf((*driver.Valuer)(nil)).Elem()

	// ScannerType is the reflection type for the sql.Scanner interface.
	ScannerType = reflect.TypeOf((*sql.Scanner)(nil)).Elem()

	// ValueWrapperType is the reflection type for the sql.ValueWrapper interface.
	ValueWrapperType = reflect.TypeOf((*ValueWrapper)(nil)).Elem()
)

var (
	ErrExpectingPointer                    = errors.New(`argument must be an address`)
	ErrExpectingSlicePointer               = errors.New(`argument must be a slice address`)
	ErrExpectingSliceMapStruct             = errors.New(`argument must be a slice address of maps or structs`)
	ErrExpectingMapOrStruct                = errors.New(`argument must be either a map or a struct`)
	ErrExpectingPointerToEitherMapOrStruct = errors.New(`expecting a pointer to either a map or a struct`)
)

Common error messages.


var Mapper = reflectx.NewMapper("db")

Functions

func BindDB

func BindDB(adapterName string, sess *sql.DB) (db.Session, error)

Bind creates a binding between an adapter and a *sql.Tx or a *sql.DB.

func Map

func Map(item interface{}, options *MapOptions) ([]string, []interface{}, error)

Map receives a pointer to map or struct and maps it to columns and values.

func NewCompatAdapter

func NewCompatAdapter(adapter Adapter) db.Adapter

func Preprocess

func Preprocess(in string, args []interface{}) (string, []interface{})

Preprocess expands arguments that needs to be expanded and compiles a query into a single string.

func WithSession

func WithSession(sess interface{}, t *exql.Template) db.SQL

WithSession returns a query builder that is bound to the given database session.

func WithTemplate

func WithTemplate(t *exql.Template) db.SQL

WithTemplate returns a builder that is based on the given template.

Types

type Adapter

type Adapter interface {
	// New wraps an active *sql.DB session and returns a SQLBuilder database.  The
	// adapter needs to be imported to the blank namespace in order for it to be
	// used here.
	//
	// This method is internally used by upper-db to create a builder backed by the
	// given database.  You may want to use your adapter's New function instead of
	// this one.
	New(*sql.DB) (db.Session, error)

	// NewTx wraps an active *sql.Tx transation and returns a SQLBuilder
	// transaction.  The adapter needs to be imported to the blank namespace in
	// order for it to be used.
	//
	// This method is internally used by upper-db to create a builder backed by the
	// given transaction.  You may want to use your adapter's NewTx function
	// instead of this one.
	NewTx(*sql.Tx) (Tx, error)

	// Open opens a SQL database.
	OpenDSN(db.ConnectionURL) (db.Session, error)
}

Adapter represents a SQL adapter.

type BatchInserter

type BatchInserter struct {
	// contains filtered or unexported fields
}

BatchInserter provides a helper that can be used to do massive insertions in batches.

func (*BatchInserter) Done

func (b *BatchInserter) Done()

Done means that no more elements are going to be added.

func (*BatchInserter) Err

func (b *BatchInserter) Err() error

Err returns any error while executing the batch.

func (*BatchInserter) NextResult

func (b *BatchInserter) NextResult(dst interface{}) bool

NextResult is useful when using PostgreSQL and Returning(), it dumps the next slice of results to dst, which can mean having the IDs of all inserted elements in the batch.

func (*BatchInserter) Values

func (b *BatchInserter) Values(values ...interface{}) db.BatchInserter

Values pushes column values to be inserted as part of the batch.

func (*BatchInserter) Wait

func (b *BatchInserter) Wait() error

Wait blocks until the whole batch is executed.

type Engine

type Engine interface {
	db.Session

	db.SQL
}

Engine represents a SQL database engine.

type MapOptions

type MapOptions struct {
	IncludeZeroed bool
	IncludeNil    bool
}

MapOptions represents options for the mapper.

type ScannerValuer

type ScannerValuer interface {
	driver.Valuer
	sql.Scanner
}

ScannerValuer represents a value that satisfies both driver.Valuer and sql.Scanner interfaces.

type Tx

type Tx interface {
	// All db.Session methods are available on transaction sessions. They will
	// run on the same transaction.
	db.Session

	Commit() error

	Rollback() error
}

Tx represents a transaction on a SQL database. A transaction is like a regular Session except it has two extra methods: Commit and Rollback.

A transaction needs to be committed (with Commit) to make changes permanent, changes can be discarded before committing by rolling back (with Rollback). After either committing or rolling back a transaction it can not longer be used and it's automatically closed.

func BindTx

func BindTx(adapterName string, tx *sql.Tx) (Tx, error)

type ValueWrapper

type ValueWrapper interface {
	WrapValue(value interface{}) interface{}
}

ValueWrapper defines a method WrapValue that query arguments can use to wrap themselves around helper types right before being used in a query.

Example:

  func (a MyCustomArray) WrapValue(value interface{}) interface{} {
    // postgresql.Array adds a driver.Valuer and sql.Scanner around
    // custom arrays.
	   return postgresql.Array(values)
  }