sqlscan

Documentation

Overview

Package sqlscan allows scanning data into Go structs and other composite types, when working with database/sql library.

Essentially, sqlscan is a wrapper around github.com/georgysavva/scany/v2/dbscan package. sqlscan connects database/sql with dbscan functionality. It contains adapters that are meant to work with *sql.Rows and proxy all calls to dbscan. sqlscan provides all capabilities available in dbscan. It's encouraged to read dbscan docs first to get familiar with all concepts and features: https://pkg.go.dev/github.com/georgysavva/scany/v2/dbscan

Querying rows

sqlscan can query rows and work with *sql.DB, *sql.Conn or *sql.Tx directly. To support this it has two high-level functions Select and Get, they accept anything that implements Querier interface and query rows from it. This means that they can be used with *sql.DB, *sql.Conn or *sql.Tx.

Index

• Variables
• func Get(ctx context.Context, db Querier, dst interface{}, query string, ...) error
• func NewDBScanAPI(opts ...dbscan.APIOption) (*dbscan.API, error)
• func NotFound(err error) bool
• func ScanAll(dst interface{}, rows *sql.Rows) error
• func ScanOne(dst interface{}, rows *sql.Rows) error
• func ScanRow(dst interface{}, rows *sql.Rows) error
• func Select(ctx context.Context, db Querier, dst interface{}, query string, ...) error
• type API
  • func NewAPI(dbscanAPI *dbscan.API) (*API, error)
  • func (api *API) Get(ctx context.Context, db Querier, dst interface{}, query string, ...) error
  • func (api *API) NewRowScanner(rows *sql.Rows) *RowScanner
  • func (api *API) ScanAll(dst interface{}, rows *sql.Rows) error
  • func (api *API) ScanOne(dst interface{}, rows *sql.Rows) error
  • func (api *API) ScanRow(dst interface{}, rows *sql.Rows) error
  • func (api *API) Select(ctx context.Context, db Querier, dst interface{}, query string, ...) error
• type Querier
• type RowScanner
  • func NewRowScanner(rows *sql.Rows) *RowScanner

Examples

• API
• Get
• RowScanner
• ScanAll
• ScanOne
• ScanRow
• Select

Variables

var DefaultAPI = mustNewAPI(mustNewDBScanAPI())

DefaultAPI is the default instance of API with all configuration settings set to default.

Functions

func Get

func Get(ctx context.Context, db Querier, dst interface{}, query string, args ...interface{}) error

Get is a package-level helper function that uses the DefaultAPI object. See API.Get for details.

Example

type User struct {
	ID       string `db:"user_id"`
	FullName string
	Email    string
	Age      int
}

db, _ := sql.Open("postgres", "example-connection-url")

var user User
if err := sqlscan.Get(
	ctx, db, &user, `SELECT user_id, full_name, email, age FROM users WHERE user_id='bob'`,
); err != nil {
	// Handle query or rows processing error.
}
// user variable now contains data from all rows.

func NewDBScanAPI

func NewDBScanAPI(opts ...dbscan.APIOption) (*dbscan.API, error)

NewDBScanAPI creates a new dbscan API object with default configuration settings for sqlscan.

func NotFound

func NotFound(err error) bool

NotFound is a helper function to check if an error is `sql.ErrNoRows`.

func ScanAll

func ScanAll(dst interface{}, rows *sql.Rows) error

ScanAll is a package-level helper function that uses the DefaultAPI object. See API.ScanAll for details.

Example

package main

import (
	"database/sql"

	"github.com/georgysavva/scany/v2/sqlscan"
)

func main() {
	type User struct {
		ID       string `db:"user_id"`
		FullName string
		Email    string
		Age      int
	}

	// Query *sql.Rows from the database.
	db, _ := sql.Open("postgres", "example-connection-url")
	rows, _ := db.Query(`SELECT user_id, full_name, email, age FROM users`)

	var users []*User
	if err := sqlscan.ScanAll(&users, rows); err != nil {
		// Handle rows processing error.
	}
	// users variable now contains data from all rows.
}

func ScanOne

func ScanOne(dst interface{}, rows *sql.Rows) error

ScanOne is a package-level helper function that uses the DefaultAPI object. See API.ScanOne for details.

Example

package main

import (
	"database/sql"

	"github.com/georgysavva/scany/v2/sqlscan"
)

func main() {
	type User struct {
		ID       string `db:"user_id"`
		FullName string
		Email    string
		Age      int
	}

	// Query *sql.Rows from the database.
	db, _ := sql.Open("postgres", "example-connection-url")
	rows, _ := db.Query(`SELECT user_id, full_name, email, age FROM users WHERE user_id='bob'`)

	var user User
	if err := sqlscan.ScanOne(&user, rows); err != nil {
		// Handle rows processing error.
	}
	// user variable now contains data from the single row.
}

func ScanRow

func ScanRow(dst interface{}, rows *sql.Rows) error

ScanRow is a package-level helper function that uses the DefaultAPI object. See API.ScanRow for details.

Example

package main

