spectypes

package
v1.1.41 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 29, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package spectypes provides nullable SQL types with automatic casting and conversion methods.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeEWKB added in v1.1.41 

func DecodeEWKB(raw []byte) (geojson []byte, srid int, err error)

DecodeEWKB decodes raw PostGIS EWKB bytes into a GeoJSON geometry object and its SRID.

func DecodeEWKBHex added in v1.1.41 

func DecodeEWKBHex(s string) (geojson []byte, srid int, err error)

DecodeEWKBHex decodes a PostGIS hex-EWKB string (the default text representation of a geometry column) into a GeoJSON geometry object and its SRID. An SRID of 0 means "unspecified".

func GeoJSONToWKT added in v1.1.41 

func GeoJSONToWKT(geojson []byte) (string, error)

GeoJSONToWKT converts a GeoJSON geometry object to its WKT representation.

func IsSpatialType added in v1.1.41 

func IsSpatialType(t reflect.Type) bool

IsSpatialType reports whether t is a PostGIS geometry/geography wrapper.

func IsVectorType added in v1.1.41 

func IsVectorType(t reflect.Type) bool

IsVectorType reports whether t is a pgvector wrapper (vector/halfvec/sparsevec).

func SQLTypeName added in v1.1.41 

func SQLTypeName(t reflect.Type) (string, bool)

SQLTypeName returns the canonical PostgreSQL type name for a spectypes wrapper type, or ("", false) if t is not a recognised spectypes type.

func ToJSONDT 

func ToJSONDT(dt time.Time) string

ToJSONDT formats a time.Time to RFC3339 string.

func TryIfInt64 

func TryIfInt64(v any, def int64) int64

TryIfInt64 tries to parse any value to int64 with default.

Types

type SqlBitVector added in v1.1.41 

type SqlBitVector struct {
	Val   []bool
	Valid bool
}

SqlBitVector is a nullable Postgres `bit(n)` / `varbit` column (used by pgvector for Hamming/Jaccard distance), backed by []bool. Wire format: a string of '0'/'1' characters. JSON: a bool array.

func NewSqlBitVector added in v1.1.41 

func NewSqlBitVector(val []bool) SqlBitVector

func (SqlBitVector) MarshalJSON added in v1.1.41 

func (v SqlBitVector) MarshalJSON() ([]byte, error)

func (*SqlBitVector) Scan added in v1.1.41 

func (v *SqlBitVector) Scan(value any) error

func (*SqlBitVector) UnmarshalJSON added in v1.1.41 

func (v *SqlBitVector) UnmarshalJSON(b []byte) error

func (SqlBitVector) Value added in v1.1.41 

func (v SqlBitVector) Value() (driver.Value, error)

type SqlBool 

type SqlBool = SqlNull[bool]

Type aliases for common types.

func NewSqlBool 

func NewSqlBool(v bool) SqlBool

type SqlBoolArray added in v1.0.87 

type SqlBoolArray struct {
	Val   []bool
	Valid bool
}

func NewSqlBoolArray added in v1.0.87 

func NewSqlBoolArray(v []bool) SqlBoolArray

func (SqlBoolArray) MarshalJSON added in v1.0.87 

func (a SqlBoolArray) MarshalJSON() ([]byte, error)

func (*SqlBoolArray) Scan added in v1.0.87 

func (a *SqlBoolArray) Scan(value any) error

func (*SqlBoolArray) UnmarshalJSON added in v1.0.87 

func (a *SqlBoolArray) UnmarshalJSON(b []byte) error

func (SqlBoolArray) Value added in v1.0.87 

func (a SqlBoolArray) Value() (driver.Value, error)

type SqlByteArray added in v1.0.44 

type SqlByteArray = SqlNull[[]byte]

Type aliases for common types.

func NewSqlByteArray added in v1.0.44 

func NewSqlByteArray(v []byte) SqlByteArray

type SqlDate 

type SqlDate struct{ SqlNull[time.Time] }

SqlDate - Date only (YYYY-MM-DD).

func NewSqlDate 

func NewSqlDate(v time.Time) SqlDate

func SqlDateNow 

func SqlDateNow() SqlDate

func (SqlDate) MarshalJSON 

func (d SqlDate) MarshalJSON() ([]byte, error)

func (SqlDate) String 

func (d SqlDate) String() string

func (*SqlDate) UnmarshalJSON 

func (d *SqlDate) UnmarshalJSON(b []byte) error

func (SqlDate) Value 

func (d SqlDate) Value() (driver.Value, error)

type SqlFloat32Array added in v1.0.87 

type SqlFloat32Array struct {
	Val   []float32
	Valid bool
}

func NewSqlFloat32Array added in v1.0.87 

func NewSqlFloat32Array(v []float32) SqlFloat32Array

func (SqlFloat32Array) MarshalJSON added in v1.0.87 

func (a SqlFloat32Array) MarshalJSON() ([]byte, error)

func (*SqlFloat32Array) Scan added in v1.0.87 

func (a *SqlFloat32Array) Scan(value any) error

func (*SqlFloat32Array) UnmarshalJSON added in v1.0.87 

func (a *SqlFloat32Array) UnmarshalJSON(b []byte) error

func (SqlFloat32Array) Value added in v1.0.87 

func (a SqlFloat32Array) Value() (driver.Value, error)

type SqlFloat64 

type SqlFloat64 = SqlNull[float64]

Type aliases for common types.

func NewSqlFloat64 

func NewSqlFloat64(v float64) SqlFloat64

type SqlFloat64Array added in v1.0.87 

type SqlFloat64Array struct {
	Val   []float64
	Valid bool
}

func NewSqlFloat64Array added in v1.0.87 

func NewSqlFloat64Array(v []float64) SqlFloat64Array

func (SqlFloat64Array) MarshalJSON added in v1.0.87 

func (a SqlFloat64Array) MarshalJSON() ([]byte, error)

func (*SqlFloat64Array) Scan added in v1.0.87 

func (a *SqlFloat64Array) Scan(value any) error

func (*SqlFloat64Array) UnmarshalJSON added in v1.0.87 

func (a *SqlFloat64Array) UnmarshalJSON(b []byte) error

func (SqlFloat64Array) Value added in v1.0.87 

func (a SqlFloat64Array) Value() (driver.Value, error)

type SqlGeography added in v1.1.41 

type SqlGeography struct {
	SqlGeometry
}

SqlGeography is identical to SqlGeometry but maps to a PostGIS `geography` column. Coordinates are always lon/lat and the default SRID is 4326.

type SqlGeometry added in v1.1.41 

type SqlGeometry struct {
	GeoJSON json.RawMessage
	SRID    int
	Valid   bool
}

SqlGeometry is a nullable PostGIS `geometry` column.

On Scan it accepts the PostGIS default hex-EWKB text output, a raw GeoJSON object, or a WKT/EWKT string (e.g. when the column is selected via ST_AsGeoJSON / ST_AsText). Internally it holds a canonical GeoJSON geometry object plus the SRID.

On Value it emits `SRID=<n>;<WKT>` text. PostGIS registers an implicit text -> geometry cast, so parameterised inserts/updates work without wrapping the placeholder in a constructor function.

MarshalJSON emits the GeoJSON geometry object (or null).

func NewSqlGeometryFromEWKT added in v1.1.41 

func NewSqlGeometryFromEWKT(ewkt string) (SqlGeometry, error)

NewSqlGeometryFromEWKT builds a SqlGeometry from an EWKT or WKT string.

func NewSqlGeometryFromGeoJSON added in v1.1.41 

func NewSqlGeometryFromGeoJSON(geojson []byte, srid int) (SqlGeometry, error)

NewSqlGeometryFromGeoJSON builds a SqlGeometry from a GeoJSON geometry object.

func (SqlGeometry) EWKT added in v1.1.41 

func (g SqlGeometry) EWKT() string

EWKT returns the geometry as `SRID=<n>;<WKT>`.

func (SqlGeometry) MarshalJSON added in v1.1.41 

