dbx

package
v0.56.0 Latest Latest
Warning

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

 Go to latest Published: Feb 23, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Question is a PlaceholderFormat instance that leaves placeholders as
	// question marks.
	Question = questionFormat{}

	// Dollar is a PlaceholderFormat instance that replaces placeholders with
	// dollar-prefixed positional placeholders (e.g. $1, $2, $3).
	Dollar = dollarFormat{}

	// Colon is a PlaceholderFormat instance that replaces placeholders with
	// colon-prefixed positional placeholders (e.g. :1, :2, :3).
	Colon = colonFormat{}

	// AtP is a PlaceholderFormat instance that replaces placeholders with
	// "@p"-prefixed positional placeholders (e.g. @p1, @p2, @p3).
	AtP = atpFormat{}
)
View Source 
var ErrNotFound = errors.New("dbx: not found")

ErrNotFound is returned by GetBuilder.Exec when no row matches.

Functions

func Alias 

func Alias(expr Sqlizer, alias string) aliasExpr

Alias allows to define alias for column in SelectBuilder. Useful when column is defined as complex expression like IF or CASE Ex: 

.Column(Alias(caseStmt, "case_column"))

func ConcatExpr 

func ConcatExpr(parts ...any) concatExpr

ConcatExpr builds an expression by concatenating strings and other expressions.

Ex: 

name_expr := Expr("CONCAT(?, ' ', ?)", firstName, lastName)
ConcatExpr("COALESCE(full_name,", name_expr, ")")

func NewClient 

func NewClient[T any](ctx context.Context, config cfg.Config, logger log.Logger, clientName string, table string) (*client[T], error)

NewClient creates a new dbx client. It takes a context, a config, a logger, a client name and a table name as arguments. The client name is the name of the database client to use, as configured in your application's configuration file. The table name is the name of the database table. It returns a new client or an error if the client could not be created.

func NewClientWithInterfaces 

func NewClientWithInterfaces[T any](dbClient db.Client, table string, placeholderFormat PlaceholderFormat) (*client[T], error)

NewClientWithInterfaces creates a new dbx client with a given database client. It takes a database client and a table name as arguments. It returns a new client.

func Placeholders 

func Placeholders(count int) string

Placeholders returns a string with count ? placeholders joined with commas.

Types

type And 

type And conj

And conjunction Sqlizers

func (And) ToSql 

func (a And) ToSql() (sql string, args []any, err error)

type Client 

type Client[T any] interface {
	// Delete creates a new DELETE query builder.
	//
	//	_, err := client.Delete().Where(dbx.Eq{"id": 1}).Exec(ctx)
	Delete() DeleteBuilder[T]
	// Insert creates a new INSERT query builder.
	//
	//	_, err := client.Insert(YourModel{Id: 1, Name: "test"}).Exec(ctx)
	Insert(val ...T) InsertBuilder[T]
	// Replace creates a new REPLACE query builder.
	//
	//	_, err := client.Replace(YourModel{Id: 1, Name: "test"}).Exec(ctx)
	Replace(val ...T) InsertBuilder[T]
	// Select creates a new SELECT query builder.
	//
	//	results, err := client.Select().Where(dbx.Eq{"id": 1}).Exec(ctx)
	Select() SelectBuilder[T]
	// Update creates a new UPDATE query builder.
	//
	//	_, err := client.Update(map[string]any{"name": "new_name"}).Where(dbx.Eq{"id": 1}).Exec(ctx)
	Update(updateMaps ...any) UpdateBuilder[T]
	// Get creates a new GET query builder.
	//
	//	result, err := client.Get().Where(dbx.Eq{"id": 1}).Exec(ctx)
	//	- Returns a single element if found.
	//	- Returns ErrNotFound if no row matches.
	//	- Returns an error if more than one row is found.
	Get() GetBuilder[T]
}

Client is the main entry point to the package. It is used to create query builders.

type DeleteBuilder 

type DeleteBuilder[T any] builder.Builder

DeleteBuilder[T] builds SQL DELETE statements.

func (DeleteBuilder[T]) Exec 

func (b DeleteBuilder[T]) Exec(ctx context.Context) (sql.Result, error)

Exec builds and Execs the query with the Runner set by RunWith.

func (DeleteBuilder[T]) Limit 

func (b DeleteBuilder[T]) Limit(limit uint64) DeleteBuilder[T]

Limit sets a LIMIT clause on the query.

func (DeleteBuilder[T]) Options 

func (b DeleteBuilder[T]) Options(options ...string) DeleteBuilder[T]

Options adds keyword options before the INTO clause of the query.

func (DeleteBuilder[T]) OrderBy 

