tessl/golang-github-com-jackc-pgx-v5
pgx is a pure Go driver and toolkit for PostgreSQL providing a native high-performance interface with PostgreSQL-specific features plus a database/sql compatibility adapter.
index.mddocs/types/
Type System (pgtype)
The pgtype package converts between Go values and PostgreSQL wire format values. All standard PostgreSQL types are supported out of the box; custom types can be registered.
Import
import "github.com/jackc/pgx/v5/pgtype"Overview
pgx provides comprehensive type support through the pgtype package:
- Nullable Types: Wrappers like
pgtype.Int4,pgtype.Textwith explicit NULL handling - Arrays: Generic
Array[T]andFlatArray[T]for PostgreSQL arrays - Ranges:
Range[T]for int, timestamp, and custom range types - Multiranges:
Multirange[T]for discontinuous ranges - JSON/JSONB: Direct encoding/decoding of Go structs
- Geometric: Point, Box, Circle, Line, Path, Polygon
- Custom Types: Load enums, composites, domains from the database
Quick Examples
Nullable Values
var name pgtype.Text
err := conn.QueryRow(ctx, "SELECT name FROM users WHERE id = $1", id).Scan(&name)
if name.Valid {
fmt.Println("Name:", name.String)
} else {
fmt.Println("Name is NULL")
}Arrays
var tags pgtype.FlatArray[string]
err := conn.QueryRow(ctx, "SELECT tags FROM articles WHERE id = $1", id).Scan(&tags)
// tags is []stringJSON
type Metadata struct {
Author string `json:"author"`
Tags []string `json:"tags"`
}
var meta Metadata
err := conn.QueryRow(ctx, "SELECT metadata FROM documents WHERE id = $1", id).Scan(&meta)Custom Enum
t, err := conn.LoadType(ctx, "my_status_enum")
conn.TypeMap().RegisterType(t)
var status string
err = conn.QueryRow(ctx, "SELECT status FROM orders WHERE id = $1", id).Scan(&status)Map — Central Type Registry
type Map struct {
TryWrapEncodePlanFuncs []TryWrapEncodePlanFunc
TryWrapScanPlanFuncs []TryWrapScanPlanFunc
}
func NewMap() *Map
func (m *Map) Copy() *MapAccess the connection's Map:
m := conn.TypeMap()Registration
func (m *Map) RegisterType(t *Type)
func (m *Map) RegisterTypes(types []*Type)
func (m *Map) RegisterDefaultPgType(value any, name string)RegisterType— register a codec for a PostgreSQL OIDRegisterDefaultPgType— when the OID is unknown (e.g.,QueryExecModeExec/SimpleProtocol), specify which PostgreSQL type to use for a given Go type
Lookup
func (m *Map) TypeForOID(oid uint32) (*Type, bool)
func (m *Map) TypeForName(name string) (*Type, bool)
func (m *Map) TypeForValue(v any) (*Type, bool)
func (m *Map) FormatCodeForOID(oid uint32) int16Encoding / Decoding
func (m *Map) PlanEncode(oid uint32, format int16, value any) EncodePlan
func (m *Map) PlanScan(oid uint32, formatCode int16, target any) ScanPlan
func (m *Map) Encode(oid uint32, formatCode int16, value any, buf []byte) (newBuf []byte, err error)
func (m *Map) Scan(oid uint32, formatCode int16, src []byte, dst any) errordatabase/sql Compatibility
func (m *Map) SQLScanner(v any) sql.ScannerWrap complex types (e.g., Array[T], Range[T]) for use as sql.Scanner:
m := pgtype.NewMap()
var a []int64
err := db.QueryRow("SELECT '{1,2,3}'::bigint[]").Scan(m.SQLScanner(&a))Type struct
type Type struct {
Name string
OID uint32
Codec Codec
}Codec Interface
type Codec interface {
FormatSupported(format int16) bool
PreferredFormat() int16
PlanEncode(m *Map, oid uint32, format int16, value any) EncodePlan
PlanScan(m *Map, oid uint32, format int16, target any) ScanPlan
DecodeDatabaseSQLValue(m *Map, oid uint32, format int16, src []byte) (driver.Value, error)
DecodeValue(m *Map, oid uint32, format int16, src []byte) (any, error)
}EncodePlan and ScanPlan
type EncodePlan interface {
Encode(value any, buf []byte) (newBuf []byte, err error)
ReportInvalidValue(value any) error
}
type ScanPlan interface {
Scan(src []byte, target any) error
}Common Errors
var ErrScanTargetTypeChanged = errors.New("scan target type changed")Returned when the scan target type changes between rows, which is not supported by plan-based scanning.
Format Codes
const (
TextFormatCode = 0
BinaryFormatCode = 1
)Topic-Specific Documentation
- Nullable Types — Basic types with NULL support
- Arrays & Slices — Array and slice types
- Ranges & Multiranges — Range types
- JSON Types — JSON and JSONB
- Geometric Types — Point, Box, Circle, Line, Path, Polygon
- Custom Types — Enums, composites, domains
- Advanced Codec — Codec implementation details, OID constants, wrap functions
Install with Tessl CLI
npx tessl i tessl/golang-github-com-jackc-pgx-v5@5.8.0