tql

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) ([]T, error)
• func QueryFirst[T any](ctx context.Context, q Querier, query string, params ...any) (T, error)
• func QueryFirstOrDefault[T any](ctx context.Context, q Querier, def T, query string, params ...any) (T, 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) (T, error)
• func SetActiveDriver(driver string) error
• type Executor
• type Querier

Variables

var ErrMultipleResults = errors.New("sql: found multiple results expected single")

Functions

func Exec

func Exec(ctx context.Context, e Executor, query string, params ...any) (sql.Result, error)

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) ([]T, 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) (T, error)

QueryFirst Queries the table and returns the first result. If the query returns no results, the function returns sql.ErrNoRows.

func QueryFirstOrDefault

func QueryFirstOrDefault[T any](ctx context.Context, q Querier, def T, query string, params ...any) (T, error)

func QuerySingle

func QuerySingle[T any](ctx context.Context, q Querier, query string, params ...any) (T, error)

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) (T, 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

func SetActiveDriver(driver string) error

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.

Types

type Executor

type Executor interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

type Querier

type Querier interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}