rowmap

README

Rowmap

A Go library to map SQL query results to Go structs.

Basic usage

Install

go get github.com/spearson78/rowmap

Define a struct and a mapper from an sql.Rows to your struct

type TestStruct struct {
	Id  int64
	Col string
}

func testStructMapper(row *sql.Rows) (TestStruct, error) {
	var e TestStruct
	err := row.Scan(&e.Id, &e.Col)
	return e, err
}

Execute queries

entities, err := Query(db,testStructMapper, "SELECT ID,COL FROM TEST WHERE ID IN(?,?) ORDER BY ID DESC", 1, 2)

Documentation

Index

• func Get(err error) (string, bool)
• func Query[E any](db Queryable, mapper MapperFunc[E], sql string, p ...any) ([]E, error)
• func QueryContext[E any](ctx context.Context, db Queryable, mapper MapperFunc[E], sql string, p ...any) ([]E, error)
• func QueryRow[E any](db Queryable, mapper MapperFunc[E], sql string, p ...any) (E, error)
• func QueryRowContext[E any](ctx context.Context, db Queryable, mapper MapperFunc[E], sql string, p ...any) (E, error)
• func With[E any](mapper MapperFunc[E]) func(error) error
• func Wrap[E any](err error, mapper MapperFunc[E]) error
• type MappedStmt
  • func Prepare[E any](db prepare, mapper MapperFunc[E], query string) (*MappedStmt[E], error)
  • func PrepareContext[E any](ctx context.Context, db prepareContext, mapper MapperFunc[E], query string) (*MappedStmt[E], error)
  • func (m *MappedStmt[E]) Close() error
  • func (m *MappedStmt[E]) Query(args ...any) ([]E, error)
  • func (m *MappedStmt[E]) QueryContext(ctx context.Context, args ...any) ([]E, error)
  • func (m *MappedStmt[E]) QueryRow(args ...any) (E, error)
  • func (m *MappedStmt[E]) QueryRowContext(ctx context.Context, args ...any) (E, error)
• type MapperFunc
• type Queryable

Examples

• Query
• QueryContext
• QueryRow
• QueryRowContext

Functions

func Get

func Get(err error) (string, bool)

func Query

func Query[E any](db Queryable, mapper MapperFunc[E], sql string, p ...any) ([]E, error)

Query executes a query, typically a SELECT that returns entities using the provided mapper function. The args are for any placeholder parameters in the query. If zero rows are selected the returned slice will be nil.

Query uses context.Background internally; to specify the context, use QueryContext.

Example

db, _ := newTestDb()
entities, _ := Query(db, func(row *sql.Rows) (TestStruct, error) {
	var e TestStruct
	err := row.Scan(&e.Id, &e.Col)
	return e, err
}, "SELECT ID,COL FROM TEST WHERE ID IN(?,?) ORDER BY ID DESC", 1, 2)
fmt.Println(entities)

Output:

[{2 Row 2} {1 Row 1}]

func QueryContext

func QueryContext[E any](ctx context.Context, db Queryable, mapper MapperFunc[E], sql string, p ...any) ([]E, error)

QueryContext executes a query, typically a SELECT that returns entities using the provided mapper function. The args are for any placeholder parameters in the query. If zero rows are selected the returned slice will be nil.

Example

db, _ := newTestDb()
ctx := context.Background()
entities, _ := QueryContext(ctx, db, func(row *sql.Rows) (TestStruct, error) {
	var e TestStruct
	err := row.Scan(&e.Id, &e.Col)
	return e, err
}, "SELECT ID,COL FROM TEST WHERE ID IN(?,?) ORDER BY ID DESC", 1, 2)
fmt.Println(entities)

Output:

[{2 Row 2} {1 Row 1}]

func QueryRow

func QueryRow[E any](db Queryable, mapper MapperFunc[E], sql string, p ...any) (E, error)

QueryRow executes a query that is expected oreturn at most one row. The result row is mapped to an entity using the provided mapper function. The args are for any placeholder parameters in the query. If the query selects no rows sql.ErrRows is returned. If multipe rows are returnd the frst row is mapped and returned.

QueryRow uses context.Background internally; to specify the context, use QueryRowContext.

Example

