pgxscan

Overview ¶

Package pgxscan adds the ability to directly scan into structs from pgx query results.

Supported data types ¶

The following Go data types are supported as destinations in a struct:

• int64
• int32
• int16
• string
• []byte
• float64
• float32

The data types have to match exactly. No extension or truncation is done.

For example:

A struct field of int32 has to be matched with a SQL result field of int. Neither int64 nor int16 are allowed as destination types for an int result.

This applies to all supported types!

TODO: decide if larger int types should be allowed to hold smaller results. Does only make sense for ints, floating point values would be hit by rounding/representation problems.

pgxscan also supports some slice types directly:

[]int64
[]int32
[]int16
[]float32
[]float64
[]string
[][]byte

Only 1 dimensional arrays are supported for now. The slices in the struct are overwritten by newly allocated slices. So it does not make sense to pre-allocate anything in there.

Embedded structs are supported. If there are duplicate field names, the highest level name is used. Which is the Go rule for access.

Default name matching ¶

A match is found when the following conditions are met:

• both names are not empty (length > 0)
• the name of the struct field matches the name from the result set (EqualFold)

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/guidog/pgxscan"
	"github.com/jackc/pgx/v4"
)

type testRecord struct {
	// order of fields does not matter
	String string
	X      []byte
	Bigid  int64
	N      float32
	R      float64
	Xx     [][]byte
	A      []string
	Xa     []int64
}

func setupDB() *pgx.Conn {
	// do DB connect
	return &pgx.Conn{}
}

func main() {
	const testTable = `CREATE TABLE IF NOT EXISTS scantest (
  bigid bigint DEFAULT 7,
  string text DEFAULT 'xy',
  n real DEFAULT 42.1,
  r double precision DEFAULT -0.000001,
  a text[] DEFAULT '{"AA","BB"}',
  x bytea DEFAULT '\x010203',
  xx bytea[] DEFAULT '{"0102", "x"}',
  xa int[] DEFAULT '{11,22}'
)`

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	db := setupDB()
	defer db.Close(ctx)

	rows, err := db.Query(ctx, "SELECT * FROM scantest")
	if err != nil {
		panic(err)
	}
	defer rows.Close()

	for rows.Next() {
		var dest testRecord

		fmt.Printf("data before: %+v\n", dest)

		err = pgxscan.ReadStruct(&dest, rows)
		if err != nil {
			panic(err)
		}

		fmt.Printf("data after: %+v\n", dest)
	}
}

Output: