gsql

README

Missing features of the Go standard library related to SQL:

• Support for scanning SQL rows into Go structs.

• Usable support for SQL arrays. Single-dimensional arrays are simple slices. Multi-dimensional arrays are nested slices. Everything is automatically compatible with other formats such as JSON.

• Various utility types compatible with both SQL and JSON.

API doc: https://pkg.go.dev/github.com/mitranim/gg/gsql

Documentation

Index

• Constants
• func DbTxDone[A DbTx](val A)
• func DbTxDoneWith[A DbTx](val A, err error)
• func ScanAny[Src Rows](src Src, out any)
• func ScanNext[Row any, Src ColumnerScanner](src Src) Row
• func ScanReflect[Src Rows](src Src, out r.Value)
• func ScanVal[Row any, Src Rows](src Src) Row
• func ScanVals[Row any, Src Rows](src Src) (out []Row)
• type Arr
  • func ArrOf[A any](val ...A) Arr[A]
  • func ToArr[A any](val []A) Arr[A]
  • func (self Arr[A]) AppendInner(buf []byte) []byte
  • func (self Arr[A]) AppendTo(buf []byte) []byte
  • func (self *Arr[A]) Clear()
  • func (self Arr[A]) IsNull() bool
  • func (self *Arr[A]) Parse(src string) (err error)
  • func (self *Arr[A]) Scan(src any) error
  • func (self Arr[A]) String() string
  • func (self Arr[A]) Value() (driver.Value, error)
• type ColumnerScanner
• type Db
• type DbConn
• type DbTx
• type DbTxer
• type Like
  • func (self Like) Esc() string
  • func (self *Like) Scan(src any) error
  • func (self Like) String() string
  • func (self Like) Value() (driver.Value, error)
• type Rows
• type Rune
  • func RuneFrom[A ~rune](val A) Rune
  • func (self Rune) AppendTo(buf []byte) []byte
  • func (self *Rune) Clear()
  • func (self Rune) IsNotNull() bool
  • func (self Rune) IsNull() bool
  • func (self Rune) MarshalJSON() ([]byte, error)
  • func (self Rune) MarshalText() ([]byte, error)
  • func (self *Rune) Parse(src string) error
  • func (self *Rune) Scan(src any) error
  • func (self Rune) String() string
  • func (self *Rune) UnmarshalJSON(src []byte) error
  • func (self *Rune) UnmarshalText(src []byte) error
  • func (self Rune) Value() (driver.Value, error)

Constants

const ErrMultipleRows gg.ErrStr = `expected one row, got multiple`

Returned by `ScanVal` and `ScanAny` when there are too many rows.

Functions

func DbTxDone

func DbTxDone[A DbTx](val A)

Must be deferred. Commit if there was no panic, rollback if there was a panic. Usage:

defer DbTxDone(conn)

func DbTxDoneWith

func DbTxDoneWith[A DbTx](val A, err error)

Commit if there was no error, rollback if there was an error. Used internally by `DbTxDone`.

func ScanAny

func ScanAny[Src Rows](src Src, out any)

Decodes `Rows` into the given dynamically typed output. Counterpart to `ScanVals` and `ScanVal` which are statically typed. Output must be a non-nil pointer to one of the following:

• Slice of scalars.
• Slice of structs.
• Single scalar.
• Single struct.

Always closes the rows. If output is not a slice, verifies that there is EXACTLY one row in total, otherwise panics.

func ScanNext

func ScanNext[Row any, Src ColumnerScanner](src Src) Row

Takes `Rows` and decodes the next row into a value of the given type. Output type must be either scalar or struct. Panics on errors. Must be called only after `Rows.Next`.

func ScanReflect

func ScanReflect[Src Rows](src Src, out r.Value)

Variant of `ScanAny` that takes a reflect value rather than `any`.

func ScanVal

func ScanVal[Row any, Src Rows](src Src) Row

Takes `Rows` and decodes the first row into a value of the given type, using `ScanNext` once. The rows must consist of EXACTLY one row, otherwise this panics. Output type must be either scalar or struct. Always closes the rows.

func ScanVals

func ScanVals[Row any, Src Rows](src Src) (out []Row)

Takes `Rows` and decodes them into a slice of the given type, using `ScanNext` for each row. Output type must be either scalar or struct. Always closes the rows.

Types

type Arr

type Arr[A any] []A

Short for "array". A slice type that supports SQL array encoding and decoding, using the `{}` format. Examples:

Arr[int]{10, 20}                  <-> '{10,20}'
Arr[Arr[int]]{{10, 20}, {30, 40}} <-> '{{10,20},{30,40}}'

func ArrOf

func ArrOf[A any](val ...A) Arr[A]

Shortcut for creating `Arr` from the arguments.

func ToArr

func ToArr[A any](val []A) Arr[A]

Shortcut for converting to `Arr`. Workaround for the lack of type inference in type literals and casts. This is a free cast with no reallocation.

func (Arr[A]) AppendInner

func (self Arr[A]) AppendInner(buf []byte) []byte

Same as `.AppenderTo` but without the enclosing `{}`.

func (Arr[A]) AppendTo

func (self Arr[A]) AppendTo(buf []byte) []byte

Implement `AppenderTo`, appending the array's SQL encoding to the buffer. If the slice is nil, appends nothing.

func (*Arr[A]) Clear

func (self *Arr[A]) Clear()

