bob

package module
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2023 License: MIT Imports: 11 Imported by: 5

README

Bob: Go SQL Access Toolkit

Test Status GitHub go.mod Go version Go Reference Go Report Card GitHub tag (latest SemVer) Coverage Status

About

Bob is a set of Go packages and tools to work with SQL databases.

Bob's philosophy centres around the following:

  1. Correctness: Things should work correctly. Follow specifications as closely as possible.
  2. Convenience (not magic): Bob provides convenient ways to perform actions, it does not add unexplainable magic, or needless abstraction.
  3. Cooperation: Bob should work well with other tools and packages as much as possible, especially the standard library.

Bob can be progressively adopted from raw SQL query strings, to fully typed queries with models and factories generated for your database.

Components of Bob

Bob consists of several components that build on each other for the full experience.

  1. Query Builder
  2. SQL Executor for convenient scanning of results
  3. Models for convenient database queries
  4. Code generation of Models and Factories from your database schema

Check out the documentation for more information.

Support

Queries Models ORM Gen Factory Gen
Postgres ✅ ✅ ✅ ✅
MySQL/MariaDB ✅ ✅ ✅ ✅
SQLite ✅ ✅ ✅ ✅
Atlas ✅ ✅
Prisma ✅ ✅

Comparisons

  1. Bob vs GORM
  2. Bob vs Ent
  3. Bob vs SQLBoiler
  4. Bob vs Jet

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoNamedArgs = errors.New("Dialect does not support named arguments")

Functions

func All 

func All[T any](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], opts ...ExecOption[T]) ([]T, error)

func Allx 

func Allx[T any, Ts ~[]T](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], opts ...ExecOption[T]) (Ts, error)

Allx takes 2 type parameters. The second is a special return type of the returned slice this is especially useful for when the the Query is Loadable and the loader depends on the return value implementing an interface

func Build 

func Build(q Query) (string, []any, error)

Convinient function to build query from start

func BuildN 

func BuildN(q Query, start int) (string, []any, error)

Convinient function to build query from a point

func Cursor 

func Cursor[T any](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], opts ...ExecOption[T]) (scan.ICursor[T], error)

Cursor returns a cursor that works similar to *sql.Rows

func Exec added in v0.3.1 

func Exec(ctx context.Context, exec Executor, q Query) (sql.Result, error)

func Express 

func Express(w io.Writer, d Dialect, start int, e any) ([]any, error)

func ExpressIf 

func ExpressIf(w io.Writer, d Dialect, start int, e any, cond bool, prefix, suffix string) ([]any, error)

ExpressIf expands an express if the condition evaluates to true it can also add a prefix and suffix

func ExpressSlice 

func ExpressSlice[T any](w io.Writer, d Dialect, start int, expressions []T, prefix, sep, suffix string) ([]any, error)

ExpressSlice is used to express a slice of expressions along with a prefix and suffix

func MustBuild 

func MustBuild(q Query) (string, []any)

MustBuild builds a query and panics on error useful for initializing queries that need to be reused

func MustBuildN 

func MustBuildN(q Query, start int) (string, []any)

func New 

func New[T StdInterface](wrapped T) common[T]

New wraps an stdInterface to make it comply with Queryer It also includes a number of other methods that are often used with *sql.DB, *sql.Tx and *sql.Conn

func NewQueryer 

func NewQueryer[T stdscan.Queryer](wrapped T) scan.Queryer

NewQueryer wraps an stdscan.Queryer and makes it a scan.Queryer

func One 

func One[T any](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], opts ...ExecOption[T]) (T, error)

Types

type BaseQuery 

type BaseQuery[E Expression] struct {
	Expression E
	Dialect    Dialect
}

BaseQuery wraps common functionality such as cloning, applying new mods and the actual query interface implementation

func (BaseQuery[E]) Apply 

func (b BaseQuery[E]) Apply(mods ...Mod[E])

func (BaseQuery[E]) Build 

func (q BaseQuery[E]) Build() (string, []any, error)

Convinient function to build query from start

func (BaseQuery[E]) BuildN 

func (q BaseQuery[E]) BuildN(start int) (string, []any, error)

Convinient function to build query from a point

func (BaseQuery[E]) Clone 

func (b BaseQuery[E]) Clone() BaseQuery[E]

func (BaseQuery[E]) Exec added in v0.15.0 

func (b BaseQuery[E]) Exec(ctx context.Context, exec Executor) (sql.Result, error)

func (BaseQuery[E]) GetLoaders 

func (b BaseQuery[E]) GetLoaders() []Loader

func (BaseQuery[E]) GetMapperMods 

func (b BaseQuery[E]) GetMapperMods() []scan.MapperMod

func (BaseQuery[E]) MustBuild 

func (q BaseQuery[E]) MustBuild() (string, []any)

MustBuild builds the query and panics on error useful for initializing queries that need to be reused

func (BaseQuery[E]) MustBuildN 

func (q BaseQuery[E]) MustBuildN(start int) (string, []any)

MustBuildN builds the query and panics on error start numbers the arguments from a different point

func (BaseQuery[E]) WriteQuery 

func (b BaseQuery[E]) WriteQuery(w io.Writer, start int) ([]any, error)

func (BaseQuery[E]) WriteSQL 

func (b BaseQuery[E]) WriteSQL(w io.Writer, _ Dialect, start int) ([]any, error)

Satisfies the Expression interface, but uses its own dialect instead of the dialect passed to it

type Conn 

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

Conn is similar to *sql.Conn but implements [Queryer]

func NewConn 

func NewConn(conn *sql.Conn) Conn

NewConn wraps an *sql.Conn and returns a type that implements [Queryer] This is useful when an existing *sql.Conn is used in other places in the codebase

func (Conn) BeginTx added in v0.13.0 

func (c Conn) BeginTx(ctx context.Context, opts *sql.TxOptions) (Tx, error)

BeginTx is similar to *sql.Conn.BeginTx, but return a transaction that implements [Queryer]

func (Conn) Close added in v0.13.0 

func (c Conn) Close() error

Close works the same as *sql.Conn.Close

func (Conn) ExecContext 

func (q Conn) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

ExecContext executes a query without returning any rows. The args are for any placeholder parameters in the query.

func (Conn) PingContext added in v0.13.0 

func (c Conn) PingContext(ctx context.Context) error

PingContext verifies a connection to the database is still alive, establishing a connection if necessary.

func (Conn) PrepareContext 

func (c Conn) PrepareContext(ctx context.Context, query string) (Statement, error)

PrepareContext creates a prepared statement for later queries or executions

type DB 

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

DB is similar to *sql.DB but implement [Queryer]

func NewDB 

func NewDB(db *sql.DB) DB

NewDB wraps an *sql.DB and returns a type that implements [Queryer] but still retains the expected methods used by *sql.DB This is useful when an existing *sql.DB is used in other places in the codebase

func Open 

func Open(driverName string, dataSource string) (DB, error)

Open works just like sql.Open, but converts the returned *sql.DB to DB

func OpenDB 

func OpenDB(c driver.Connector) DB

OpenDB works just like sql.OpenDB, but converts the returned *sql.DB to DB

func (DB) BeginTx 

func (d DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (Tx, error)

BeginTx is similar to *sql.DB.BeginTx, but return a transaction that implements [Queryer]

func (DB) Close 

func (d DB) Close() error

Close works the same as *sql.DB.Close

func (DB) ExecContext 

func (q DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

ExecContext executes a query without returning any rows. The args are for any placeholder parameters in the query.

func (DB) PingContext added in v0.13.0 

func (d DB) PingContext(ctx context.Context) error

PingContext verifies a connection to the database is still alive, establishing a connection if necessary.

func (DB) PrepareContext 

func (c DB) PrepareContext(ctx context.Context, query string) (Statement, error)

PrepareContext creates a prepared statement for later queries or executions

type DebugPrinter added in v0.20.0 

type DebugPrinter interface {
	PrintQuery(query string, args ...any)
}

DebugPrinter is used to print queries and arguments

type Dialect 

type Dialect interface {
	// WriteArg should write an argument placeholder to the writer with the given index
	WriteArg(w io.Writer, position int)

	// WriteQuoted writes the given string to the writer surrounded by the appropriate
	// quotes for the dialect
	WriteQuoted(w io.Writer, s string)
}

Dialect provides expressions with methods to write parts of the query

type DialectWithNamed 

type DialectWithNamed interface {
	Dialect
	// WriteNamedArg should write an argument placeholder to the writer with the given name
	WriteNamedArg(w io.Writer, name string)
}

DialectWithNamed is a Dialect with the additional ability to WriteNamedArgs

type ExecOption added in v0.2.3 

type ExecOption[T any] func(*ExecSettings[T])

type ExecSettings added in v0.2.3 

type ExecSettings[T any] struct {
	AfterSelect func(ctx context.Context, retrieved []T) error
}

type Executor added in v0.3.1 

type Executor interface {
	scan.Queryer
	ExecContext(context.Context, string, ...any) (sql.Result, error)
}

func Debug added in v0.20.0 

func Debug(exec Executor) Executor

Debug wraps an Executor and prints the queries and args to os.Stdout

func DebugToPrinter added in v0.20.0 

func DebugToPrinter(exec Executor, w DebugPrinter) Executor

DebugToPrinter wraps an existing Executor and writes all queries and args to the given DebugPrinter if w is nil, it fallsback to writing to os.Stdout

func DebugToWriter added in v0.20.0 

func DebugToWriter(exec Executor, w io.Writer) Executor

DebugToWriter wraps an existing Executor and writes all queries and args to the given io.Writer if w is nil, it fallsback to os.Stdout

type Expression 

type Expression interface {
	// Writes the textual representation of the expression to the writer
	// using the given dialect.
	// start is the beginning index of the args if it needs to write any
	WriteSQL(w io.Writer, d Dialect, start int) (args []any, err error)
}

Expression represents a section of a query

type ExpressionFunc 

type ExpressionFunc func(w io.Writer, d Dialect, start int) ([]any, error)

func (ExpressionFunc) WriteSQL 

func (e ExpressionFunc) WriteSQL(w io.Writer, d Dialect, start int) ([]any, error)

type Load added in v0.13.0 

type Load[Q any] struct {
	// contains filtered or unexported fields
}

Load is an embeddable struct that enables Preloading and AfterLoading

func (*Load[Q]) AppendLoader added in v0.13.0 

func (l *Load[Q]) AppendLoader(f ...Loader)

AppendLoader add to the query's loaders

func (*Load[Q]) AppendMapperMod added in v0.13.0 

func (l *Load[Q]) AppendMapperMod(f scan.MapperMod)

AppendMapperMod adds to the query's mapper mods

func (*Load[Q]) GetLoadContext added in v0.20.0 

func (l *Load[Q]) GetLoadContext() context.Context

GetLoadContext

func (*Load[Q]) GetLoaders added in v0.13.0 

func (l *Load[Q]) GetLoaders() []Loader

GetLoaders implements the Loadable interface

func (*Load[Q]) GetMapperMods added in v0.13.0 

func (l *Load[Q]) GetMapperMods() []scan.MapperMod

GetMapperMods implements the MapperModder interface

func (*Load[Q]) SetLoadContext added in v0.20.0 

func (l *Load[Q]) SetLoadContext(ctx context.Context)

SetLoadContext

type Loadable 

type Loadable interface {
	GetLoaders() []Loader
}

Loadable is an object that has loaders if a query implements this interface, the loaders are called after executing the query

type Loader added in v0.13.0 

type Loader interface {
	Load(ctx context.Context, exec Executor, retrieved any) error
}

Loader is an object that is called after the main query is performed when called from Exec, retrieved is nil when called from One, retrieved is the retrieved object when called from All, retrieved is a slice retrieved objects this is used for loading relationships

type MapperModder 

type MapperModder interface {
	GetMapperMods() []scan.MapperMod
}

type Mod 

type Mod[T any] interface {
	Apply(T)
}

type Preparer added in v0.13.0 

type Preparer interface {
	Executor
	PrepareContext(ctx context.Context, query string) (Statement, error)
}

type Query 

type Query interface {
	// It should satisfy the Expression interface so that it can be used
	// in places such as a sub-select
	// However, it is allowed for a query to use its own dialect and not
	// the dialect given to it
	Expression
	// start is the index of the args, usually 1.
	// it is present to allow re-indexing in cases of a subquery
	// The method returns the value of any args placed
	WriteQuery(w io.Writer, start int) (args []any, err error)
}

type QueryStmt added in v0.13.0 

type QueryStmt[T any, Ts ~[]T] struct {
	Stmt
	// contains filtered or unexported fields
}

func PrepareQuery added in v0.13.0 

func PrepareQuery[T any](ctx context.Context, exec Preparer, q Query, m scan.Mapper[T], opts ...ExecOption[T]) (QueryStmt[T, []T], error)

func PrepareQueryx added in v0.13.0 

func PrepareQueryx[T any, Ts ~[]T](ctx context.Context, exec Preparer, q Query, m scan.Mapper[T], opts ...ExecOption[T]) (QueryStmt[T, Ts], error)

func (QueryStmt[T, Ts]) All added in v0.13.0 

func (s QueryStmt[T, Ts]) All(ctx context.Context, args ...any) (Ts, error)

func (QueryStmt[T, Ts]) Cursor added in v0.15.0 

func (s QueryStmt[T, Ts]) Cursor(ctx context.Context, args ...any) (scan.ICursor[T], error)

func (QueryStmt[T, Ts]) One added in v0.13.0 

func (s QueryStmt[T, Ts]) One(ctx context.Context, args ...any) (T, error)

type Statement added in v0.13.0 

type Statement interface {
	ExecContext(ctx context.Context, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, args ...any) (scan.Rows, error)
}

type StdInterface 

type StdInterface interface {
	stdscan.Queryer
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
}

StdInterface is an interface that *sql.DB, *sql.Tx and *sql.Conn satisfy

type Stmt added in v0.13.0 

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

Stmt is similar to *sql.Stmt but implements [Queryer]

func Prepare added in v0.13.0 

func Prepare(ctx context.Context, exec Preparer, q Query) (Stmt, error)

NewStmt wraps an *sql.Stmt and returns a type that implements [Queryer] but still retains the expected methods used by *sql.Stmt This is useful when an existing *sql.Stmt is used in other places in the codebase

func (Stmt) Exec added in v0.13.0 

func (s Stmt) Exec(ctx context.Context, args ...any) (sql.Result, error)

Exec executes a query without returning any rows. The args are for any placeholder parameters in the query.

type Tx 

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

Tx is similar to *sql.Tx but implements [Queryer]

func NewTx 

func NewTx(tx *sql.Tx) Tx

NewTx wraps an *sql.Tx and returns a type that implements [Queryer] but still retains the expected methods used by *sql.Tx This is useful when an existing *sql.Tx is used in other places in the codebase

func (Tx) Commit 

func (t Tx) Commit() error

Commit works the same as *sql.Tx.Commit

func (Tx) ExecContext 

func (q Tx) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

ExecContext executes a query without returning any rows. The args are for any placeholder parameters in the query.

func (Tx) PrepareContext 

func (c Tx) PrepareContext(ctx context.Context, query string) (Statement, error)

PrepareContext creates a prepared statement for later queries or executions

func (Tx) Rollback 

func (t Tx) Rollback() error

Rollback works the same as *sql.Tx.Rollback

Source Files

View all Source files

Directories

Path Synopsis
dialect
mssql
mysql
mysql/dialect
mysql/dm
mysql/im
mysql/sm
mysql/um
psql
psql/dialect
psql/dm
psql/im
psql/sm
psql/um
sqlite
sqlite/dialect
sqlite/dm
sqlite/im
sqlite/sm
sqlite/um
gen
bobgen-atlas
bobgen-atlas/driver
bobgen-helpers
bobgen-mysql
bobgen-mysql/driver
bobgen-prisma
bobgen-prisma/driver
bobgen-psql
bobgen-psql/driver
bobgen-sqlite
bobgen-sqlite/driver
drivers
Package drivers talks to various database backends and retrieves table, column, type, and foreign key information
 Package drivers talks to various database backends and retrieves table, column, type, and foreign key information
importers
Package importers helps with dynamic imports for templating
 Package importers helps with dynamic imports for templating
parray

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.