func (b DeleteBuilder[T]) OrderBy(orderBys ...string) DeleteBuilder[T]

OrderBy adds ORDER BY expressions to the query.

func (DeleteBuilder[T]) Where 

func (b DeleteBuilder[T]) Where(pred any, args ...any) DeleteBuilder[T]

Where adds WHERE expressions to the query.

See SelectBuilder.Where for more information.

type Eq 

type Eq map[string]any

Eq is syntactic sugar for use with Where/Having/Set methods.

func (Eq) ToSql 

func (eq Eq) ToSql() (sql string, args []any, err error)

type GetBuilder added in v0.54.2 

type GetBuilder[T any] builder.Builder

GetBuilder[T] builds SELECT ... LIMIT 2 statements which return one element.

func (GetBuilder[T]) Column added in v0.54.2 

func (b GetBuilder[T]) Column(column any, args ...any) GetBuilder[T]

Column adds a result column to the query. See SelectBuilder.Column for details.

func (GetBuilder[T]) CrossJoin added in v0.54.2 

func (b GetBuilder[T]) CrossJoin(join string, rest ...any) GetBuilder[T]

CrossJoin adds a CROSS JOIN clause to the query.

func (GetBuilder[T]) Exec added in v0.54.2 

func (b GetBuilder[T]) Exec(ctx context.Context) (T, error)

func (GetBuilder[T]) GroupBy added in v0.54.2 

func (b GetBuilder[T]) GroupBy(groupBys ...string) GetBuilder[T]

GroupBy adds GROUP BY expressions to the query.

func (GetBuilder[T]) Having added in v0.54.2 

func (b GetBuilder[T]) Having(pred any, rest ...any) GetBuilder[T]

Having adds an expression to the HAVING clause of the query.

See SelectBuilder.Where for details.

func (GetBuilder[T]) InnerJoin added in v0.54.2 

func (b GetBuilder[T]) InnerJoin(join string, rest ...any) GetBuilder[T]

InnerJoin adds an INNER JOIN clause to the query.

func (GetBuilder[T]) Join added in v0.54.2 

func (b GetBuilder[T]) Join(join string, rest ...any) GetBuilder[T]

Join adds a JOIN clause to the query.

func (GetBuilder[T]) JoinClause added in v0.54.2 

func (b GetBuilder[T]) JoinClause(pred any, args ...any) GetBuilder[T]

JoinClause adds a join clause to the query.

func (GetBuilder[T]) LeftJoin added in v0.54.2 

func (b GetBuilder[T]) LeftJoin(join string, rest ...any) GetBuilder[T]

LeftJoin adds a LEFT JOIN clause to the query.

func (GetBuilder[T]) Options added in v0.54.2 

func (b GetBuilder[T]) Options(options ...string) GetBuilder[T]

Options adds select options to the query (e.g. SQL_NO_CACHE, HIGH_PRIORITY).

func (GetBuilder[T]) OrderBy added in v0.54.2 

func (b GetBuilder[T]) OrderBy(orderBys ...string) GetBuilder[T]

OrderBy adds ORDER BY expressions to the query.

func (GetBuilder[T]) OrderByClause added in v0.54.2 

func (b GetBuilder[T]) OrderByClause(pred any, args ...any) GetBuilder[T]

OrderByClause adds ORDER BY clause to the query.

func (GetBuilder[T]) RightJoin added in v0.54.2 

func (b GetBuilder[T]) RightJoin(join string, rest ...any) GetBuilder[T]

RightJoin adds a RIGHT JOIN clause to the query.

func (GetBuilder[T]) Where added in v0.54.2 

func (b GetBuilder[T]) Where(pred any, args ...any) GetBuilder[T]

Where adds an expression to the WHERE clause of the query.

See SelectBuilder.Where for the supported predicate types (string, Eq/map, struct T, etc.).

type Gt 

type Gt Lt

Gt is syntactic sugar for use with Where/Having/Set methods. Ex: 

.Where(Gt{"id": 1}) == "id > 1"

func (Gt) ToSql 

func (gt Gt) ToSql() (sql string, args []any, err error)

type GtOrEq 

type GtOrEq Lt

GtOrEq is syntactic sugar for use with Where/Having/Set methods. Ex: 

.Where(GtOrEq{"id": 1}) == "id >= 1"

func (GtOrEq) ToSql 

func (gtOrEq GtOrEq) ToSql() (sql string, args []any, err error)

type ILike 

type ILike Like

ILike is syntactic sugar for use with ILIKE conditions. Ex: 

.Where(ILike{"name": "sq%"})

func (ILike) ToSql 

func (ilk ILike) ToSql() (sql string, args []any, err error)

type InsertBuilder 

type InsertBuilder[T any] builder.Builder