Truncates the length, keeping the capacity.

func (Arr[A]) IsNull

func (self Arr[A]) IsNull() bool

Implement `gg.Nullable`. True if the slice is nil.

func (*Arr[A]) Parse

func (self *Arr[A]) Parse(src string) (err error)

Decodes from an SQL array literal string. Supports nested arrays.

func (*Arr[A]) Scan

func (self *Arr[A]) Scan(src any) error

Implement `sql.Scanner`.

func (Arr[A]) String

func (self Arr[A]) String() string

Implement `fmt.Stringer`. Returns an SQL encoding of the array.

func (Arr[A]) Value

func (self Arr[A]) Value() (driver.Value, error)

Implement `driver.Valuer`.

type ColumnerScanner

type ColumnerScanner interface {
	Columns() ([]string, error)
	Scan(...any) error
}

Sub-interface of `Rows` used by `ScanNext`.

type Db

type Db interface {
	DbConn
	DbTxer
}

Implemented by stdlib types such as `sql.DB`.

type DbConn

type DbConn interface {
	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
	ExecContext(context.Context, string, ...any) (sql.Result, error)
}

Implemented by stdlib types such as `sql.Conn` and `sql.Tx`.

type DbTx

type DbTx interface {
	DbConn
	Commit() error
	Rollback() error
}

Implemented by stdlib types such as `sql.Tx`.

type DbTxer

type DbTxer interface {
	BeginTx(context.Context, *sql.TxOptions) (*sql.Tx, error)
}

Implemented by stdlib types such as `sql.DB`.

type Like

type Like string

Variant of `string` intended as an operand for SQL "like" and "ilike" operators. When generating an SQL argument via `.Value`, the string is wrapped in `%` to ensure partial match, escaping any pre-existing `%` and `_`. As a special case, an empty string is used as-is, and doesn't match anything when used with `like` or `ilike`.

func (Like) Esc

func (self Like) Esc() string

Returns an escaped string suitable as an operand for SQL "like" or "ilike". As a special case, an empty string is returned as-is.

func (*Like) Scan

func (self *Like) Scan(src any) error

Implement `sql.Scanner`.

func (Like) String

func (self Like) String() string

Implement `fmt.Stringer`. Returns the underlying string unchanged.

func (Like) Value

func (self Like) Value() (driver.Value, error)

Implement `driver.Valuer`, returning the escaped string from `.Esc`.

type Rows

type Rows interface {
	io.Closer
	gg.Errer
	gg.Nexter
	ColumnerScanner
}

Interface of `sql.Rows`. Used by various scanning tools.

type Rune

type Rune rune

Variant of Go `rune` compatible with text, JSON, and SQL (with caveats). In text and JSON, behaves like `string`. In Go and SQL, behaves like `rune`/`int32`. As a special case, zero value is considered empty in text, and null in JSON and SQL. When parsing, input must be empty or single char.

Some databases, or their Go drivers, may not support representing chars as int32. For example, Postgres doesn't have an analog of Go `rune`. Its "char" type is a variable-sized string. This type is not compatible with such databases.

func RuneFrom

func RuneFrom[A ~rune](val A) Rune

Shortcut for casting an arbitrary rune-like into `Rune`. Useful for higher-order functions such as `gg.Map`.

func (Rune) AppendTo

func (self Rune) AppendTo(buf []byte) []byte

Implement `AppenderTo`, appending the same representation as `.String`.

func (*Rune) Clear

func (self *Rune) Clear()

Implement `Clearer`. Zeroes the receiver.

func (Rune) IsNotNull

func (self Rune) IsNotNull() bool

Inverse of `.IsNull`.

func (Rune) IsNull

func (self Rune) IsNull() bool

Implement `gg.Nullable`. True if zero value.

func (Rune) MarshalJSON

func (self Rune) MarshalJSON() ([]byte, error)

Implement `json.Marshaler`. If `.IsNull`, returns a representation of JSON null. Otherwise uses an equivalent of `json.Marshal(self.String())`.

func (Rune) MarshalText

func (self Rune) MarshalText() ([]byte, error)

Implement `encoding.TextMarshaler`, returning the same representation as `.String`.

func (*Rune) Parse

func (self *Rune) Parse(src string) error

Implement `Parser`. If the input is empty, clears the receiver via `.Clear`. If the input has more than one character, returns an error. Otherwise uses the first and only character from the input.

func (*Rune) Scan

func (self *Rune) Scan(src any) error

Implement SQL `Scanner`, decoding arbitrary input, which must be one of:

• Nil -> use `.Clear`.
• Text -> use `.Parse`.
• Rune -> assign as-is.

func (Rune) String

func (self Rune) String() string

Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise returns a string containing exactly one character.

func (*Rune) UnmarshalJSON

func (self *Rune) UnmarshalJSON(src []byte) error

Implement `json.Unmarshaler`. If the input is empty or represents JSON null, clears the receiver via `.Clear`. Otherwise requires the input to be a JSON string and decodes it via `.Parse`.

func (*Rune) UnmarshalText

func (self *Rune) UnmarshalText(src []byte) error

Implement `encoding.TextUnmarshaler`, using the same logic as `.Parse`.

func (Rune) Value

func (self Rune) Value() (driver.Value, error)

Implement SQL `driver.Valuer`. If `.IsNull`, returns nil. Otherwise returns rune.