func (g SqlGeometry) MarshalJSON() ([]byte, error)

func (*SqlGeometry) Scan added in v1.1.41 

func (g *SqlGeometry) Scan(value any) error

func (*SqlGeometry) UnmarshalJSON added in v1.1.41 

func (g *SqlGeometry) UnmarshalJSON(b []byte) error

func (SqlGeometry) Value added in v1.1.41 

func (g SqlGeometry) Value() (driver.Value, error)

func (SqlGeometry) WKT added in v1.1.41 

func (g SqlGeometry) WKT() string

WKT returns the geometry as a plain WKT string (no SRID prefix).

type SqlHalfVector added in v1.1.41 

type SqlHalfVector struct {
	Val   []float32
	Valid bool
}

SqlHalfVector is a nullable pgvector `halfvec` (half-precision) column, backed by []float32. Wire format matches `vector`: `[1,2,3]`.

func NewSqlHalfVector added in v1.1.41 

func NewSqlHalfVector(val []float32) SqlHalfVector

func (SqlHalfVector) MarshalJSON added in v1.1.41 

func (v SqlHalfVector) MarshalJSON() ([]byte, error)

func (*SqlHalfVector) Scan added in v1.1.41 

func (v *SqlHalfVector) Scan(value any) error

func (*SqlHalfVector) UnmarshalJSON added in v1.1.41 

func (v *SqlHalfVector) UnmarshalJSON(b []byte) error

func (SqlHalfVector) Value added in v1.1.41 

func (v SqlHalfVector) Value() (driver.Value, error)

type SqlInt16 

type SqlInt16 = SqlNull[int16]

Type aliases for common types.

func NewSqlInt16 

func NewSqlInt16(v int16) SqlInt16

type SqlInt16Array added in v1.0.87 

type SqlInt16Array struct {
	Val   []int16
	Valid bool
}

func NewSqlInt16Array added in v1.0.87 

func NewSqlInt16Array(v []int16) SqlInt16Array

func (SqlInt16Array) MarshalJSON added in v1.0.87 

func (a SqlInt16Array) MarshalJSON() ([]byte, error)

func (*SqlInt16Array) Scan added in v1.0.87 

func (a *SqlInt16Array) Scan(value any) error

func (*SqlInt16Array) UnmarshalJSON added in v1.0.87 

func (a *SqlInt16Array) UnmarshalJSON(b []byte) error

func (SqlInt16Array) Value added in v1.0.87 

func (a SqlInt16Array) Value() (driver.Value, error)

type SqlInt32 

type SqlInt32 = SqlNull[int32]

Type aliases for common types.

func NewSqlInt32 

func NewSqlInt32(v int32) SqlInt32

type SqlInt32Array added in v1.0.87 

type SqlInt32Array struct {
	Val   []int32
	Valid bool
}

func NewSqlInt32Array added in v1.0.87 

func NewSqlInt32Array(v []int32) SqlInt32Array

func (SqlInt32Array) MarshalJSON added in v1.0.87 

func (a SqlInt32Array) MarshalJSON() ([]byte, error)

func (*SqlInt32Array) Scan added in v1.0.87 

func (a *SqlInt32Array) Scan(value any) error

func (*SqlInt32Array) UnmarshalJSON added in v1.0.87 

func (a *SqlInt32Array) UnmarshalJSON(b []byte) error

func (SqlInt32Array) Value added in v1.0.87 

func (a SqlInt32Array) Value() (driver.Value, error)

type SqlInt64 

type SqlInt64 = SqlNull[int64]

Type aliases for common types.

func NewSqlInt64 

func NewSqlInt64(v int64) SqlInt64

type SqlInt64Array added in v1.0.87 

type SqlInt64Array struct {
	Val   []int64
	Valid bool
}

func NewSqlInt64Array added in v1.0.87 

func NewSqlInt64Array(v []int64) SqlInt64Array

func (SqlInt64Array) MarshalJSON added in v1.0.87 

func (a SqlInt64Array) MarshalJSON() ([]byte, error)

func (*SqlInt64Array) Scan added in v1.0.87 

