dbr

package module
Version: v0.0.0-...-8114670 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 14, 2019 License: MIT Imports: 12 Imported by: 100

README

gocraft/dbr (database records)

GoDoc FOSSA Status Go Report Card CircleCI

gocraft/dbr provides additions to Go's database/sql for super fast performance and convenience.

$ go get -u github.com/gocraft/dbr
import "github.com/gocraft/dbr"

Driver support

  • MySQL
  • PostgreSQL
  • SQLite3

Examples

See godoc for more examples.

Open connections
// create a connection (e.g. "postgres", "mysql", or "sqlite3")
conn, _ := Open("postgres", "...", nil)
conn.SetMaxOpenConns(10)

// create a session for each business unit of execution (e.g. a web request or goworkers job)
sess := conn.NewSession(nil)

// create a tx from sessions
sess.Begin()
Create and use Tx
sess := mysqlSession
tx, err := sess.Begin()
if err != nil {
	return
}
defer tx.RollbackUnlessCommitted()

// do stuff...

tx.Commit()
SelectStmt loads data into structs
// columns are mapped by tag then by field
type Suggestion struct {
	ID	int64		// id, will be autoloaded by last insert id
	Title	NullString	`db:"subject"`	// subjects are called titles now
	Url	string		`db:"-"`	// ignored
	secret	string		// ignored
}

// By default gocraft/dbr converts CamelCase property names to snake_case column_names.
// You can override this with struct tags, just like with JSON tags.
// This is especially helpful while migrating from legacy systems.
var suggestions []Suggestion
sess := mysqlSession
sess.Select("*").From("suggestions").Load(&suggestions)
SelectStmt with where-value interpolation
// database/sql uses prepared statements, which means each argument
// in an IN clause needs its own question mark.
// gocraft/dbr, on the other hand, handles interpolation itself
// so that you can easily use a single question mark paired with a
// dynamically sized slice.

sess := mysqlSession
ids := []int64{1, 2, 3, 4, 5}
sess.Select("*").From("suggestions").Where("id IN ?", ids)
SelectStmt with joins
sess := mysqlSession
sess.Select("*").From("suggestions").
	Join("subdomains", "suggestions.subdomain_id = subdomains.id")

sess.Select("*").From("suggestions").
	LeftJoin("subdomains", "suggestions.subdomain_id = subdomains.id")

// join multiple tables
sess.Select("*").From("suggestions").
	Join("subdomains", "suggestions.subdomain_id = subdomains.id").
	Join("accounts", "subdomains.accounts_id = accounts.id")
SelectStmt with raw SQL
SelectBySql("SELECT `title`, `body` FROM `suggestions` ORDER BY `id` ASC LIMIT 10")
InsertStmt adds data from struct
type Suggestion struct {
	ID		int64
	Title		NullString
	CreatedAt	time.Time
}
sugg := &Suggestion{
	Title:		NewNullString("Gopher"),
	CreatedAt:	time.Now(),
}
sess := mysqlSession
sess.InsertInto("suggestions").
	Columns("title").
	Record(&sugg).
	Exec()

// id is set automatically
fmt.Println(sugg.ID)
InsertStmt adds data from value
sess := mysqlSession
sess.InsertInto("suggestions").
	Pair("title", "Gopher").
	Pair("body", "I love go.")

Benchmark (2018-05-11)

BenchmarkLoadValues/sqlx_10-8         	    5000	    407318 ns/op	    3913 B/op	     164 allocs/op
BenchmarkLoadValues/dbr_10-8          	    5000	    372940 ns/op	    3874 B/op	     123 allocs/op
BenchmarkLoadValues/sqlx_100-8        	    2000	    584197 ns/op	   30195 B/op	    1428 allocs/op
BenchmarkLoadValues/dbr_100-8         	    3000	    558852 ns/op	   22965 B/op	     937 allocs/op
BenchmarkLoadValues/sqlx_1000-8       	    1000	   2319101 ns/op	  289339 B/op	   14031 allocs/op
BenchmarkLoadValues/dbr_1000-8        	    1000	   2310441 ns/op	  210092 B/op	    9040 allocs/op
BenchmarkLoadValues/sqlx_10000-8      	     100	  17004716 ns/op	 3193997 B/op	  140043 allocs/op
BenchmarkLoadValues/dbr_10000-8       	     100	  16150062 ns/op	 2394698 B/op	   90051 allocs/op
BenchmarkLoadValues/sqlx_100000-8     	      10	 170068209 ns/op	31679944 B/op	 1400053 allocs/op
BenchmarkLoadValues/dbr_100000-8      	      10	 147202536 ns/op	23680625 B/op	  900061 allocs/op

