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 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]) Append(buf []byte) []byte
  • func (self Arr[A]) AppendInner(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 Rows

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 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 casting into `Arr`. Workaround for lack of type inference in type literals and casts.

func (Arr[A]) Append

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

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

func (Arr[A]) AppendInner

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

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

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 `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 Rows

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

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