func (a *SqlInt64Array) Scan(value any) error

func (*SqlInt64Array) UnmarshalJSON added in v1.0.87 

func (a *SqlInt64Array) UnmarshalJSON(b []byte) error

func (SqlInt64Array) Value added in v1.0.87 

func (a SqlInt64Array) Value() (driver.Value, error)

type SqlJSONB 

type SqlJSONB []byte

SqlJSONB - Nullable JSONB as []byte.

func (SqlJSONB) AsMap 

func (n SqlJSONB) AsMap() (map[string]any, error)

func (SqlJSONB) AsSlice 

func (n SqlJSONB) AsSlice() ([]any, error)

func (SqlJSONB) MarshalJSON 

func (n SqlJSONB) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*SqlJSONB) Scan 

func (n *SqlJSONB) Scan(value any) error

Scan implements sql.Scanner.

func (*SqlJSONB) UnmarshalJSON 

func (n *SqlJSONB) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (SqlJSONB) Value 

func (n SqlJSONB) Value() (driver.Value, error)

Value implements driver.Valuer.

type SqlNull 

type SqlNull[T any] struct {
	Val   T
	Valid bool
}

SqlNull is a generic nullable type that behaves like sql.NullXXX with auto-casting.

func NewSql 

func NewSql[T any](value any) SqlNull[T]

func Null 

func Null[T any](v T, valid bool) SqlNull[T]

Constructor helpers - clean and fast value creation

func (SqlNull[T]) Bool 

func (n SqlNull[T]) Bool() bool

Bool converts to bool or false if invalid.

func (SqlNull[T]) Float64 

func (n SqlNull[T]) Float64() float64

Float64 converts to float64 or 0.0 if invalid.

func (*SqlNull[T]) FromString 

func (n *SqlNull[T]) FromString(s string) error

func (SqlNull[T]) Int64 

func (n SqlNull[T]) Int64() int64

Int64 converts to int64 or 0 if invalid.

func (SqlNull[T]) MarshalJSON 