Thanks & Authors

Inspiration from these excellent libraries:

  • sqlx - various useful tools and utils for interacting with database/sql.
  • Squirrel - simple fluent query builder.

Authors:

Contributors:

License

FOSSA Status

Documentation

Overview

Package dbr provides additions to Go's database/sql for super fast performance and convenience.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	ErrNotFound           = errors.New("dbr: not found")
	ErrNotSupported       = errors.New("dbr: not supported")
	ErrTableNotSpecified  = errors.New("dbr: table not specified")
	ErrColumnNotSpecified = errors.New("dbr: column not specified")
	ErrInvalidPointer     = errors.New("dbr: attempt to load into an invalid pointer")
	ErrPlaceholderCount   = errors.New("dbr: wrong placeholder count")
	ErrInvalidSliceLength = errors.New("dbr: length of slice is 0. length must be >= 1")
	ErrCantConvertToTime  = errors.New("dbr: can't convert to time.Time")
	ErrInvalidTimestring  = errors.New("dbr: invalid time string")
)

package errors

View Source
var NameMapping = camelCaseToSnakeCase
View Source
var Now = nowSentinel{}

Now is a value that serializes to the current time in UTC.

Functions

func InterfaceLoader

func InterfaceLoader(value interface{}, concreteType interface{}) interface{}

func InterpolateForDialect

func InterpolateForDialect(query string, value []interface{}, d Dialect) (string, error)

InterpolateForDialect replaces placeholder in query with corresponding value in dialect.

It can be also used for debugging custom Builder.

Every time you call database/sql's db.Query("SELECT ...") method, under the hood, the mysql driver will create a prepared statement, execute it, and then throw it away. This has a big performance cost.

gocraft/dbr doesn't use prepared statements. We ported mysql's query escape functionality directly into our package, which means we interpolate all of those question marks with their arguments before they get to MySQL. The result of this is that it's way faster, and just as secure.

Check out these benchmarks from https://github.com/tyler-smith/golang-sql-benchmark.

func Load

func Load(rows *sql.Rows, value interface{}) (int, error)

Load loads any value from sql.Rows.

value can be:

1. simple type like int64, string, etc.

2. sql.Scanner, which allows loading with custom types.

3. map; the first column from SQL result loaded to the key, and the rest of columns will be loaded into the value. This is useful to dedup SQL result with first column.

4. map of slice; like map, values with the same key are collected with a slice.

func Union

func Union(builder ...Builder) interface {
	Builder
	As(string) Builder
}

Union builds `... UNION ...`.

Example
Union(
	Select("*"),
	Select("*"),
).As("subquery")
Output:

func UnionAll

func UnionAll(builder ...Builder) interface {
	Builder
	As(string) Builder
}

UnionAll builds `... UNION ALL ...`.

Example
UnionAll(
	Select("*"),
	Select("*"),
).As("subquery")
Output:

Types

type Buffer

type Buffer interface {
	WriteString(string) (int, error)
	String() string

	WriteValue(v ...interface{}) (err error)
	Value() []interface{}
}

Buffer collects strings, and values that are ready to be interpolated. This is used internally to efficiently build SQL statement.

func NewBuffer

func NewBuffer() Buffer

NewBuffer creates a new Buffer.

type BuildFunc

type BuildFunc func(Dialect, Buffer) error

BuildFunc implements Builder.

func (BuildFunc) Build

func (b BuildFunc) Build(d Dialect, buf Buffer) error

Build calls itself to build SQL.

type Builder

type Builder interface {
	Build(Dialect, Buffer) error
}

Builder builds SQL in Dialect like MySQL, and PostgreSQL. The raw SQL and values are stored in Buffer.

The core of gocraft/dbr is interpolation, which can expand ? with arbitrary SQL. If you need a feature that is not currently supported, you can build it on your own (or use Expr).

To do that, the value that you wish to be expanded with ? needs to implement Builder.

func And

func And(cond ...Builder) Builder

And creates AND from a list of conditions.

Example
And(
	Or(
		Gt("created_at", "2015-09-10"),
		Lte("created_at", "2015-09-11"),
	),
	Eq("title", "hello world"),
)
Output:

func Eq

func Eq(column string, value interface{}) Builder