db, _ := newTestDb()
entity, _ := QueryRow(db, func(row *sql.Rows) (TestStruct, error) {
	var e TestStruct
	err := row.Scan(&e.Id, &e.Col)
	return e, err
}, "SELECT ID,COL FROM TEST WHERE ID IN(?,?) ORDER BY ID DESC", 1, 2)
fmt.Println(entity)

Output:

{2 Row 2}

func QueryRowContext

func QueryRowContext[E any](ctx context.Context, db Queryable, mapper MapperFunc[E], sql string, p ...any) (E, error)

QueryRowContext executes a query that is expected oreturn at most one row. The result row is mapped to an entity using the provided mapper function. The args are for any placeholder parameters in the query. If the query selects no rows sql.ErrRows is returned. If multipe rows are returnd the frst row is mapped and returned.

Example

db, _ := newTestDb()
ctx := context.Background()
entity, _ := QueryRowContext(ctx, db, func(row *sql.Rows) (TestStruct, error) {
	var e TestStruct
	err := row.Scan(&e.Id, &e.Col)
	return e, err
}, "SELECT ID,COL FROM TEST WHERE ID IN(?,?) ORDER BY ID DESC", 1, 2)
fmt.Println(entity)

Output:

{2 Row 2}

func With

func With[E any](mapper MapperFunc[E]) func(error) error

func Wrap

func Wrap[E any](err error, mapper MapperFunc[E]) error

Types

type MappedStmt

type MappedStmt[E any] struct {
	// contains filtered or unexported fields
}

If a MappedStmt is prepared on a Tx or Conn, it will be bound to a single underlying connection forever. If the Tx or Conn closes, the MappedStmt will become unusable and all operations will return an error. If a MappedStmt is prepared on a DB, it will remain usable for the lifetime of the DB. When the Stmt needs to execute on a new underlying connection, it will prepare itself on the new connection automatically.

func Prepare

func Prepare[E any](db prepare, mapper MapperFunc[E], query string) (*MappedStmt[E], error)

PrepareContext creates a prepared statement for later queries whose results will be mapped using the provided MapperFunc. Multiple queries or executions may be run concurrently from the returned statement. The caller must call the statement's Close method when the statement is no longer needed.

func PrepareContext

func PrepareContext[E any](ctx context.Context, db prepareContext, mapper MapperFunc[E], query string) (*MappedStmt[E], error)

PrepareContext creates a prepared statement for later queries whose results will be mapped using the provided MapperFunc. Multiple queries or executions may be run concurrently from the returned statement. The caller must call the statement's Close method when the statement is no longer needed.

The provided context is used for the preparation of the statement, not for the execution of the statement.

func (*MappedStmt[E]) Close

func (m *MappedStmt[E]) Close() error

Close closes the MappedStmt

func (*MappedStmt[E]) Query

func (m *MappedStmt[E]) Query(args ...any) ([]E, error)

Query executes a query, typically a SELECT that returns entities using the mapper function provided when preparing the statement.

func (*MappedStmt[E]) QueryContext

func (m *MappedStmt[E]) QueryContext(ctx context.Context, args ...any) ([]E, error)

QueryContext executes a query, typically a SELECT that returns entities using the mapper function provided when preparing the statement. The args are for any placeholder parameters in the query. If zero rows are selected the returned slice will be nil.

func (*MappedStmt[E]) QueryRow

func (m *MappedStmt[E]) QueryRow(args ...any) (E, error)

QueryRow executes a query that is expected to return at most one row. The result row is mapped to an entity using the mapper function provided when preparing the statement. The args are for any placeholder parameters in the query. If the query selects no rows sql.ErrRows is returned. If multipe rows are returnd the frst row is mapped and returned.

func (*MappedStmt[E]) QueryRowContext

func (m *MappedStmt[E]) QueryRowContext(ctx context.Context, args ...any) (E, error)

QueryRowContext executes a query that is expected to return at most one row. The result row is mapped to an entity using the mapper function provided when preparing the statement. The args are for any placeholder parameters in the query. If the query selects no rows sql.ErrRows is returned. If multipe rows are returnd the frst row is mapped and returned.

type MapperFunc

type MapperFunc[E any] func(row *sql.Rows) (E, error)

MapperFunc is used by query functions to map a row to an Entity

type Queryable

type Queryable interface {
	Query(string, ...any) (*sql.Rows, error)
	QueryRow(string, ...any) *sql.Row
	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
}

Queryable enbales rowmap functions to be used with sql.DB sql.Conn and sql.Tx