package sqlscan

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

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

Examples

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

Code: 

{
	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

Code:play  

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 ScanAllSets 

func ScanAllSets(dsts []interface{}, rows *sql.Rows) error

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

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

Code:play  

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

Code:play  

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

Code: 

{
	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.

Code: 

{
	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) ScanAllSets 

func (api *API) ScanAllSets(dsts []interface{}, rows *sql.Rows) error

ScanAllSets is a wrapper around the dbscan.ScanAllSets function. See dbscan.ScanAllSets 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

Code:play  

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.

Source Files

doc.go sqlscan.go

Version
v2.1.1
Published
Mar 24, 2024
Platform
windows/amd64
Imports
5 packages
Last checked
4 hours ago –

Tools for package owners.