Eq is `=`. When value is nil, it will be translated to `IS NULL`. When value is a slice, it will be translated to `IN`. Otherwise it will be translated to `=`.

func Expr

func Expr(query string, value ...interface{}) Builder

Expr allows raw expression to be used when current SQL syntax is not supported by gocraft/dbr.

func Gt

func Gt(column string, value interface{}) Builder

Gt is `>`.

func Gte

func Gte(column string, value interface{}) Builder

Gte is '>='.

func Like

func Like(column, value string, escape ...string) Builder

Like is `LIKE`, with an optional `ESCAPE` clause

func Lt

func Lt(column string, value interface{}) Builder

Lt is '<'.

func Lte

func Lte(column string, value interface{}) Builder

Lte is `<=`.

func Neq

func Neq(column string, value interface{}) Builder

Neq is `!=`. When value is nil, it will be translated to `IS NOT NULL`. When value is a slice, it will be translated to `NOT IN`. Otherwise it will be translated to `!=`.

func NotLike

func NotLike(column, value string, escape ...string) Builder

NotLike is `NOT LIKE`, with an optional `ESCAPE` clause

func Or

func Or(cond ...Builder) Builder

Or creates OR from a list of conditions.

type Connection

type Connection struct {
	*sql.DB
	Dialect
	EventReceiver
}

Connection wraps sql.DB with an EventReceiver to send events, errors, and timings.

func Open

func Open(driver, dsn string, log EventReceiver) (*Connection, error)

Open creates a Connection. log can be nil to ignore logging.

Example
// create a connection (e.g. "postgres", "mysql", or "sqlite3")
conn, _ := Open("postgres", "...", nil)
conn.SetMaxOpenConns(10)

// create a session for each business unit of execution (e.g. a web request or goworkers job)
sess := conn.NewSession(nil)

// create a tx from sessions
sess.Begin()
Output:

func (*Connection) NewSession

func (conn *Connection) NewSession(log EventReceiver) *Session

NewSession instantiates a Session from Connection. If log is nil, Connection EventReceiver is used.

type DeleteBuilder

type DeleteBuilder = DeleteStmt

type DeleteStmt

type DeleteStmt struct {
	EventReceiver
	Dialect

	Table      string
	WhereCond  []Builder
	LimitCount int64
	// contains filtered or unexported fields
}

DeleteStmt builds `DELETE ...`.

Example
sess := mysqlSession
sess.DeleteFrom("suggestions").
	Where("id = ?", 1)
Output:

func DeleteBySql

func DeleteBySql(query string, value ...interface{}) *DeleteStmt

DeleteBySql creates a DeleteStmt from raw query.

func DeleteFrom

func DeleteFrom(table string) *DeleteStmt

DeleteFrom creates a DeleteStmt.

func (*DeleteStmt) Build

func (b *DeleteStmt) Build(d Dialect, buf Buffer) error

func (*DeleteStmt) Exec

func (b *DeleteStmt) Exec() (sql.Result, error)

func (*DeleteStmt) ExecContext

func (b *DeleteStmt) ExecContext(ctx context.Context) (sql.Result, error)

func (*DeleteStmt) Limit

func (b *DeleteStmt) Limit(n uint64) *DeleteStmt

func (*DeleteStmt) Where

func (b *DeleteStmt) Where(query interface{}, value ...interface{}) *DeleteStmt

Where adds a where condition. query can be Builder or string. value is used only if query type is string.

type Dialect

type Dialect interface {
	QuoteIdent(id string) string

	EncodeString(s string) string
	EncodeBool(b bool) string
	EncodeTime(t time.Time) string
	EncodeBytes(b []byte) string

	Placeholder(n int) string
}

Dialect abstracts database driver differences in encoding types, and placeholders.

type EventReceiver

type EventReceiver interface {
	Event(eventName string)
	EventKv(eventName string, kvs map[string]string)
	EventErr(eventName string, err error) error
	EventErrKv(eventName string, err error, kvs map[string]string) error
	Timing(eventName string, nanoseconds int64)
	TimingKv(eventName string, nanoseconds int64, kvs map[string]string)
}

EventReceiver gets events from dbr methods for logging purposes.

type I

type I string

I is quoted identifier

Example
// I, identifier, can be used to quote.
I("suggestions.id").As("id") // `suggestions`.`id`
Output:

func (I) As

func (i I) As(alias string) Builder

As creates an alias for expr.

func (I) Build

func (i I) Build(d Dialect, buf Buffer) error

