Documentation
¶
Overview ¶
Package spectypes provides nullable SQL types with automatic casting and conversion methods.
Index ¶
- func DecodeEWKB(raw []byte) (geojson []byte, srid int, err error)
- func DecodeEWKBHex(s string) (geojson []byte, srid int, err error)
- func GeoJSONToWKT(geojson []byte) (string, error)
- func IsJSONType(t reflect.Type) bool
- func IsSpatialType(t reflect.Type) bool
- func IsVectorType(t reflect.Type) bool
- func SQLTypeName(t reflect.Type) (string, bool)
- func ToJSONDT(dt time.Time) string
- func TryIfInt64(v any, def int64) int64
- func UnwrapKind(t reflect.Type) reflect.Kind
- type CIString
- func (s CIString) Compare(other CIString) int
- func (s CIString) Equal(other CIString) bool
- func (s CIString) EqualString(other string) bool
- func (s CIString) Less(other CIString) bool
- func (s *CIString) Scan(value any) error
- func (s CIString) String() string
- func (s CIString) Value() (driver.Value, error)
- type LCString
- func (s LCString) Equal(other LCString) bool
- func (s LCString) EqualString(other string) bool
- func (s LCString) MarshalJSON() ([]byte, error)
- func (s *LCString) Scan(value any) error
- func (s LCString) String() string
- func (s *LCString) UnmarshalJSON(b []byte) error
- func (s LCString) Value() (driver.Value, error)
- type SqlBitVector
- type SqlBool
- type SqlBoolArray
- type SqlByteArray
- type SqlDate
- type SqlFloat32Array
- type SqlFloat64
- type SqlFloat64Array
- type SqlGeography
- type SqlGeometry
- type SqlHalfVector
- type SqlInt16
- type SqlInt16Array
- type SqlInt32
- type SqlInt32Array
- type SqlInt64
- type SqlInt64Array
- type SqlJSONB
- type SqlNull
- func (n SqlNull[T]) Bool() bool
- func (n SqlNull[T]) Float64() float64
- func (n *SqlNull[T]) FromString(s string) error
- func (n SqlNull[T]) Int64() int64
- func (n SqlNull[T]) MarshalJSON() ([]byte, error)
- func (n *SqlNull[T]) Scan(value any) error
- func (n SqlNull[T]) String() string
- func (n SqlNull[T]) Time() time.Time
- func (n SqlNull[T]) UUID() uuid.UUID
- func (n *SqlNull[T]) UnmarshalJSON(b []byte) error
- func (n SqlNull[T]) Value() (driver.Value, error)
- type SqlSparseVector
- type SqlString
- type SqlStringArray
- type SqlTime
- type SqlTimeStamp
- type SqlUUID
- type SqlUUIDArray
- type SqlVector
- type UCString
- func (s UCString) Equal(other UCString) bool
- func (s UCString) EqualString(other string) bool
- func (s UCString) MarshalJSON() ([]byte, error)
- func (s *UCString) Scan(value any) error
- func (s UCString) String() string
- func (s *UCString) UnmarshalJSON(b []byte) error
- func (s UCString) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeEWKB ¶ added in v1.1.41
DecodeEWKB decodes raw PostGIS EWKB bytes into a GeoJSON geometry object and its SRID.
func DecodeEWKBHex ¶ added in v1.1.41
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
GeoJSONToWKT converts a GeoJSON geometry object to its WKT representation.
func IsJSONType ¶ added in v1.1.44
IsJSONType reports whether t is a spectypes JSON/JSONB wrapper.
func IsSpatialType ¶ added in v1.1.41
IsSpatialType reports whether t is a PostGIS geometry/geography wrapper.
func IsVectorType ¶ added in v1.1.41
IsVectorType reports whether t is a pgvector wrapper (vector/halfvec/sparsevec).
func SQLTypeName ¶ added in v1.1.41
SQLTypeName returns the canonical PostgreSQL type name for a spectypes wrapper type, or ("", false) if t is not a recognised spectypes type.
func TryIfInt64 ¶
TryIfInt64 tries to parse any value to int64 with default.
func UnwrapKind ¶ added in v1.1.45
UnwrapKind returns the reflect.Kind to use when reasoning about a column's comparability (numeric vs. string vs. other) for filter building. Plain Go types return their own Kind unchanged. spectypes.SqlNull[T] wrappers (and types that embed one, such as SqlTimeStamp/SqlDate/SqlTime) always report reflect.Struct for their own Kind even when T is an int64 or string, which would otherwise make numeric/text columns look "complex" and force an unnecessary CAST(... AS TEXT) that defeats native column indexes. For those wrappers, UnwrapKind returns the Kind of the wrapped value T instead.
Types ¶
type CIString ¶ added in v1.1.53
type CIString string
CIString is a string that stores, scans, and returns its value exactly as given (no case normalization), but compares case-insensitively via Equal and EqualString. Use it as a bun model field type for columns (e.g. citext, or codes matched case-insensitively) where you want Go-side case-insensitive comparisons without forcing the stored/returned value to a particular case.
func (CIString) Compare ¶ added in v1.1.53
Compare returns -1, 0, or +1 if s is less than, equal to, or greater than other, ignoring case. Useful with slices.SortFunc or similar.
func (CIString) Equal ¶ added in v1.1.53
Equal reports whether s and other are equal, ignoring case.
func (CIString) EqualString ¶ added in v1.1.53
EqualString reports whether s equals other, ignoring case.
func (CIString) Less ¶ added in v1.1.53
Less reports whether s sorts before other, ignoring case. Suitable for sort.Slice or slices.SortFunc comparisons.
func (*CIString) Scan ¶ added in v1.1.53
Scan implements sql.Scanner. The value is stored unchanged.
type LCString ¶ added in v1.1.53
type LCString string
LCString is a string that always stores, scans, and returns as lowercase. Use it as a bun model field type for columns that must be normalized to lowercase (e.g. codes, slugs, emails) rather than merely compared case-insensitively; see CIString if the original case must be preserved.
func (LCString) Equal ¶ added in v1.1.53
Equal reports whether s and other are equal (case-insensitively, since both normalize to lowercase).
func (LCString) EqualString ¶ added in v1.1.53
EqualString reports whether s equals other, ignoring case.
func (LCString) MarshalJSON ¶ added in v1.1.53
MarshalJSON implements json.Marshaler, always lowercase. Needed because encoding/json marshals a bare string-kind type as-is and does not call Value/String, so a value constructed directly (not scanned from the DB) would otherwise serialize with its original case.
func (*LCString) UnmarshalJSON ¶ added in v1.1.53
UnmarshalJSON implements json.Unmarshaler, always lowercase.
type SqlBitVector ¶ added in v1.1.41
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
type SqlBoolArray ¶ added in v1.0.87
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
type SqlByteArray ¶ added in v1.0.44
Type aliases for common types.
func NewSqlByteArray ¶ added in v1.0.44
func NewSqlByteArray(v []byte) SqlByteArray
type SqlDate ¶
SqlDate - Date only (YYYY-MM-DD).
func NewSqlDate ¶
func SqlDateNow ¶
func SqlDateNow() SqlDate
func (SqlDate) MarshalJSON ¶
func (*SqlDate) UnmarshalJSON ¶
type SqlFloat32Array ¶ added in v1.0.87
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
type SqlFloat64 ¶
Type aliases for common types.
func NewSqlFloat64 ¶
func NewSqlFloat64(v float64) SqlFloat64
type SqlFloat64Array ¶ added in v1.0.87
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
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) 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
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
type SqlInt16Array ¶ added in v1.0.87
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
type SqlInt32Array ¶ added in v1.0.87
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
type SqlInt64Array ¶ added in v1.0.87
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
type SqlJSONB ¶
type SqlJSONB []byte
SqlJSONB - Nullable JSONB as []byte.
func (SqlJSONB) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (*SqlJSONB) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
type SqlNull ¶
SqlNull is a generic nullable type that behaves like sql.NullXXX with auto-casting.
func (*SqlNull[T]) FromString ¶
func (SqlNull[T]) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (*SqlNull[T]) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
type SqlSparseVector ¶ added in v1.1.41
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
type SqlStringArray ¶ added in v1.0.87
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
type SqlTime ¶
SqlTime - Time only (HH:MM:SS).
func NewSqlTime ¶
func SqlTimeNow ¶
func SqlTimeNow() SqlTime
func (SqlTime) MarshalJSON ¶
func (*SqlTime) UnmarshalJSON ¶
type SqlTimeStamp ¶
SqlTimeStamp - Timestamp serialized as RFC3339 with timezone offset.
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
type SqlUUIDArray ¶ added in v1.0.87
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
type SqlVector ¶ added in v1.0.87
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 (SqlVector) MarshalJSON ¶ added in v1.0.87
func (*SqlVector) UnmarshalJSON ¶ added in v1.0.87
type UCString ¶ added in v1.1.53
type UCString string
UCString is a string that always stores, scans, and returns as uppercase. Use it as a bun model field type for columns that must be normalized to uppercase (e.g. table prefix codes) rather than merely compared case-insensitively; see CIString if the original case must be preserved.
func (UCString) Equal ¶ added in v1.1.53
Equal reports whether s and other are equal (case-insensitively, since both normalize to uppercase).
func (UCString) EqualString ¶ added in v1.1.53
EqualString reports whether s equals other, ignoring case.
func (UCString) MarshalJSON ¶ added in v1.1.53
MarshalJSON implements json.Marshaler, always uppercase. Needed because encoding/json marshals a bare string-kind type as-is and does not call Value/String, so a value constructed directly (not scanned from the DB) would otherwise serialize with its original case.
func (*UCString) UnmarshalJSON ¶ added in v1.1.53
UnmarshalJSON implements json.Unmarshaler, always uppercase.