gosql

package module
v2.3.2 Latest Latest
Warning

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

Go to latest
Published: Nov 30, 2025 License: MIT Imports: 9 Imported by: 15

README

GoSQL Types Collection

Build Status Go Report Card GoDoc Coverage Status

A comprehensive Go library providing SQL-compatible types and collections with full JSON marshaling/unmarshaling support and database integration.

Features

Core Types
  • Char - Single character type with SQL and JSON support
  • Duration - Extended duration type with custom parsing (ns, us, ms, s, m, h, d, w)
  • JSON - Generic JSON type for any value (structs, scalars, arrays)
  • StringArray - Array of strings with PostgreSQL-compatible formatting
  • NumberArray - Generic numeric arrays supporting integers and floats
  • NullableJSON - JSON type with nullable support
Array Types

All array types support:

  • Ordered variants for sorted arrays
  • Nullable variants that can be null
  • PostgreSQL array format parsing and generation
  • JSON marshaling/unmarshaling
  • SQL scanning and value generation
ORM Integration

Full GORM support is provided via the gorm subpackage with:

  • Database-specific type mapping (MySQL, PostgreSQL, SQLite, YDB, ClickHouse)
  • Custom value expressions for different SQL dialects
  • Proper migration support

Installation

go get github.com/geniusrabbit/gosql/v2

For GORM integration:

go get github.com/geniusrabbit/gosql/gorm

Usage

Basic Types
import (
  "github.com/geniusrabbit/gosql/v2"
)

type Model struct {
  ID uint64
  Title string
  Status gosql.Char
  
  // JSON configurations
  Configuration gosql.JSON[Config]
  Metadata gosql.NullableJSON[map[string]any]
  
  // Arrays
  Tags gosql.StringArray
  Scores gosql.OrderedNumberArray[float64]
  Metrics gosql.NullableOrderedNumberArray[int]
  
  // Duration with custom parsing
  Timeout gosql.Duration
}

// Usage examples
model := Model{
  Status: gosql.Char('A'),
  Configuration: gosql.MustJSON(Config{Debug: true}),
  Tags: gosql.StringArray{"tag1", "tag2", "tag3"},
  Scores: gosql.OrderedNumberArray[float64]{9.5, 8.7, 9.1},
  Timeout: gosql.Duration(5 * time.Minute),
}
ORM Usage
import (
  "github.com/geniusrabbit/gosql/gorm"
)

type User struct {
  ID uint64
  Name string
  Status gorm.Char
  Settings gorm.JSON[UserSettings]
  Tags gorm.StringArray
}

// The GORM types automatically handle:
// - Database-specific SQL generation
// - Type casting for different databases
// - Proper migration schemas
Supported Databases

The library provides optimized support for:

  • PostgreSQL - Native array and JSON support
  • MySQL/MariaDB - JSON and text-based arrays
  • SQLite - Text-based storage with JSON parsing
  • SQL Server - JSON and varchar arrays
  • YDB - Specialized type casting
  • ClickHouse - Optimized for analytics workloads
Testing

The library includes comprehensive tests covering:

  • Core type functionality (scan, value, JSON marshaling)
  • Database-specific behavior testing
  • GORM integration testing with mock dialectors
  • Error handling and edge cases
  • Unicode and special character support

Run tests:

# Core library tests
go test -v

# GORM integration tests
cd gorm && go test -v

Contributing

Contributions are welcome! The library follows standard Go conventions and includes:

  • Comprehensive test coverage
  • Proper error handling
  • Database compatibility testing
  • JSON marshaling/unmarshaling validation

License

MIT License - see LICENSE for details.

Documentation

Index

Constants

View Source
const (
	Nanosecond  Duration = Duration(time.Nanosecond)
	Microsecond          = Duration(time.Microsecond)
	Millisecond          = Duration(time.Millisecond)
	Second               = Duration(time.Second)
	Minute               = Duration(time.Minute)
	Hour                 = Duration(time.Hour)
)

Duration constants

Variables

View Source
var (
	ErrInvalidScan         = errors.New("invalid field scan")
	ErrInvalidScanValue    = errors.New("invalid field scan value")
	ErrInvalidSetValue     = errors.New("invalid field set value")
	ErrNullValueNotAllowed = errors.New("nil value not allowed")
	ErrInvalidDecodeValue  = errors.New("invalid decode value")
)

Set of errors

Functions

func ArrayNumberDecode

func ArrayNumberDecode[T Number](data any, begin, end byte) (result []T, err error)

ArrayNumberDecode decodes array of type int

func ArrayNumberEncode

func ArrayNumberEncode[T Number](begin, end byte, arr []T) *bytes.Buffer

ArrayEncode encodes array of type int

Types

type Char

type Char rune

Char type of field

func (Char) MarshalJSON

func (f Char) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (*Char) Scan

func (f *Char) Scan(value any) (err error)

Scan implements the sql.Scanner interface, char field

func (*Char) UnmarshalJSON

func (f *Char) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements the json.Unmarshaller

func (Char) Value

func (f Char) Value() (driver.Value, error)

Value implements the driver.Valuer interface, char field

type Duration added in v2.1.0

type Duration time.Duration

Duration is a wrapper around time.Duration that allows us to

func ParseDuration added in v2.1.0

func ParseDuration(s string) (Duration, error)

ParseDuration parses a duration string.

func (Duration) Abs added in v2.1.0

func (d Duration) Abs() Duration

Abs returns the absolute value of d. As a special case, math.MinInt64 is converted to math.MaxInt64.

func (Duration) Duration added in v2.1.0

func (d Duration) Duration() time.Duration

Duration returns the time.Duration value.

func (Duration) Hours added in v2.1.0

func (d Duration) Hours() float64

Hours returns the duration as a floating point number of hours.

func (Duration) MarshalJSON added in v2.1.0

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

MarshalJSON implements the json.Marshaler interface.

func (Duration) Microseconds added in v2.1.0

func (d Duration) Microseconds() int64

Microseconds returns the duration as an integer microsecond count.

func (Duration) Milliseconds added in v2.1.0

func (d Duration) Milliseconds() int64

Milliseconds returns the duration as an integer millisecond count.

func (Duration) Minutes added in v2.1.0

func (d Duration) Minutes() float64

Minutes returns the duration as a floating point number of minutes.

func (Duration) Nanoseconds added in v2.1.0

func (d Duration) Nanoseconds() int64

Nanoseconds returns the duration as an integer nanosecond count.

func (Duration) Round added in v2.1.0

func (d Duration) Round(m Duration) Duration

Round returns the result of rounding d to the nearest multiple of m. The rounding behavior for halfway values is to round away from zero. If the result exceeds the maximum (or minimum) value that can be stored in a Duration, Round returns the maximum (or minimum) duration. If m <= 0, Round returns d unchanged.

func (*Duration) Scan added in v2.1.0

func (d *Duration) Scan(value any) error

Scan implements the Scanner interface.

func (Duration) Seconds added in v2.1.0

func (d Duration) Seconds() float64

Seconds returns the duration as a floating point number of seconds.

func (Duration) String added in v2.1.0

func (d Duration) String() string

String implements the Stringer interface.

func (Duration) Truncate added in v2.1.0

func (d Duration) Truncate(m Duration) Duration

Truncate returns the result of rounding d toward zero to a multiple of m. If m <= 0, Truncate returns d unchanged.

func (*Duration) UnmarshalJSON added in v2.1.0

func (d *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (Duration) Value added in v2.1.0

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

Value implements the driver Valuer interface.

type JSON

type JSON[T any] struct {
	Data T
}

JSON field

func MustJSON added in v2.2.0

func MustJSON[T any](val any) *JSON[T]

MustJSON creates new JSON object

func NewJSON

func NewJSON[T any](val any) (*JSON[T], error)

NewJSON creates new JSON object

func (*JSON[T]) DecodeValue

func (f *JSON[T]) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (JSON[T]) MarshalJSON

func (f JSON[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (*JSON[T]) Scan

func (f *JSON[T]) Scan(value any) error

Scan implements the driver.Valuer interface, json field interface

func (*JSON[T]) SetValue

func (f *JSON[T]) SetValue(value any) error

SetValue of json

func (*JSON[T]) String

func (f *JSON[T]) String() string

String value

func (*JSON[T]) UnmarshalJSON

func (f *JSON[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (JSON[T]) Value

func (f JSON[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface, json field interface

type JSONArray added in v2.3.0

type JSONArray[T any] []T

func MustJSONArray added in v2.3.0

func MustJSONArray[T any](val any) JSONArray[T]

MustJSONArray creates new JSONArray object

func NewJSONArray added in v2.3.0

func NewJSONArray[T any](val any) (JSONArray[T], error)

NewJSONArray creates new JSONArray object

func (*JSONArray[T]) DecodeValue added in v2.3.0

func (f *JSONArray[T]) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (JSONArray[T]) MarshalJSON added in v2.3.0

func (f JSONArray[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (*JSONArray[T]) Scan added in v2.3.0

func (f *JSONArray[T]) Scan(value any) error

Scan implements the driver.Valuer interface, []T field

func (*JSONArray[T]) SetValue added in v2.3.0

func (f *JSONArray[T]) SetValue(value any) error

SetValue of json

func (JSONArray[T]) String added in v2.3.0

func (f JSONArray[T]) String() string

String value

func (*JSONArray[T]) UnmarshalJSON added in v2.3.0

func (f *JSONArray[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (JSONArray[T]) Value added in v2.3.0

func (f JSONArray[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface, []T field

type NullableJSON

type NullableJSON[T any] struct {
	Data *T
}

NullableJSON field

func MustNullableJSON added in v2.2.0

func MustNullableJSON[T any](val any) *NullableJSON[T]

MustNullableJSON creates new JSON object

func NewNullableJSON

func NewNullableJSON[T any](val any) (*NullableJSON[T], error)

NewNullableJSON creates new JSON object

func (*NullableJSON[T]) DataOr added in v2.2.2

func (f *NullableJSON[T]) DataOr(def T) T

DataOr returns data or default value

func (*NullableJSON[T]) DecodeValue

func (f *NullableJSON[T]) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (NullableJSON[T]) MarshalJSON

func (f NullableJSON[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (*NullableJSON[T]) Scan

func (f *NullableJSON[T]) Scan(value any) error

Scan implements the driver.Valuer interface, json field interface

func (*NullableJSON[T]) SetValue

func (f *NullableJSON[T]) SetValue(value any) error

SetValue of json

func (*NullableJSON[T]) String

func (f *NullableJSON[T]) String() string

String value

func (*NullableJSON[T]) UnmarshalJSON

func (f *NullableJSON[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (NullableJSON[T]) Value

func (f NullableJSON[T]) Value() (_ driver.Value, err error)

Value implements the driver.Valuer interface, json field interface

type NullableJSONArray added in v2.3.0

type NullableJSONArray[T any] JSONArray[T]

NullableJSONArray object

func MustNullableJSONArray added in v2.3.0

func MustNullableJSONArray[T any](val any) NullableJSONArray[T]

MustNullableJSONArray creates new NullableJSONArray object

func NewNullableJSONArray added in v2.3.0

func NewNullableJSONArray[T any](val any) (NullableJSONArray[T], error)

NewNullableJSONArray creates new NullableJSONArray object

func (*NullableJSONArray[T]) DecodeValue added in v2.3.0

func (f *NullableJSONArray[T]) DecodeValue(v any) error

DecodeValue of the object

func (NullableJSONArray[T]) MarshalJSON added in v2.3.0

func (f NullableJSONArray[T]) MarshalJSON() ([]byte, error)

MarshalJSON data

func (*NullableJSONArray[T]) Scan added in v2.3.0

func (f *NullableJSONArray[T]) Scan(value any) error

Scan value from database

func (*NullableJSONArray[T]) SetValue added in v2.3.0

func (f *NullableJSONArray[T]) SetValue(value any) error

SetValue of json

func (NullableJSONArray[T]) String added in v2.3.0

func (f NullableJSONArray[T]) String() string

String value

func (*NullableJSONArray[T]) UnmarshalJSON added in v2.3.0

func (f *NullableJSONArray[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON data

func (NullableJSONArray[T]) Value added in v2.3.0

func (f NullableJSONArray[T]) Value() (driver.Value, error)

Value of the object

type NullableNumberArray

type NullableNumberArray[T Number] []T

NullableNumberArray type of field

func (*NullableNumberArray[T]) DecodeValue

func (f *NullableNumberArray[T]) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (NullableNumberArray[T]) Filter

func (f NullableNumberArray[T]) Filter(fn func(v T) bool) NullableNumberArray[T]

Filter current array and create filtered copy

func (NullableNumberArray[T]) IndexOf

func (f NullableNumberArray[T]) IndexOf(v T) int

IndexOf array value

func (NullableNumberArray[T]) Len

func (s NullableNumberArray[T]) Len() int

Len of array

func (NullableNumberArray[T]) Less

func (s NullableNumberArray[T]) Less(i, j int) bool

func (NullableNumberArray[T]) Map

func (f NullableNumberArray[T]) Map(fn func(v T) (T, bool)) NullableNumberArray[T]

Map transforms every value into the target

func (NullableNumberArray[T]) MarshalJSON

func (f NullableNumberArray[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (NullableNumberArray[T]) OneOf

func (f NullableNumberArray[T]) OneOf(vals []T) bool

OneOf value in array

func (NullableNumberArray[T]) Ordered

Ordered object

func (*NullableNumberArray[T]) Scan

func (f *NullableNumberArray[T]) Scan(value any) error

Scan implements the driver.Valuer interface, []int field

func (NullableNumberArray[T]) Sort

Sort ints array

func (NullableNumberArray[T]) Swap

func (s NullableNumberArray[T]) Swap(i, j int)

func (*NullableNumberArray[T]) UnmarshalJSON

func (f *NullableNumberArray[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (NullableNumberArray[T]) Value

func (f NullableNumberArray[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface, []int field

type NullableOrderedNumberArray

type NullableOrderedNumberArray[T Number] []T

NullableOrderedNumberArray[T Number] type of field

func (*NullableOrderedNumberArray[T]) DecodeValue

func (f *NullableOrderedNumberArray[T]) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (NullableOrderedNumberArray[T]) Filter

func (f NullableOrderedNumberArray[T]) Filter(fn func(v T) bool) NullableOrderedNumberArray[T]

Filter current array and create filtered copy

func (NullableOrderedNumberArray[T]) IndexOf

func (f NullableOrderedNumberArray[T]) IndexOf(v T) int

IndexOf array value

func (NullableOrderedNumberArray[T]) Len

func (s NullableOrderedNumberArray[T]) Len() int

Len of array

func (NullableOrderedNumberArray[T]) Less

func (s NullableOrderedNumberArray[T]) Less(i, j int) bool

func (NullableOrderedNumberArray[T]) Map

func (f NullableOrderedNumberArray[T]) Map(fn func(v T) (T, bool)) NullableOrderedNumberArray[T]

Map transforms every value into the target

func (NullableOrderedNumberArray[T]) MarshalJSON

func (f NullableOrderedNumberArray[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (NullableOrderedNumberArray[T]) OneOf

func (f NullableOrderedNumberArray[T]) OneOf(vals []T) bool

OneOf value in array

func (*NullableOrderedNumberArray[T]) Scan

func (f *NullableOrderedNumberArray[T]) Scan(value any) error

Scan implements the driver.Valuer interface, []int field

func (NullableOrderedNumberArray[T]) Sort

Sort ints array

func (NullableOrderedNumberArray[T]) Swap

func (s NullableOrderedNumberArray[T]) Swap(i, j int)

func (*NullableOrderedNumberArray[T]) UnmarshalJSON

func (f *NullableOrderedNumberArray[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (NullableOrderedNumberArray[T]) Value

func (f NullableOrderedNumberArray[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface, []int field

type NullableStringArray

type NullableStringArray []string

NullableStringArray implementation

func (*NullableStringArray) DecodeValue

func (f *NullableStringArray) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (NullableStringArray) IndexOf

func (f NullableStringArray) IndexOf(v string) int

IndexOf array value

func (NullableStringArray) Join

func (f NullableStringArray) Join(sep string) string

Join array to string

func (NullableStringArray) Len

func (f NullableStringArray) Len() int

Len of array

func (NullableStringArray) MarshalJSON

func (f NullableStringArray) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (NullableStringArray) OneOf

func (f NullableStringArray) OneOf(vals []string) bool

OneOf value in array

func (*NullableStringArray) Scan

func (f *NullableStringArray) Scan(value any) error

Scan implements the driver.Valuer interface, []string field

func (*NullableStringArray) SetArray

func (f *NullableStringArray) SetArray(arr []string) *NullableStringArray

SetArray value

func (*NullableStringArray) UnmarshalJSON

func (f *NullableStringArray) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (NullableStringArray) Value

func (f NullableStringArray) Value() (driver.Value, error)

Value implements the driver.Valuer interface, []string field

type Number

type Number interface {
	constraints.Integer | constraints.Float
}

Number general type

type NumberArray

type NumberArray[T Number] []T

NumberArray[T Number] type of field

func (*NumberArray[T]) DecodeValue

func (f *NumberArray[T]) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (NumberArray[T]) Filter

func (f NumberArray[T]) Filter(fn func(v T) bool) NumberArray[T]

Filter current NumberArray and create filtered copy

func (NumberArray[T]) IndexOf

func (f NumberArray[T]) IndexOf(v T) int

IndexOf NumberArray value

func (NumberArray[T]) Len

func (s NumberArray[T]) Len() int

Len of NumberArray

func (NumberArray[T]) Less

func (s NumberArray[T]) Less(i, j int) bool

func (NumberArray[T]) Map

func (f NumberArray[T]) Map(fn func(v T) (T, bool)) NumberArray[T]

Map transforms every value into the target

func (NumberArray[T]) MarshalJSON

func (f NumberArray[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (NumberArray[T]) OneOf

func (f NumberArray[T]) OneOf(vals []T) bool

OneOf value in NumberArray

func (NumberArray[T]) Ordered

func (f NumberArray[T]) Ordered() OrderedNumberArray[T]

Ordered object

func (*NumberArray[T]) Scan

func (f *NumberArray[T]) Scan(value any) error

Scan implements the driver.Valuer interface, []int field

func (NumberArray[T]) Sort

func (f NumberArray[T]) Sort() NumberArray[T]

Sort ints NumberArray

func (NumberArray[T]) Swap

func (s NumberArray[T]) Swap(i, j int)

func (*NumberArray[T]) UnmarshalJSON

func (f *NumberArray[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (NumberArray[T]) Value

func (f NumberArray[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface, []int field

type OrderedNumberArray

type OrderedNumberArray[T Number] []T

OrderedNumberArray type of field

func (*OrderedNumberArray[T]) DecodeValue

func (f *OrderedNumberArray[T]) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (OrderedNumberArray[T]) Filter

func (f OrderedNumberArray[T]) Filter(fn func(v T) bool) OrderedNumberArray[T]

Filter current array and create filtered copy

func (OrderedNumberArray[T]) IndexOf

func (f OrderedNumberArray[T]) IndexOf(v T) int

IndexOf array value

func (OrderedNumberArray[T]) Len

func (s OrderedNumberArray[T]) Len() int

Len of array

func (OrderedNumberArray[T]) Less

func (s OrderedNumberArray[T]) Less(i, j int) bool

func (OrderedNumberArray[T]) Map

func (f OrderedNumberArray[T]) Map(fn func(v T) (T, bool)) OrderedNumberArray[T]

Map transforms every value into the target

func (OrderedNumberArray[T]) MarshalJSON

func (f OrderedNumberArray[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler

func (OrderedNumberArray[T]) OneOf

func (f OrderedNumberArray[T]) OneOf(vals []T) bool

OneOf value in array

func (*OrderedNumberArray[T]) Scan

func (f *OrderedNumberArray[T]) Scan(value any) error

Scan implements the driver.Valuer interface, []int field

func (OrderedNumberArray[T]) Sort

func (f OrderedNumberArray[T]) Sort() OrderedNumberArray[T]

Sort ints array

func (OrderedNumberArray[T]) Swap

func (s OrderedNumberArray[T]) Swap(i, j int)

func (*OrderedNumberArray[T]) UnmarshalJSON

func (f *OrderedNumberArray[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (OrderedNumberArray[T]) Value

func (f OrderedNumberArray[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface, []int field

type StringArray

type StringArray NullableStringArray

StringArray implementation

func (*StringArray) DecodeValue

func (f *StringArray) DecodeValue(v any) error

DecodeValue implements the gocast.Decoder

func (StringArray) IndexOf

func (f StringArray) IndexOf(v string) int

IndexOf array value

func (StringArray) Join

func (f StringArray) Join(sep string) string

Join array to string

func (StringArray) Len

func (f StringArray) Len() int

Len of array

func (StringArray) OneOf

func (f StringArray) OneOf(vals []string) bool

OneOf value in array

func (*StringArray) Scan

func (f *StringArray) Scan(value any) error

Scan implements the driver.Valuer interface, []string field

func (*StringArray) SetArray

func (f *StringArray) SetArray(arr []string) *StringArray

SetArray value

func (*StringArray) UnmarshalJSON

func (f *StringArray) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaller

func (StringArray) Value

func (f StringArray) Value() (driver.Value, error)

Value implements the driver.Valuer interface, []string field

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL