README
¶
tql
Simple convenience functions (with generics) around database/sql.
Designed to be used with existing sql.DB, sql.Tx types.
Marshals rows into structs using the db tag. For the struct field to be marshalled, it needs to contain the db tag.
Example usage:
type Foo struct {
ID string `db:"id"`
Value string `db:"value"`
}
const query = "SELECT * FROM foo WHERE value = $1;"
foos, err := tql.Query[Foo](context.Background(), db, query, "bar")
if err != nil {
// error handling
}
// do stuff with foos
Supports named parameters:
type Foo struct {
ID string `db:"id"`
Value string `db:"value"`
}
foo := Foo {
ID: "foo",
Value: "bar",
}
const stmt = "INSERT INTO foo (id, value) VALUES (:id, :value);"
result, err := tql.Exec(context.Background(), db, stmt, foo)
if err != nil {
// error handling
}
// do stuff with result
API
QuerySingle[T any](ctx context.Context, q Querier, query string, params ...any) (T, error)
QuerySingleOrDefault[T any](ctx context.Context, q Querier, def T, query string, params ...any) (T, error)
QueryFirst[T any](ctx context.Context, q Querier, query string, params ...any) (T, error)
QueryFirstOrDefault[T any](ctx context.Context, q Querier, def T, query string, params ...any) (T, error)
Query[T any](ctx context.Context, q Querier, query string, params ...any) ([]T, error)
Exec(ctx context.Context, e Executor, query string, params ...any) (sql.Result, error)
Interfaces used
type Executor interface {
ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}
type Querier interface {
QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}
Documentation
¶
Index ¶
- Variables
- func Exec(ctx context.Context, e Executor, query string, params ...any) (sql.Result, error)
- func Query[T any](ctx context.Context, q Querier, query string, params ...any) (result []T, err error)
- func QueryFirst[T any](ctx context.Context, q Querier, query string, params ...any) (result T, err error)
- func QueryFirstOrDefault[T any](ctx context.Context, q Querier, def T, query string, params ...any) (result T, err error)
- func QuerySingle[T any](ctx context.Context, q Querier, query string, params ...any) (T, error)
- func QuerySingleOrDefault[T any](ctx context.Context, q Querier, def T, query string, params ...any) (result T, err error)
- func SetActiveDriver(driver string) error
- type Executor
- type Querier
Constants ¶
This section is empty.
Variables ¶
var ErrMultipleResults = errors.New("sql: found multiple results expected single")
Functions ¶
func Exec ¶
Exec Executes a statement and returns sql.Result.
The statement can be parameterised using, either, the positional parameters (e.g. $1, $2 or ?, ?, depending on the driver) or using named parameters (such as :parameter1, :parameter2).
When using named parameters with structs as params, the names in the query *must* be specified as the db tag in the struct name. When using a map, the keys will be the names.
func Query ¶
func Query[T any](ctx context.Context, q Querier, query string, params ...any) (result []T, err error)
Query Queries the database and returns all the results as a slice. If the query returns no results, an empty slice of type T is returned. This matches the sql.QueryContext function from database/sql.
func QueryFirst ¶
func QueryFirst[T any](ctx context.Context, q Querier, query string, params ...any) (result T, err error)
QueryFirst Queries the table and returns the first result. If the query returns no results, the function returns sql.ErrNoRows.
func QueryFirstOrDefault ¶
func QuerySingle ¶
QuerySingle Queries the table to return one result. A variant of QueryFirst that expects only a single result.
If the query returns more than one result, this function returns tql.ErrMultipleResults.
If the query returns no results, this function return sql.ErrNoRows.
If the query returns a single result, this function returns the result.
func QuerySingleOrDefault ¶
func QuerySingleOrDefault[T any](ctx context.Context, q Querier, def T, query string, params ...any) (result T, err error)
QuerySingleOrDefault A variant of QueryFirstOrDefault that expects only a single result.
If the query returns more than one result, this function returns tql.ErrMultipleResults.
If the query returns no results, this function return the provided default.
If the query returns a single result, this function returns the result.
func SetActiveDriver ¶
SetActiveDriver
*Do not use this!*
Sets which driver to use to know which parameter syntax to use. Don't use this, it's global state, it's not safe for concurrent use, and it is bad. It is just here, so I can choose which driver I want to use in the tests for tql, and the tests are in a separate module so this is public.
Source Files
Directories