Build quotes string with dialect.

type InsertBuilder

type InsertBuilder = InsertStmt

type InsertStmt

type InsertStmt struct {
	EventReceiver
	Dialect

	Table        string
	Column       []string
	Value        [][]interface{}
	ReturnColumn []string
	RecordID     *int64
	// contains filtered or unexported fields
}

InsertStmt builds `INSERT INTO ...`.

func InsertBySql

func InsertBySql(query string, value ...interface{}) *InsertStmt

InsertBySql creates an InsertStmt from raw query.

func InsertInto

func InsertInto(table string) *InsertStmt

InsertInto creates an InsertStmt.

func (*InsertStmt) Build

func (b *InsertStmt) Build(d Dialect, buf Buffer) error

func (*InsertStmt) Columns

func (b *InsertStmt) Columns(column ...string) *InsertStmt

func (*InsertStmt) Exec

func (b *InsertStmt) Exec() (sql.Result, error)

func (*InsertStmt) ExecContext

func (b *InsertStmt) ExecContext(ctx context.Context) (sql.Result, error)

func (*InsertStmt) Load

func (b *InsertStmt) Load(value interface{}) error

func (*InsertStmt) LoadContext

func (b *InsertStmt) LoadContext(ctx context.Context, value interface{}) error

func (*InsertStmt) Pair

func (b *InsertStmt) Pair(column string, value interface{}) *InsertStmt

Pair adds (column, value) to be inserted. It is an error to mix Pair with Values and Record.

Example
sess := mysqlSession
sess.InsertInto("suggestions").
	Pair("title", "Gopher").
	Pair("body", "I love go.")
Output:

func (*InsertStmt) Record

func (b *InsertStmt) Record(structValue interface{}) *InsertStmt

Record adds a tuple for columns from a struct.

If there is a field called "Id" or "ID" in the struct, it will be set to LastInsertId.

Example
type Suggestion struct {
	ID        int64
	Title     NullString
	CreatedAt time.Time
}
sugg := &Suggestion{
	Title:     NewNullString("Gopher"),
	CreatedAt: time.Now(),
}
sess := mysqlSession
sess.InsertInto("suggestions").
	Columns("title").
	Record(&sugg).
	Exec()

// id is set automatically
fmt.Println(sugg.ID)
Output:

func (*InsertStmt) Returning

func (b *InsertStmt) Returning(column ...string) *InsertStmt

Returning specifies the returning columns for postgres.

func (*InsertStmt) Values

func (b *InsertStmt) Values(value ...interface{}) *InsertStmt

Values adds a tuple to be inserted. The order of the tuple should match Columns.

type NullBool

type NullBool struct {
	sql.NullBool
}

NullBool is a type that can be null or a bool.

func NewNullBool

func NewNullBool(v interface{}) (n NullBool)

NewNullBool creates a NullBool with Scan().

func (NullBool) MarshalJSON

func (n NullBool) MarshalJSON() ([]byte, error)

MarshalJSON correctly serializes a NullBool to JSON.

func (*NullBool) UnmarshalJSON

func (n *NullBool) UnmarshalJSON(b []byte) error

UnmarshalJSON correctly deserializes a NullBool from JSON.

type NullEventReceiver

type NullEventReceiver struct{}

NullEventReceiver is a sentinel EventReceiver. Use it if the caller doesn't supply one.

func (*NullEventReceiver) Event

func (n *NullEventReceiver) Event(eventName string)

Event receives a simple notification when various events occur.

func (*NullEventReceiver) EventErr

func (n *NullEventReceiver) EventErr(eventName string, err error) error

EventErr receives a notification of an error if one occurs.

func (*NullEventReceiver) EventErrKv

func (n *NullEventReceiver) EventErrKv(eventName string, err error, kvs map[string]string) error

EventErrKv receives a notification of an error if one occurs along with optional key/value data.

func (*NullEventReceiver) EventKv

func (n *NullEventReceiver) EventKv(eventName string, kvs map[string]string)

EventKv receives a notification when various events occur along with optional key/value data.

func (*NullEventReceiver) Timing

func (n *NullEventReceiver) Timing(eventName string, nanoseconds int64)

Timing receives the time an event took to happen.

func (*NullEventReceiver) TimingKv

func (n *NullEventReceiver) TimingKv(eventName string, nanoseconds int64, kvs map[string]string)

TimingKv receives the time an event took to happen along with optional key/value data.

type NullFloat64

type NullFloat64 struct {
	sql.NullFloat64
}

