README
¶
Bob: Go SQL Access Toolkit
Links
About
Bob is a set of Go packages and tools to work with SQL databases.
Bob's philosophy centres around the following:
- Correctness: Things should work correctly. Follow specifications as closely as possible.
- Convenience (not magic): Bob provides convenient ways to perform actions, it does not add unexplainable magic, or needless abstraction.
- 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.
- Query Builder
- SQL Executor for convenient scanning of results
- Models for convenient database queries
- 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
Documentation
¶
Index ¶
- Variables
- func All[T any](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], ...) ([]T, error)
- func Allx[T any, Ts ~[]T](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], ...) (Ts, error)
- func Build(q Query) (string, []any, error)
- func BuildN(q Query, start int) (string, []any, error)
- func Cursor[T any](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], ...) (scan.ICursor[T], error)
- func Exec(ctx context.Context, exec Executor, q Query) (sql.Result, error)
- func Express(w io.Writer, d Dialect, start int, e any) ([]any, error)
- func ExpressIf(w io.Writer, d Dialect, start int, e any, cond bool, prefix, suffix string) ([]any, error)
- func ExpressSlice[T any](w io.Writer, d Dialect, start int, expressions []T, prefix, sep, suffix string) ([]any, error)
- func MustBuild(q Query) (string, []any)
- func MustBuildN(q Query, start int) (string, []any)
- func New[T StdInterface](wrapped T) common[T]
- func NewQueryer[T stdscan.Queryer](wrapped T) scan.Queryer
- func One[T any](ctx context.Context, exec Executor, q Query, m scan.Mapper[T], ...) (T, error)
- type BaseQuery
- func (b BaseQuery[E]) Apply(mods ...Mod[E])
- func (q BaseQuery[E]) Build() (string, []any, error)
- func (q BaseQuery[E]) BuildN(start int) (string, []any, error)
- func (q BaseQuery[E]) Cache() (BaseQuery[*cached], error)
- func (q BaseQuery[E]) CacheN(start int) (BaseQuery[*cached], error)
- func (b BaseQuery[E]) Clone() BaseQuery[E]
- func (b BaseQuery[E]) Exec(ctx context.Context, exec Executor) (sql.Result, error)
- func (b BaseQuery[E]) GetLoaders() []Loader
- func (b BaseQuery[E]) GetMapperMods() []scan.MapperMod
- func (q BaseQuery[E]) MustBuild() (string, []any)
- func (q BaseQuery[E]) MustBuildN(start int) (string, []any)
- func (b BaseQuery[E]) WriteQuery(w io.Writer, start int) ([]any, error)
- func (b BaseQuery[E]) WriteSQL(w io.Writer, _ Dialect, start int) ([]any, error)
- type Conn
- func (c Conn) BeginTx(ctx context.Context, opts *sql.TxOptions) (Tx, error)
- func (c Conn) Close() error
- func (q Conn) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
- func (c Conn) PingContext(ctx context.Context) error
- func (c Conn) PrepareContext(ctx context.Context, query string) (Statement, error)
- type DB
- func (d DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (Tx, error)
- func (d DB) Close() error
- func (q DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
- func (d DB) PingContext(ctx context.Context) error
- func (c DB) PrepareContext(ctx context.Context, query string) (Statement, error)
- type DebugPrinter
- type Dialect
- type DialectWithNamed
- type ExecOption
- type ExecSettings
- type Executor
- type Expression
- type ExpressionFunc
- type Load
- type Loadable
- type Loader
- type MapperModder
- type Mod
- type Preparer
- type Query
- type QueryStmt
- type Statement
- type StdInterface
- type Stmt
- type Tx
- type WrongStartError
Constants ¶
This section is empty.
Variables ¶
var ErrNoNamedArgs = errors.New("Dialect does not support named arguments")
Functions ¶
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 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 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 ¶
MustBuild builds a query and panics on error useful for initializing queries that need to be reused
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 ¶
NewQueryer wraps an stdscan.Queryer and makes it a scan.Queryer
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]) GetLoaders ¶
func (BaseQuery[E]) GetMapperMods ¶
func (BaseQuery[E]) MustBuild ¶
MustBuild builds the query and panics on error useful for initializing queries that need to be reused
func (BaseQuery[E]) MustBuildN ¶
MustBuildN builds the query and panics on error start numbers the arguments from a different point
func (BaseQuery[E]) WriteQuery ¶
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is similar to *sql.Conn but implements [Queryer]
func NewConn ¶
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
BeginTx is similar to *sql.Conn.BeginTx, but return a transaction that implements [Queryer]
func (Conn) Close ¶ added in v0.13.0
Close works the same as *sql.Conn.Close
func (Conn) ExecContext ¶
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
PingContext verifies a connection to the database is still alive, establishing a connection if necessary.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is similar to *sql.DB but implement [Queryer]
func NewDB ¶
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 OpenDB ¶
OpenDB works just like sql.OpenDB, but converts the returned *sql.DB to DB
func (DB) BeginTx ¶
BeginTx is similar to *sql.DB.BeginTx, but return a transaction that implements [Queryer]
func (DB) ExecContext ¶
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
PingContext verifies a connection to the database is still alive, establishing a connection if necessary.
type DebugPrinter ¶ added in v0.20.0
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 Executor ¶ added in v0.3.1
type Executor interface {
scan.Queryer
ExecContext(context.Context, string, ...any) (sql.Result, error)
}
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
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 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
AppendLoader add to the query's loaders
func (*Load[Q]) AppendMapperMod ¶ added in v0.13.0
AppendMapperMod adds to the query's mapper mods
func (*Load[Q]) GetLoadContext ¶ added in v0.20.0
GetLoadContext
func (*Load[Q]) GetLoaders ¶ added in v0.13.0
GetLoaders implements the Loadable interface
func (*Load[Q]) GetMapperMods ¶ added in v0.13.0
GetMapperMods implements the MapperModder interface
func (*Load[Q]) SetLoadContext ¶ added in v0.20.0
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
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 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
func PrepareQuery ¶ added in v0.13.0
func PrepareQueryx ¶ added in v0.13.0
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]
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx is similar to *sql.Tx but implements [Queryer]
func NewTx ¶
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) ExecContext ¶
ExecContext executes a query without returning any rows. The args are for any placeholder parameters in the query.
func (Tx) PrepareContext ¶
PrepareContext creates a prepared statement for later queries or executions
type WrongStartError ¶ added in v0.23.0
func (WrongStartError) Error ¶ added in v0.23.0
func (e WrongStartError) Error() string
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
dialect
|
|
|
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 |