InsertBuilder builds SQL INSERT statements.

func (InsertBuilder[T]) Exec 

func (b InsertBuilder[T]) Exec(ctx context.Context) (sql.Result, error)

func (InsertBuilder[T]) Options 

func (b InsertBuilder[T]) Options(options ...string) InsertBuilder[T]

Options adds keyword options before the INTO clause of the query.

func (InsertBuilder[T]) Suffix 

func (b InsertBuilder[T]) Suffix(sql string, args ...any) InsertBuilder[T]

Suffix adds an expression to the end of the query

func (InsertBuilder[T]) SuffixExpr 

func (b InsertBuilder[T]) SuffixExpr(expr Sqlizer) InsertBuilder[T]

SuffixExpr adds an expression to the end of the query

type Like 

type Like map[string]any

Like is syntactic sugar for use with LIKE conditions. Ex: 

.Where(Like{"name": "%irrel"})

func (Like) ToSql 

func (lk Like) ToSql() (sql string, args []any, err error)

type Lt 

type Lt map[string]any

Lt is syntactic sugar for use with Where/Having/Set methods. Ex: 

.Where(Lt{"id": 1})

func (Lt) ToSql 

func (lt Lt) ToSql() (sql string, args []any, err error)

type LtOrEq 

type LtOrEq Lt

LtOrEq is syntactic sugar for use with Where/Having/Set methods. Ex: 

.Where(LtOrEq{"id": 1}) == "id <= 1"

func (LtOrEq) ToSql 

func (ltOrEq LtOrEq) ToSql() (sql string, args []any, err error)

type NotEq 

type NotEq Eq

NotEq is syntactic sugar for use with Where/Having/Set methods. Ex: 

.Where(NotEq{"id": 1}) == "id <> 1"

func (NotEq) ToSql 

func (neq NotEq) ToSql() (sql string, args []any, err error)

type NotILike 

type NotILike Like

NotILike is syntactic sugar for use with ILIKE conditions. Ex: 

.Where(NotILike{"name": "sq%"})

func (NotILike) ToSql 

func (nilk NotILike) ToSql() (sql string, args []any, err error)

type NotLike 

type NotLike Like

NotLike is syntactic sugar for use with LIKE conditions. Ex: 

.Where(NotLike{"name": "%irrel"})

func (NotLike) ToSql 

func (nlk NotLike) ToSql() (sql string, args []any, err error)

type Or 

type Or conj

Or conjunction Sqlizers

func (Or) ToSql 

func (o Or) ToSql() (sql string, args []any, err error)

type PlaceholderFormat 

type PlaceholderFormat interface {
	ReplacePlaceholders(sql string) (string, error)
}

PlaceholderFormat is the interface that wraps the ReplacePlaceholders method.

ReplacePlaceholders takes a SQL statement and replaces each question mark placeholder with a (possibly different) SQL placeholder.

type SelectBuilder 

type SelectBuilder[T any] builder.Builder

SelectBuilder[T] builds SQL SELECT statements.

func (SelectBuilder[T]) Column 

func (b SelectBuilder[T]) Column(column any, args ...any) SelectBuilder[T]

Column adds a result column to the query. Unlike Columns, Column accepts args which will be bound to placeholders in the columns string, for example: 

Column("IF(col IN ("+squirrel.Placeholders(3)+"), 1, 0) as col", 1, 2, 3)

The first call to Column() will clear any default columns and replace them with the specified custom columns. Subsequent calls will append.

func (SelectBuilder[T]) CrossJoin 

func (b SelectBuilder[T]) CrossJoin(join string, rest ...any) SelectBuilder[T]

CrossJoin adds a CROSS JOIN clause to the query.

func (SelectBuilder[T]) Distinct 

func (b SelectBuilder[T]) Distinct() SelectBuilder[T]

Distinct adds a DISTINCT clause to the query.

func (SelectBuilder[T]) Exec 

func (b SelectBuilder[T]) Exec(ctx context.Context) ([]T, error)

func (SelectBuilder[T]) GroupBy 

func (b SelectBuilder[T]) GroupBy(groupBys ...string) SelectBuilder[T]

GroupBy adds GROUP BY expressions to the query.

func (SelectBuilder[T]) Having 

func (b SelectBuilder[T]) Having(pred any, rest ...any) SelectBuilder[T]

Having adds an expression to the HAVING clause of the query.

See Where.

func (SelectBuilder[T]) InnerJoin 

func (b SelectBuilder[T]) InnerJoin(join string, rest ...any) SelectBuilder[T]

InnerJoin adds a INNER JOIN clause to the query.

func (SelectBuilder[T]) Join 

func (b SelectBuilder[T]) Join(join string, rest ...any) SelectBuilder[T]

Join adds a JOIN clause to the query.

func (SelectBuilder[T]) JoinClause 

func (b SelectBuilder[T]) JoinClause(pred any, args ...any) SelectBuilder[T]

JoinClause adds a join clause to the query.

func (SelectBuilder[T]) LeftJoin 

func (b SelectBuilder[T]) LeftJoin(join string, rest ...any) SelectBuilder[T]

LeftJoin adds a LEFT JOIN clause to the query.

func (SelectBuilder[T]) Limit 

func (b SelectBuilder[T]) Limit(limit uint64) SelectBuilder[T]

Limit sets a LIMIT clause on the query.

func (SelectBuilder[T]) Offset 

func (b SelectBuilder[T]) Offset(offset uint64) SelectBuilder[T]

Offset sets a OFFSET clause on the query.

func (SelectBuilder[T]) Options 

func (b SelectBuilder[T]) Options(options ...string) SelectBuilder[T]

Options adds select option to the query

func (SelectBuilder[T]) OrderBy 

func (b SelectBuilder[T]) OrderBy(orderBys ...string) SelectBuilder[T]

OrderBy adds ORDER BY expressions to the query.

func (SelectBuilder[T]) OrderByClause 

func (b SelectBuilder[T]) OrderByClause(pred any, args ...any) SelectBuilder[T]

OrderByClause adds ORDER BY clause to the query.

func (SelectBuilder[T]) RemoveLimit 

func (b SelectBuilder[T]) RemoveLimit() SelectBuilder[T]

Limit ALL allows to access all records with limit

func (SelectBuilder[T]) RemoveOffset 

func (b SelectBuilder[T]) RemoveOffset() SelectBuilder[T]

RemoveOffset removes OFFSET clause.

func (SelectBuilder[T]) RightJoin 

func (b SelectBuilder[T]) RightJoin(join string, rest ...any) SelectBuilder[T]

RightJoin adds a RIGHT JOIN clause to the query.

func (SelectBuilder[T]) Where 

func (b SelectBuilder[T]) Where(pred any, args ...any) SelectBuilder[T]

Where adds an expression to the WHERE clause of the query.

Expressions are ANDed together in the generated SQL.

Where accepts several types for its pred argument:

nil OR "" - ignored.

string - SQL expression. If the expression has SQL placeholders then a set of arguments must be passed as well, one for each placeholder.

map[string]any OR Eq - map of SQL expressions to values. Each key is transformed into an expression like "<key> = ?", with the corresponding value bound to the placeholder. If the value is nil, the expression will be "<key> IS NULL". If the value is an array or slice, the expression will be "<key> IN (?,?,...)", with one placeholder for each item in the value. These expressions are ANDed together.

T - a struct of type T The struct will get transformed into a map. Keys with zero values will be ignored. The resulting map will be passed to Eq, which results in a handling like with map[string]any

Where will panic if pred isn't any of the above types.

type Sqlizer 

type Sqlizer interface {
	ToSql() (string, []any, error)
}

func Expr 

func Expr(sql string, args ...any) Sqlizer

Expr builds an expression from a SQL fragment and arguments.

Ex: 

Expr("FROM_UNIXTIME(?)", t)

type UpdateBuilder 

type UpdateBuilder[T any] builder.Builder

UpdateBuilder[T] builds SQL UPDATE statements.

func (UpdateBuilder[T]) Exec 

func (b UpdateBuilder[T]) Exec(ctx context.Context) (sql.Result, error)

func (UpdateBuilder[T]) Limit 

func (b UpdateBuilder[T]) Limit(limit uint64) UpdateBuilder[T]

Limit sets a LIMIT clause on the query.

func (UpdateBuilder[T]) Options 

func (b UpdateBuilder[T]) Options(options ...string) UpdateBuilder[T]

Set adds SET clauses to the query.

func (UpdateBuilder[T]) OrderBy 

func (b UpdateBuilder[T]) OrderBy(orderBys ...string) UpdateBuilder[T]

OrderBy adds ORDER BY expressions to the query.

func (UpdateBuilder[T]) Set 

func (b UpdateBuilder[T]) Set(column string, value any) UpdateBuilder[T]

Set adds SET clauses to the query.

func (UpdateBuilder[T]) SetMap 

func (b UpdateBuilder[T]) SetMap(clauses map[string]any) UpdateBuilder[T]

SetMap is a convenience method which calls .Set for each key/value pair in clauses.

func (UpdateBuilder[T]) Where 

func (b UpdateBuilder[T]) Where(pred any, args ...any) UpdateBuilder[T]

Where adds WHERE expressions to the query.

See SelectBuilder.Where for more information.

Source Files

View all Source files

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.