func (n SqlNull[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*SqlNull[T]) Scan 

func (n *SqlNull[T]) Scan(value any) error

Scan implements sql.Scanner.

func (SqlNull[T]) String 

func (n SqlNull[T]) String() string

String implements fmt.Stringer.

func (SqlNull[T]) Time 

func (n SqlNull[T]) Time() time.Time

Time converts to time.Time or zero if invalid.

func (SqlNull[T]) UUID 

func (n SqlNull[T]) UUID() uuid.UUID

UUID converts to uuid.UUID or Nil if invalid.

func (*SqlNull[T]) UnmarshalJSON 

func (n *SqlNull[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (SqlNull[T]) Value 

func (n SqlNull[T]) Value() (driver.Value, error)

Value implements driver.Valuer.

type SqlSparseVector added in v1.1.41 

type SqlSparseVector struct {
	Dim     int
	Indices []int32
	Values  []float32
	Valid   bool
}

SqlSparseVector is a nullable pgvector `sparsevec` column. Wire format: `{1:0.5,4:0.2}/8` (1-based indices). JSON: `{"dim":8,"indices":[1,4],"values":[0.5,0.2]}`.

func NewSqlSparseVector added in v1.1.41 

func NewSqlSparseVector(dim int, indices []int32, values []float32) SqlSparseVector

func (SqlSparseVector) MarshalJSON added in v1.1.41 

func (v SqlSparseVector) MarshalJSON() ([]byte, error)

func (*SqlSparseVector) Scan added in v1.1.41 

func (v *SqlSparseVector) Scan(value any) error

func (*SqlSparseVector) UnmarshalJSON added in v1.1.41 

func (v *SqlSparseVector) UnmarshalJSON(b []byte) error

func (SqlSparseVector) Value added in v1.1.41 

func (v SqlSparseVector) Value() (driver.Value, error)

type SqlString 

type SqlString = SqlNull[string]

Type aliases for common types.

func NewSqlString 

func NewSqlString(v string) SqlString

type SqlStringArray added in v1.0.87 

type SqlStringArray struct {
	Val   []string
	Valid bool
}

SqlStringArray is a nullable PostgreSQL text[] / varchar[] array.

func NewSqlStringArray added in v1.0.87 

func NewSqlStringArray(v []string) SqlStringArray

func (SqlStringArray) MarshalJSON added in v1.0.87 

func (a SqlStringArray) MarshalJSON() ([]byte, error)

func (*SqlStringArray) Scan added in v1.0.87 

func (a *SqlStringArray) Scan(value any) error

func (*SqlStringArray) UnmarshalJSON added in v1.0.87 

func (a *SqlStringArray) UnmarshalJSON(b []byte) error

func (SqlStringArray) Value added in v1.0.87 

func (a SqlStringArray) Value() (driver.Value, error)

type SqlTime 

type SqlTime struct{ SqlNull[time.Time] }

SqlTime - Time only (HH:MM:SS).

func NewSqlTime 

func NewSqlTime(v time.Time) SqlTime

func SqlTimeNow 

func SqlTimeNow() SqlTime

func (SqlTime) MarshalJSON 

func (t SqlTime) MarshalJSON() ([]byte, error)

func (SqlTime) String 

func (t SqlTime) String() string

func (*SqlTime) UnmarshalJSON 

func (t *SqlTime) UnmarshalJSON(b []byte) error

func (SqlTime) Value 

func (t SqlTime) Value() (driver.Value, error)

type SqlTimeStamp 

type SqlTimeStamp struct{ SqlNull[time.Time] }

SqlTimeStamp - Timestamp with custom formatting (YYYY-MM-DDTHH:MM:SS).

func NewSqlTimeStamp 

func NewSqlTimeStamp(v time.Time) SqlTimeStamp

func SqlTimeStampNow 

func SqlTimeStampNow() SqlTimeStamp

func (SqlTimeStamp) MarshalJSON 

func (t SqlTimeStamp) MarshalJSON() ([]byte, error)

func (*SqlTimeStamp) UnmarshalJSON 

func (t *SqlTimeStamp) UnmarshalJSON(b []byte) error

func (SqlTimeStamp) Value 

func (t SqlTimeStamp) Value() (driver.Value, error)

type SqlUUID 

type SqlUUID = SqlNull[uuid.UUID]

Type aliases for common types.

func NewSqlUUID 

func NewSqlUUID(v uuid.UUID) SqlUUID

type SqlUUIDArray added in v1.0.87 

type SqlUUIDArray struct {
	Val   []uuid.UUID
	Valid bool
}

func NewSqlUUIDArray added in v1.0.87 

func NewSqlUUIDArray(v []uuid.UUID) SqlUUIDArray

func (SqlUUIDArray) MarshalJSON added in v1.0.87 

func (a SqlUUIDArray) MarshalJSON() ([]byte, error)

func (*SqlUUIDArray) Scan added in v1.0.87 

func (a *SqlUUIDArray) Scan(value any) error

func (*SqlUUIDArray) UnmarshalJSON added in v1.0.87 

func (a *SqlUUIDArray) UnmarshalJSON(b []byte) error

func (SqlUUIDArray) Value added in v1.0.87 

func (a SqlUUIDArray) Value() (driver.Value, error)

type SqlVector added in v1.0.87 

type SqlVector struct {
	Val   []float32
	Valid bool
}

SqlVector is a nullable pgvector `vector` type backed by []float32. Wire format: `[1.0,2.0,3.0]` (square brackets, comma-separated floats).

func NewSqlVector added in v1.0.87 

func NewSqlVector(val []float32) SqlVector

func (SqlVector) MarshalJSON added in v1.0.87 

func (v SqlVector) MarshalJSON() ([]byte, error)

func (*SqlVector) Scan added in v1.0.87 

func (v *SqlVector) Scan(value any) error

func (*SqlVector) UnmarshalJSON added in v1.0.87 

func (v *SqlVector) UnmarshalJSON(b []byte) error

func (SqlVector) Value added in v1.0.87 

func (v SqlVector) Value() (driver.Value, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.