import (
	"database/sql"

	"github.com/georgysavva/scany/v2/sqlscan"
)

func main() {
	type User struct {
		ID       string `db:"user_id"`
		FullName string
		Email    string
		Age      int
	}

	// Query *sql.Rows from the database.
	db, _ := sql.Open("postgres", "example-connection-url")
	rows, _ := db.Query(`SELECT user_id, full_name, email, age FROM users`)
	defer rows.Close()
	for rows.Next() {
		var user User
		if err := sqlscan.ScanRow(&user, rows); err != nil {
			// Handle row scanning error.
		}
		// user variable now contains data from the current row.
	}
	if err := rows.Err(); err != nil {
		// Handle rows final error.
	}
}

func Select

func Select(ctx context.Context, db Querier, dst interface{}, query string, args ...interface{}) error

Select is a package-level helper function that uses the DefaultAPI object. See API.Select for details.

Example

type User struct {
	ID       string `db:"user_id"`
	FullName string
	Email    string
	Age      int
}

db, _ := sql.Open("postgres", "example-connection-url")

var users []*User
if err := sqlscan.Select(
	ctx, db, &users, `SELECT user_id, full_name, email, age FROM users`,
); err != nil {
	// Handle query or rows processing error.
}
// users variable now contains data from all rows.

Types

type API

type API struct {
	// contains filtered or unexported fields
}

API is a wrapper around the dbscan.API type. See dbscan.API for details.

Example

This example shows how to create and use a custom API instance to override default settings.

type User struct {
	ID       string `database:"userid"`
	FullName string
	Email    string
	Age      int
}

// Instantiate a custom API with overridden settings.
dbscanAPI, err := sqlscan.NewDBScanAPI(
	dbscan.WithFieldNameMapper(strings.ToLower),
	dbscan.WithStructTagKey("database"),
)
if err != nil {
	// Handle dbscan API initialization error.
}
api, err := sqlscan.NewAPI(dbscanAPI)
if err != nil {
	// Handle sqlscan API initialization error.
}

db, _ := sql.Open("postgres", "example-connection-url")

var users []*User
// Use the custom API instance to access sqlscan functionality.
if err := api.Select(
	ctx, db, &users, `SELECT userid, fullname, email, age FROM users`,
); err != nil {
	// Handle query or rows processing error.
}
// users variable now contains data from all rows.

func NewAPI

func NewAPI(dbscanAPI *dbscan.API) (*API, error)

NewAPI creates new API instance from dbscan.API instance.

func (*API) Get

func (api *API) Get(ctx context.Context, db Querier, dst interface{}, query string, args ...interface{}) error

Get is a high-level function that queries rows from Querier and calls the ScanOne function. See ScanOne for details.

func (*API) NewRowScanner

func (api *API) NewRowScanner(rows *sql.Rows) *RowScanner

NewRowScanner returns a new RowScanner instance.

func (*API) ScanAll

func (api *API) ScanAll(dst interface{}, rows *sql.Rows) error

ScanAll is a wrapper around the dbscan.ScanAll function. See dbscan.ScanAll for details.

func (*API) ScanOne

func (api *API) ScanOne(dst interface{}, rows *sql.Rows) error

ScanOne is a wrapper around the dbscan.ScanOne function. See dbscan.ScanOne for details. If no rows are found it returns an sql.ErrNoRows error.

func (*API) ScanRow

func (api *API) ScanRow(dst interface{}, rows *sql.Rows) error

ScanRow is a wrapper around the dbscan.ScanRow function. See dbscan.ScanRow for details.

func (*API) Select

func (api *API) Select(ctx context.Context, db Querier, dst interface{}, query string, args ...interface{}) error

Select is a high-level function that queries rows from Querier and calls the ScanAll function. See ScanAll for details.

type Querier

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

Querier is something that sqlscan can query and get the *sql.Rows from. For example, it can be: *sql.DB, *sql.Conn or *sql.Tx.

type RowScanner

type RowScanner struct {
	*dbscan.RowScanner
}

RowScanner is a wrapper around the dbscan.RowScanner type. See dbscan.RowScanner for details.

Example

package main

import (
	"database/sql"

	"github.com/georgysavva/scany/v2/sqlscan"
)

func main() {
	type User struct {
		ID       string `db:"user_id"`
		FullName string
		Email    string
		Age      int
	}

	// Query *sql.Rows from the database.
	db, _ := sql.Open("postgres", "example-connection-url")
	rows, _ := db.Query(`SELECT user_id, full_name, email, age FROM users`)
	defer rows.Close()

	rs := sqlscan.NewRowScanner(rows)

	for rows.Next() {
		var user User
		if err := rs.Scan(&user); err != nil {
			// Handle row scanning error.
		}
		// user variable now contains data from the current row.
	}
	if err := rows.Err(); err != nil {
		// Handle rows final error.
	}
}

func NewRowScanner

func NewRowScanner(rows *sql.Rows) *RowScanner

NewRowScanner is a package-level helper function that uses the DefaultAPI object. See API.NewRowScanner for details.