NullFloat64 is a type that can be null or a float64.

func NewNullFloat64

func NewNullFloat64(v interface{}) (n NullFloat64)

NewNullFloat64 creates a NullFloat64 with Scan().

func (NullFloat64) MarshalJSON

func (n NullFloat64) MarshalJSON() ([]byte, error)

MarshalJSON correctly serializes a NullFloat64 to JSON.

func (*NullFloat64) UnmarshalJSON

func (n *NullFloat64) UnmarshalJSON(b []byte) error

UnmarshalJSON correctly deserializes a NullFloat64 from JSON.

type NullInt64

type NullInt64 struct {
	sql.NullInt64
}

NullInt64 is a type that can be null or an int.

func NewNullInt64

func NewNullInt64(v interface{}) (n NullInt64)

NewNullInt64 creates a NullInt64 with Scan().

func (NullInt64) MarshalJSON

func (n NullInt64) MarshalJSON() ([]byte, error)

MarshalJSON correctly serializes a NullInt64 to JSON.

func (*NullInt64) UnmarshalJSON

func (n *NullInt64) UnmarshalJSON(b []byte) error

UnmarshalJSON correctly deserializes a NullInt64 from JSON.

type NullString

type NullString struct {
	sql.NullString
}

NullString is a type that can be null or a string.

func NewNullString

func NewNullString(v interface{}) (n NullString)

NewNullString creates a NullString with Scan().

func (NullString) MarshalJSON

func (n NullString) MarshalJSON() ([]byte, error)

MarshalJSON correctly serializes a NullString to JSON.

func (*NullString) UnmarshalJSON

func (n *NullString) UnmarshalJSON(b []byte) error

UnmarshalJSON correctly deserializes a NullString from JSON.

type NullTime

type NullTime struct {
	Time  time.Time
	Valid bool // Valid is true if Time is not NULL
}

NullTime is a type that can be null or a time.

func NewNullTime

func NewNullTime(v interface{}) (n NullTime)

NewNullTime creates a NullTime with Scan().

func (NullTime) MarshalJSON

func (n NullTime) MarshalJSON() ([]byte, error)

MarshalJSON correctly serializes a NullTime to JSON.

func (*NullTime) Scan

func (n *NullTime) Scan(value interface{}) error

Scan implements the Scanner interface. The value type must be time.Time or string / []byte (formatted time-string), otherwise Scan fails.

func (*NullTime) UnmarshalJSON

func (n *NullTime) UnmarshalJSON(b []byte) error

UnmarshalJSON correctly deserializes a NullTime from JSON.

func (NullTime) Value

func (n NullTime) Value() (driver.Value, error)

Value implements the driver Valuer interface.

type SelectBuilder

type SelectBuilder = SelectStmt

type SelectStmt

type SelectStmt struct {
	EventReceiver
	Dialect

	IsDistinct bool

	Column    []interface{}
	Table     interface{}
	JoinTable []Builder

	WhereCond  []Builder
	Group      []Builder
	HavingCond []Builder
	Order      []Builder
	Suffixes   []Builder

	LimitCount  int64
	OffsetCount int64
	// contains filtered or unexported fields
}

SelectStmt builds `SELECT ...`.

func Select

func Select(column ...interface{}) *SelectStmt

Select creates a SelectStmt.

Example
Select("title", "body").
	From("suggestions").
	OrderBy("id").
	Limit(10)
Output:

func SelectBySql

func SelectBySql(query string, value ...interface{}) *SelectStmt

SelectBySql creates a SelectStmt from raw query.

Example
SelectBySql("SELECT `title`, `body` FROM `suggestions` ORDER BY `id` ASC LIMIT 10")
Output:

func (*SelectStmt) As

func (b *SelectStmt) As(alias string) Builder

As creates alias for select statement.

Example
sess := mysqlSession
sess.Select("count(id)").From(
	Select("*").From("suggestions").As("count"),
)
Output:

func (*SelectStmt) Build

func (b *SelectStmt) Build(d Dialect, buf Buffer) error

func (*SelectStmt) Distinct

func (b *SelectStmt) Distinct() *SelectStmt

func (*SelectStmt) From

func (b *SelectStmt) From(table interface{}) *SelectStmt

From specifies table to select from. table can be Builder like SelectStmt, or string.

func (*SelectStmt) FullJoin

func (b *SelectStmt) FullJoin(table, on interface{}) *SelectStmt

