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.

—

Pending

Overview

Eval results

Files

Nullable Types

Name: tessl/golang-github-com-jackc-pgx-v5
Author: tessl

These types represent PostgreSQL values with explicit NULL support. Set Valid = false to send NULL; check Valid after scanning.

Import

import "github.com/jackc/pgx/v5/pgtype"

Common Nullable Types

type Bool struct {
    Bool  bool
    Valid bool
}

type Int2 struct {
    Int16 int16
    Valid bool
}

type Int4 struct {
    Int32 int32
    Valid bool
}

type Int8 struct {
    Int64 int64
    Valid bool
}

type Float4 struct {
    Float32 float32
    Valid   bool
}

type Float8 struct {
    Float64 float64
    Valid   bool
}

type Text struct {
    String string
    Valid  bool
}

type Date struct {
    Time             time.Time
    InfinityModifier InfinityModifier
    Valid            bool
}

type Timestamp struct {
    Time             time.Time
    InfinityModifier InfinityModifier
    Valid            bool
}

type Timestamptz struct {
    Time             time.Time
    InfinityModifier InfinityModifier
    Valid            bool
}

type Time struct {
    Microseconds int64 // microseconds since midnight
    Valid        bool
}

type Interval struct {
    Microseconds int64
    Days         int32
    Months       int32
    Valid         bool
}

type Numeric struct {
    Int              *big.Int
    Exp              int32
    NaN              bool
    InfinityModifier InfinityModifier
    Valid            bool
}

type UUID struct {
    Bytes [16]byte
    Valid bool
}

type Bits struct {
    Bytes []byte
    Len   int32
    Valid bool
}

type Uint32 struct {
    Uint32 uint32
    Valid  bool
}

type Uint64 struct {
    Uint64 uint64
    Valid  bool
}

type TID struct {
    BlockNumber  uint32
    OffsetNumber uint16
    Valid        bool
}

type Hstore map[string]*string  // nil value = NULL for that key

All nullable types implement sql.Scanner and driver.Valuer.

Usage

Scanning NULL Values

var name pgtype.Text
err := conn.QueryRow(ctx, "SELECT name FROM users WHERE id = $1", 42).Scan(&name)

if name.Valid {
    fmt.Println("Name:", name.String)
} else {
    fmt.Println("Name is NULL")
}

Sending NULL Values

When using as query parameter, explicitly set Valid = true:

var name pgtype.Text
name.String = "John"
name.Valid = true
conn.Exec(ctx, "INSERT INTO users(name) VALUES ($1)", name)

// Send NULL
var nullName pgtype.Text
nullName.Valid = false
conn.Exec(ctx, "INSERT INTO users(name) VALUES ($1)", nullName)

InfinityModifier

type InfinityModifier int8

const (
    Infinity         InfinityModifier = 1
    Finite           InfinityModifier = 0
    NegativeInfinity InfinityModifier = -1
)

func (im InfinityModifier) String() string

Used with Date, Timestamp, and Timestamptz types to represent PostgreSQL's infinity values:

var ts pgtype.Timestamp
ts.InfinityModifier = pgtype.Infinity
ts.Valid = true
conn.Exec(ctx, "INSERT INTO events(expires_at) VALUES ($1)", ts)

zeronull Package

Types that treat Go zero values as PostgreSQL NULL (and vice versa).

import "github.com/jackc/pgx/v5/pgtype/zeronull"

func Register(m *pgtype.Map)

type Text       string
type Int2       int16
type Int4       int32
type Int8       int64
type Float8     float64
type Timestamp  time.Time
type Timestamptz time.Time
type UUID       [16]byte

Each type implements:

Scan(src any) error (sql.Scanner)
Value() (driver.Value, error) (driver.Valuer)
ScanXxx(v pgtype.Xxx) error
XxxValue() (pgtype.Xxx, error)
SkipUnderlyingTypePlan() (SkipUnderlyingTypePlanner)

Usage

// Empty string stored as NULL, NULL scanned as empty string
_, err := conn.Exec(ctx, "INSERT INTO people(first, middle, last) VALUES ($1,$2,$3)",
    zeronull.Text("John"),
    zeronull.Text(""),    // stored as NULL
    zeronull.Text("Smith"))

var middle zeronull.Text
err = conn.QueryRow(ctx, "SELECT middle FROM people WHERE first = $1", "John").Scan(&middle)
// middle == "" if database value is NULL

Call zeronull.Register(conn.TypeMap()) when using QueryExecModeExec or QueryExecModeSimpleProtocol.

Scanner/Valuer Interfaces

Implement these interfaces to make custom Go types work with pgtype:

// Boolean
type BoolScanner interface { ScanBool(v Bool) error }
type BoolValuer  interface { BoolValue() (Bool, error) }

// Text
type TextScanner interface { ScanText(v Text) error }
type TextValuer  interface { TextValue() (Text, error) }

// Integers
type Int16Scanner interface { ScanInt16(v Int2) error }
type Int16Valuer  interface { Int16Value() (Int2, error) }
type Int32Scanner interface { ScanInt32(v Int4) error }
type Int32Valuer  interface { Int32Value() (Int4, error) }
type Int64Scanner interface { ScanInt64(v Int8) error }
type Int64Valuer  interface { Int64Value() (Int8, error) }

// Floats
type Float32Scanner interface { ScanFloat32(v Float4) error }
type Float32Valuer  interface { Float32Value() (Float4, error) }
type Float64Scanner interface { ScanFloat64(v Float8) error }
type Float64Valuer  interface { Float64Value() (Float8, error) }

// Numeric
type NumericScanner interface { ScanNumeric(v Numeric) error }
type NumericValuer  interface { NumericValue() (Numeric, error) }

// UUID
type UUIDScanner interface { ScanUUID(v UUID) error }
type UUIDValuer  interface { UUIDValue() (UUID, error) }

// Timestamps
type TimestampScanner   interface { ScanTimestamp(v Timestamp) error }
type TimestampValuer    interface { TimestampValue() (Timestamp, error) }
type TimestamptzScanner interface { ScanTimestamptz(v Timestamptz) error }
type TimestamptzValuer  interface { TimestamptzValue() (Timestamptz, error) }
type DateScanner        interface { ScanDate(v Date) error }
type DateValuer         interface { DateValue() (Date, error) }

// Time
type TimeScanner interface { ScanTime(v Time) error }
type TimeValuer  interface { TimeValue() (Time, error) }

// Interval
type IntervalScanner interface { ScanInterval(v Interval) error }
type IntervalValuer  interface { IntervalValue() (Interval, error) }

// Uint32/Uint64
type Uint32Scanner interface { ScanUint32(v Uint32) error }
type Uint32Valuer  interface { Uint32Value() (Uint32, error) }
type Uint64Scanner interface { ScanUint64(v Uint64) error }
type Uint64Valuer  interface { Uint64Value() (Uint64, error) }

// Bytes
type BytesScanner interface { ScanBytes(v []byte) error }
type BytesValuer  interface { BytesValue() ([]byte, error) }

// Network
type NetipPrefixScanner interface { ScanNetipPrefix(v netip.Prefix) error }
type NetipPrefixValuer  interface { NetipPrefixValue() (netip.Prefix, error) }

// Bits
type BitsScanner interface { ScanBits(v Bits) error }
type BitsValuer  interface { BitsValue() (Bits, error) }

// TID
type TIDScanner interface { ScanTID(v TID) error }
type TIDValuer  interface { TIDValue() (TID, error) }

// Hstore
type HstoreScanner interface { ScanHstore(v Hstore) error }
type HstoreValuer  interface { HstoreValue() (Hstore, error) }

Implement both Scanner and Valuer for bidirectional support.

Install with Tessl CLI

npx tessl i tessl/golang-github-com-jackc-pgx-v5

tessl/golang-github-com-jackc-pgx-v5

nullable-types.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/types/

Nullable Types

Import

Common Nullable Types

Usage

Scanning NULL Values

Sending NULL Values

InfinityModifier

zeronull Package

Usage

Scanner/Valuer Interfaces

nullable-types.mddocs/types/