FullJoin add full-join. on can be Builder or string.

func (*SelectStmt) GroupBy

func (b *SelectStmt) GroupBy(col ...string) *SelectStmt

GroupBy specifies columns for grouping.

func (*SelectStmt) Having

func (b *SelectStmt) Having(query interface{}, value ...interface{}) *SelectStmt

Having adds a having condition. query can be Builder or string. value is used only if query type is string.

func (*SelectStmt) Join

func (b *SelectStmt) Join(table, on interface{}) *SelectStmt

Join add inner-join. on can be Builder or string.

Example
sess := mysqlSession
sess.Select("*").From("suggestions").
	Join("subdomains", "suggestions.subdomain_id = subdomains.id")

sess.Select("*").From("suggestions").
	LeftJoin("subdomains", "suggestions.subdomain_id = subdomains.id")

// join multiple tables
sess.Select("*").From("suggestions").
	Join("subdomains", "suggestions.subdomain_id = subdomains.id").
	Join("accounts", "subdomains.accounts_id = accounts.id")
Output:

func (*SelectStmt) LeftJoin

func (b *SelectStmt) LeftJoin(table, on interface{}) *SelectStmt

LeftJoin add left-join. on can be Builder or string.

func (*SelectStmt) Limit

func (b *SelectStmt) Limit(n uint64) *SelectStmt

func (*SelectStmt) Load

func (b *SelectStmt) Load(value interface{}) (int, error)

Load loads multi-row SQL result into a slice of go variables.

See https://godoc.org/github.com/gocraft/dbr#Load.

Example
// columns are mapped by tag then by field
type Suggestion struct {
	ID     int64      // id, will be autoloaded by last insert id
	Title  NullString `db:"subject"` // subjects are called titles now
	Url    string     `db:"-"`       // ignored
	secret string     // ignored
}

// By default gocraft/dbr converts CamelCase property names to snake_case column_names.
// You can override this with struct tags, just like with JSON tags.
// This is especially helpful while migrating from legacy systems.
var suggestions []Suggestion
sess := mysqlSession
sess.Select("*").From("suggestions").Load(&suggestions)
Output:

func (*SelectStmt) LoadContext

func (b *SelectStmt) LoadContext(ctx context.Context, value interface{}) (int, error)

func (*SelectStmt) LoadOne

func (b *SelectStmt) LoadOne(value interface{}) error

LoadOne loads SQL result into go variable that is not a slice. Unlike Load, it returns ErrNotFound if the SQL result row count is 0.

See https://godoc.org/github.com/gocraft/dbr#Load.

func (*SelectStmt) LoadOneContext

func (b *SelectStmt) LoadOneContext(ctx context.Context, value interface{}) error

func (*SelectStmt) Offset

func (b *SelectStmt) Offset(n uint64) *SelectStmt

func (*SelectStmt) OrderAsc

func (b *SelectStmt) OrderAsc(col string) *SelectStmt

func (*SelectStmt) OrderBy

func (b *SelectStmt) OrderBy(col string) *SelectStmt

OrderBy specifies columns for ordering.

func (*SelectStmt) OrderDesc

func (b *SelectStmt) OrderDesc(col string) *SelectStmt

func (*SelectStmt) OrderDir

func (b *SelectStmt) OrderDir(col string, isAsc bool) *SelectStmt

OrderDir is a helper for OrderAsc and OrderDesc.

func (*SelectStmt) Paginate

func (b *SelectStmt) Paginate(page, perPage uint64) *SelectStmt

Paginate fetches a page in a naive way for a small set of data.

func (*SelectStmt) ReturnInt64

func (b *SelectStmt) ReturnInt64() (int64, error)

ReturnInt64 executes the SelectStmt and returns the value as an int64.

func (*SelectStmt) ReturnInt64s

func (b *SelectStmt) ReturnInt64s() ([]int64, error)

ReturnInt64s executes the SelectStmt and returns the value as a slice of int64s.

func (*SelectStmt) ReturnString

func (b *SelectStmt) ReturnString() (string, error)

ReturnString executes the SelectStmt and returns the value as a string.

func (*SelectStmt) ReturnStrings

func (b *SelectStmt) ReturnStrings() ([]string, error)

ReturnStrings executes the SelectStmt and returns the value as a slice of strings.

func (*SelectStmt) ReturnUint64

func (b *SelectStmt) ReturnUint64() (uint64, error)

ReturnUint64 executes the SelectStmt and returns the value as an uint64.

func (*SelectStmt) ReturnUint64s

func (b *SelectStmt) ReturnUint64s() ([]uint64, error)

ReturnUint64s executes the SelectStmt and returns the value as a slice of uint64s.

func (*SelectStmt) RightJoin

func (b *SelectStmt) RightJoin(table, on interface{}) *SelectStmt

RightJoin add right-join. on can be Builder or string.

func (*SelectStmt) Rows

func (b *SelectStmt) Rows() (*sql.Rows, error)

Rows executes the query and returns the rows returned, or any error encountered.

func (*SelectStmt) RowsContext

func (b *SelectStmt) RowsContext(ctx context.Context) (*sql.Rows, error)

func (*SelectStmt) Suffix

func (b *SelectStmt) Suffix(suffix string, value ...interface{}) *SelectStmt

Suffix adds an expression to the end of the query. This is useful to add dialect-specific clauses like FOR UPDATE

func (*SelectStmt) Where

func (b *SelectStmt) Where(query interface{}, value ...interface{}) *SelectStmt

Where adds a where condition. query can be Builder or string. value is used only if query type is string.

Example
// database/sql uses prepared statements, which means each argument
// in an IN clause needs its own question mark.
// gocraft/dbr, on the other hand, handles interpolation itself
// so that you can easily use a single question mark paired with a
// dynamically sized slice.

sess := mysqlSession
ids := []int64{1, 2, 3, 4, 5}
sess.Select("*").From("suggestions").Where("id IN ?", ids)
Output:

type Session

type Session struct {
	*Connection
	EventReceiver
	Timeout time.Duration
}

Session represents a business unit of execution.

All queries in gocraft/dbr are made in the context of a session. This is because when instrumenting your app, it's important to understand which business action the query took place in.

A custom EventReceiver can be set.

Timeout specifies max duration for an operation like Select.

func (*Session) Begin

func (sess *Session) Begin() (*Tx, error)

Begin creates a transaction for the given session.

func (*Session) BeginTx

func (sess *Session) BeginTx(ctx context.Context, opts *sql.TxOptions) (*Tx, error)

BeginTx creates a transaction with TxOptions.

func (*Session) DeleteBySql

func (sess *Session) DeleteBySql(query string, value ...interface{}) *DeleteStmt

DeleteBySql creates a DeleteStmt from raw query.

func (*Session) DeleteFrom

func (sess *Session) DeleteFrom(table string) *DeleteStmt

DeleteFrom creates a DeleteStmt.

func (*Session) GetTimeout

func (sess *Session) GetTimeout() time.Duration

GetTimeout returns current timeout enforced in session.

func (*Session) InsertBySql

func (sess *Session) InsertBySql(query string, value ...interface{}) *InsertStmt

InsertBySql creates an InsertStmt from raw query.

func (*Session) InsertInto

func (sess *Session) InsertInto(table string) *InsertStmt

InsertInto creates an InsertStmt.

func (*Session) Select

func (sess *Session) Select(column ...string) *SelectStmt

Select creates a SelectStmt.

func (*Session) SelectBySql

func (sess *Session) SelectBySql(query string, value ...interface{}) *SelectStmt

SelectBySql creates a SelectStmt from raw query.

func (*Session) Update

func (sess *Session) Update(table string) *UpdateStmt

Update creates an UpdateStmt.

func (*Session) UpdateBySql

func (sess *Session) UpdateBySql(query string, value ...interface{}) *UpdateStmt

UpdateBySql creates an UpdateStmt with raw query.

type SessionRunner

type SessionRunner interface {
	Select(column ...string) *SelectBuilder
	SelectBySql(query string, value ...interface{}) *SelectBuilder

	InsertInto(table string) *InsertBuilder
	InsertBySql(query string, value ...interface{}) *InsertBuilder

	Update(table string) *UpdateBuilder
	UpdateBySql(query string, value ...interface{}) *UpdateBuilder

	DeleteFrom(table string) *DeleteBuilder
	DeleteBySql(query string, value ...interface{}) *DeleteBuilder
}

SessionRunner can do anything that a Session can except start a transaction. Both Session and Tx implements this interface.

type TracingEventReceiver

type TracingEventReceiver interface {
	SpanStart(ctx context.Context, eventName, query string) context.Context
	SpanError(ctx context.Context, err error)
	SpanFinish(ctx context.Context)
}

TracingEventReceiver is an optional interface an EventReceiver type can implement to allow tracing instrumentation

type Tx

type Tx struct {
	EventReceiver
	Dialect
	*sql.Tx
	Timeout time.Duration
}

Tx is a transaction created by Session.

Example
sess := mysqlSession
tx, err := sess.Begin()
if err != nil {
	return
}
defer tx.RollbackUnlessCommitted()

// do stuff...

tx.Commit()
Output:

func (*Tx) Commit

func (tx *Tx) Commit() error

Commit finishes the transaction.

func (*Tx) DeleteBySql

func (tx *Tx) DeleteBySql(query string, value ...interface{}) *DeleteStmt

DeleteBySql creates a DeleteStmt from raw query.

func (*Tx) DeleteFrom

func (tx *Tx) DeleteFrom(table string) *DeleteStmt

DeleteFrom creates a DeleteStmt.

func (*Tx) GetTimeout

func (tx *Tx) GetTimeout() time.Duration

GetTimeout returns timeout enforced in Tx.

func (*Tx) InsertBySql

func (tx *Tx) InsertBySql(query string, value ...interface{}) *InsertStmt

InsertBySql creates an InsertStmt from raw query.

func (*Tx) InsertInto

func (tx *Tx) InsertInto(table string) *InsertStmt

InsertInto creates an InsertStmt.

func (*Tx) Rollback

func (tx *Tx) Rollback() error

Rollback cancels the transaction.

func (*Tx) RollbackUnlessCommitted

func (tx *Tx) RollbackUnlessCommitted()

RollbackUnlessCommitted rollsback the transaction unless it has already been committed or rolled back.

Useful to defer tx.RollbackUnlessCommitted(), so you don't have to handle N failure cases. Keep in mind the only way to detect an error on the rollback is via the event log.

func (*Tx) Select

func (tx *Tx) Select(column ...string) *SelectStmt

Select creates a SelectStmt.

func (*Tx) SelectBySql

func (tx *Tx) SelectBySql(query string, value ...interface{}) *SelectStmt

SelectBySql creates a SelectStmt from raw query.

func (*Tx) Update

func (tx *Tx) Update(table string) *UpdateStmt

Update creates an UpdateStmt.

func (*Tx) UpdateBySql

func (tx *Tx) UpdateBySql(query string, value ...interface{}) *UpdateStmt

UpdateBySql creates an UpdateStmt with raw query.

type UpdateBuilder

type UpdateBuilder = UpdateStmt

type UpdateStmt

type UpdateStmt struct {
	EventReceiver
	Dialect

	Table        string
	Value        map[string]interface{}
	WhereCond    []Builder
	ReturnColumn []string
	LimitCount   int64
	// contains filtered or unexported fields
}

UpdateStmt builds `UPDATE ...`.

Example
sess := mysqlSession
sess.Update("suggestions").
	Set("title", "Gopher").
	Set("body", "I love go.").
	Where("id = ?", 1)
Output:

func Update

func Update(table string) *UpdateStmt

Update creates an UpdateStmt.

func UpdateBySql

func UpdateBySql(query string, value ...interface{}) *UpdateStmt

UpdateBySql creates an UpdateStmt with raw query.

func (*UpdateStmt) Build

func (b *UpdateStmt) Build(d Dialect, buf Buffer) error

func (*UpdateStmt) Exec

func (b *UpdateStmt) Exec() (sql.Result, error)

func (*UpdateStmt) ExecContext

func (b *UpdateStmt) ExecContext(ctx context.Context) (sql.Result, error)

func (*UpdateStmt) Limit

func (b *UpdateStmt) Limit(n uint64) *UpdateStmt

func (*UpdateStmt) Load

func (b *UpdateStmt) Load(value interface{}) error

func (*UpdateStmt) LoadContext

func (b *UpdateStmt) LoadContext(ctx context.Context, value interface{}) error

func (*UpdateStmt) Returning

func (b *UpdateStmt) Returning(column ...string) *UpdateStmt

Returning specifies the returning columns for postgres.

func (*UpdateStmt) Set

func (b *UpdateStmt) Set(column string, value interface{}) *UpdateStmt

Set updates column with value.

func (*UpdateStmt) SetMap

func (b *UpdateStmt) SetMap(m map[string]interface{}) *UpdateStmt

SetMap specifies a map of (column, value) to update in bulk.

func (*UpdateStmt) Where

func (b *UpdateStmt) Where(query interface{}, value ...interface{}) *UpdateStmt

Where adds a where condition. query can be Builder or string. value is used only if query type is string.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL