Documentation ¶
Index ¶
- Constants
- Variables
- func CheckTxOptionsCompatibility(parent, child *sql.TxOptions, defaultIsolation sql.IsolationLevel) error
- func IgnoreStructField(string) string
- func IsNull(val any) bool
- func IsNullOrZero(val any) bool
- func IsOtherThanErrNoRows(err error) bool
- func IsolatedTransaction(parentConn Connection, opts *sql.TxOptions, txFunc func(tx Connection) error) (err error)
- func NextTransactionNo() uint64
- func ReplaceErrNoRows(err, replacement error) error
- func SanitizeString(s string) string
- func SanitizeStringTrimSpace(s string) string
- func ScanDriverValue(destPtr any, value driver.Value) error
- func Transaction(parentConn Connection, opts *sql.TxOptions, txFunc func(tx Connection) error) (err error)
- type AnyValue
- type ColumnFilter
- type ColumnFilterFunc
- type Config
- type Connection
- type ErrCheckViolation
- type ErrExclusionViolation
- type ErrForeignKeyViolation
- type ErrIntegrityConstraintViolation
- type ErrNotNullViolation
- type ErrRaisedException
- type ErrRestrictViolation
- type ErrUniqueViolation
- type FieldFlag
- type Logger
- type Nullable
- type OnNotifyFunc
- type OnUnlistenFunc
- type RowScanner
- type RowsScanner
- type StringScannable
- type StructFieldMapper
- type TaggedStructFieldMapping
- type Values
Constants ¶
const ( // ErrWithinTransaction is returned by methods // that are not allowed within DB transactions // when the DB connection is a transaction. ErrWithinTransaction sentinelError = "within a transaction" // ErrNotWithinTransaction is returned by methods // that are are only allowed within DB transactions // when the DB connection is not a transaction. ErrNotWithinTransaction sentinelError = "not within a transaction" ErrNullValueNotAllowed sentinelError = "null value not allowed" )
Variables ¶
var DefaultStructFieldMapping = NewTaggedStructFieldMapping()
DefaultStructFieldMapping provides the default StructFieldTagNaming using "db" as NameTag and IgnoreStructField as UntaggedNameFunc. Implements StructFieldMapper.
var ToSnakeCase = strutil.ToSnakeCase
ToSnakeCase converts s to snake case by lower casing everything and inserting '_' before every new upper case character in s. Whitespace, symbol, and punctuation characters will be replace by '_'.
Functions ¶
func CheckTxOptionsCompatibility ¶
func CheckTxOptionsCompatibility(parent, child *sql.TxOptions, defaultIsolation sql.IsolationLevel) error
CheckTxOptionsCompatibility returns an error if the parent transaction options are less strict than the child options.
func IgnoreStructField ¶
IgnoreStructField can be used as TaggedStructFieldMapping.UntaggedNameFunc to ignore fields that don't have TaggedStructFieldMapping.NameTag.
func IsNull ¶
IsNull returns if val would be interpreted as NULL by a SQL driver. It checks if val is nil, implements driver.Valuer or is a nil pointer, slice, or map.
func IsNullOrZero ¶
IsNullOrZero returns if val would be interpreted as NULL by a SQL driver or if it is the types zero value or if it implements interface{ IsZero() bool } returning true.
func IsOtherThanErrNoRows ¶
IsOtherThanErrNoRows returns true if the passed error is not nil and does not unwrap to, or is sql.ErrNoRows.
func IsolatedTransaction ¶
func IsolatedTransaction(parentConn Connection, opts *sql.TxOptions, txFunc func(tx Connection) error) (err error)
IsolatedTransaction executes txFunc within a database transaction that is passed in to txFunc as tx Connection. IsolatedTransaction returns all errors from txFunc or transaction commit errors happening after txFunc. If parentConn is already a transaction, a brand new transaction will begin on the parent's connection. Errors and panics from txFunc will rollback the transaction. Recovered panics are re-paniced and rollback errors after a panic are logged with ErrLogger.
func NextTransactionNo ¶
func NextTransactionNo() uint64
NextTransactionNo returns the next globally unique number for a new transaction in a threadsafe way.
Use Connection.TransactionNo() to get the number from a transaction connection.
func ReplaceErrNoRows ¶
ReplaceErrNoRows returns the passed replacement error if errors.Is(err, sql.ErrNoRows), else the passed err is returned unchanged.
func SanitizeString ¶
SanitizeString returns valid UTF-8 only with printable characters.
func SanitizeStringTrimSpace ¶
SanitizeStringTrimSpace returns valid UTF-8 only with printable characters with leading and trailing whitespace trimmed away.
func ScanDriverValue ¶
ScanDriverValue scans a driver.Value into destPtr.
func Transaction ¶
func Transaction(parentConn Connection, opts *sql.TxOptions, txFunc func(tx Connection) error) (err error)
Transaction executes txFunc within a database transaction that is passed in to txFunc as tx Connection. Transaction returns all errors from txFunc or transaction commit errors happening after txFunc. If parentConn is already a transaction, then it is passed through to txFunc unchanged as tx Connection and no parentConn.Begin, Commit, or Rollback calls will occour within this Transaction call. An error is returned, if the requested transaction options passed via opts are stricter than the options of the parent transaction. Errors and panics from txFunc will rollback the transaction if parentConn was not already a transaction. Recovered panics are re-paniced and rollback errors after a panic are logged with ErrLogger.
Types ¶
type AnyValue ¶
type AnyValue struct {
Val any
}
AnyValue wraps a driver.Value and is useful for generic code that can handle unknown column types.
AnyValue implements the following interfaces:
database/sql.Scanner database/sql/driver.Valuer fmt.Stringer fmt.GoStringer
When scanned, Val can have one of the following underlying types:
int64 float64 bool []byte string time.Time nil - for NULL values
type ColumnFilter ¶
type ColumnFilter interface {
IgnoreColumn(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool
}
var IgnoreDefault ColumnFilter = ColumnFilterFunc(func(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool {
return flags.Default()
})
var IgnoreNull ColumnFilter = ColumnFilterFunc(func(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool { return IsNull(fieldValue) })
var IgnoreNullOrZero ColumnFilter = ColumnFilterFunc(func(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool { return IsNullOrZero(fieldValue) })
var IgnoreNullOrZeroDefault ColumnFilter = ColumnFilterFunc(func(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool { return flags.Default() && IsNullOrZero(fieldValue) })
var IgnorePrimaryKey ColumnFilter = ColumnFilterFunc(func(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool {
return flags.PrimaryKey()
})
var IgnoreReadOnly ColumnFilter = ColumnFilterFunc(func(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool {
return flags.ReadOnly()
})
func IgnoreColumns ¶
func IgnoreColumns(names ...string) ColumnFilter
func IgnoreFlags ¶
func IgnoreFlags(ignore FieldFlag) ColumnFilter
func IgnoreStructFields ¶
func IgnoreStructFields(names ...string) ColumnFilter
func OnlyColumns ¶
func OnlyColumns(names ...string) ColumnFilter
func OnlyStructFields ¶
func OnlyStructFields(names ...string) ColumnFilter
type ColumnFilterFunc ¶
type ColumnFilterFunc func(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool
func (ColumnFilterFunc) IgnoreColumn ¶
func (f ColumnFilterFunc) IgnoreColumn(name string, flags FieldFlag, fieldType reflect.StructField, fieldValue reflect.Value) bool
type Config ¶
type Config struct { Driver string `json:"driver"` Host string `json:"host"` Port uint16 `json:"port,omitempty"` User string `json:"user,omitempty"` Password string `json:"password,omitempty"` Database string `json:"database"` Extra map[string]string `json:"misc,omitempty"` // MaxOpenConns sets the maximum number of open connections to the database. // // If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than // MaxIdleConns, then MaxIdleConns will be reduced to match the new // MaxOpenConns limit. // // If MaxOpenConns <= 0, then there is no limit on the number of open connections. // The default is 0 (unlimited). MaxOpenConns int `json:"maxOpenConns,omitempty"` // MaxIdleConns sets the maximum number of connections in the idle // connection pool. // // If MaxOpenConns is greater than 0 but less than the new MaxIdleConns, // then the new MaxIdleConns will be reduced to match the MaxOpenConns limit. // // If MaxIdleConns <= 0, no idle connections are retained. // // The default max idle connections is currently 2. This may change in // a future release. MaxIdleConns int `json:"maxIdleConns,omitempty"` // ConnMaxLifetime sets the maximum amount of time a connection may be reused. // // Expired connections may be closed lazily before reuse. // // If ConnMaxLifetime <= 0, connections are not closed due to a connection's age. ConnMaxLifetime time.Duration `json:"connMaxLifetime,omitempty"` DefaultIsolationLevel sql.IsolationLevel `json:"-"` Err error `json:"-"` }
Config for a connection. For tips see https://www.alexedwards.net/blog/configuring-sqldb
func (*Config) Connect ¶
Connect opens a new sql.DB connection, sets all Config values and performs a ping with ctx. The sql.DB will be returned if the ping was successful.
func (*Config) ConnectURL ¶
ConnectURL for connecting to a database
type Connection ¶
type Connection interface { // Context that all connection operations use. // See also WithContext. Context() context.Context // WithContext returns a connection that uses the passed // context for its operations. WithContext(ctx context.Context) Connection // WithStructFieldMapper returns a copy of the connection // that will use the passed StructFieldMapper. WithStructFieldMapper(StructFieldMapper) Connection // StructFieldMapper used by methods of this Connection. StructFieldMapper() StructFieldMapper // Ping returns an error if the database // does not answer on this connection // with an optional timeout. // The passed timeout has to be greater zero // to be considered. Ping(timeout time.Duration) error // Stats returns the sql.DBStats of this connection. Stats() sql.DBStats // Config returns the configuration used // to create this connection. Config() *Config // ValidateColumnName returns an error // if the passed name is not valid for a // column of the connection's database. ValidateColumnName(name string) error // Now returns the result of the SQL now() // function for the current connection. // Useful for getting the timestamp of a // SQL transaction for use in Go code. Now() (time.Time, error) // Exec executes a query with optional args. Exec(query string, args ...any) error // Insert a new row into table using the values. Insert(table string, values Values) error // InsertUnique inserts a new row into table using the passed values // or does nothing if the onConflict statement applies. // Returns if a row was inserted. InsertUnique(table string, values Values, onConflict string) (inserted bool, err error) // InsertReturning inserts a new row into table using values // and returns values from the inserted row listed in returning. InsertReturning(table string, values Values, returning string) RowScanner // InsertStruct inserts a new row into table using the connection's // StructFieldMapper to map struct fields to column names. // Optional ColumnFilter can be passed to ignore mapped columns. InsertStruct(table string, rowStruct any, ignoreColumns ...ColumnFilter) error // InsertStructs inserts a slice or array of structs // as new rows into table using the connection's // StructFieldMapper to map struct fields to column names. // Optional ColumnFilter can be passed to ignore mapped columns. // // TODO optimized version with single query if possible // split into multiple queries depending or maxArgs for query InsertStructs(table string, rowStructs any, ignoreColumns ...ColumnFilter) error // InsertUniqueStruct inserts a new row into table using the connection's // StructFieldMapper to map struct fields to column names. // Optional ColumnFilter can be passed to ignore mapped columns. // Does nothing if the onConflict statement applies // and returns if a row was inserted. InsertUniqueStruct(table string, rowStruct any, onConflict string, ignoreColumns ...ColumnFilter) (inserted bool, err error) // Update table rows(s) with values using the where statement with passed in args starting at $1. Update(table string, values Values, where string, args ...any) error // UpdateReturningRow updates a table row with values using the where statement with passed in args starting at $1 // and returning a single row with the columns specified in returning argument. UpdateReturningRow(table string, values Values, returning, where string, args ...any) RowScanner // UpdateReturningRows updates table rows with values using the where statement with passed in args starting at $1 // and returning multiple rows with the columns specified in returning argument. UpdateReturningRows(table string, values Values, returning, where string, args ...any) RowsScanner // UpdateStruct updates a row in a table using the exported fields // of rowStruct which have a `db` tag that is not "-". // If restrictToColumns are provided, then only struct fields with a `db` tag // matching any of the passed column names will be used. // The struct must have at least one field with a `db` tag value having a ",pk" suffix // to mark primary key column(s). UpdateStruct(table string, rowStruct any, ignoreColumns ...ColumnFilter) error // UpsertStruct upserts a row to table using the exported fields // of rowStruct which have a `db` tag that is not "-". // If restrictToColumns are provided, then only struct fields with a `db` tag // matching any of the passed column names will be used. // The struct must have at least one field with a `db` tag value having a ",pk" suffix // to mark primary key column(s). // If inserting conflicts on the primary key column(s), then an update is performed. UpsertStruct(table string, rowStruct any, ignoreColumns ...ColumnFilter) error // QueryRow queries a single row and returns a RowScanner for the results. QueryRow(query string, args ...any) RowScanner // QueryRows queries multiple rows and returns a RowsScanner for the results. QueryRows(query string, args ...any) RowsScanner // IsTransaction returns if the connection is a transaction IsTransaction() bool // TransactionNo returns the globally unique number of the transaction // or zero if the connection is not a transaction. // Implementations should use the package function NextTransactionNo // to aquire a new number in a threadsafe way. TransactionNo() uint64 // TransactionOptions returns the sql.TxOptions of the // current transaction and true as second result value, // or false if the connection is not a transaction. TransactionOptions() (*sql.TxOptions, bool) // Begin a new transaction. // If the connection is already a transaction then a brand // new transaction will begin on the parent's connection. // The passed no will be returnd from the transaction's // Connection.TransactionNo method. // Implementations should use the package function NextTransactionNo // to aquire a new number in a threadsafe way. Begin(opts *sql.TxOptions, no uint64) (Connection, error) // Commit the current transaction. // Returns ErrNotWithinTransaction if the connection // is not within a transaction. Commit() error // Rollback the current transaction. // Returns ErrNotWithinTransaction if the connection // is not within a transaction. Rollback() error // ListenOnChannel will call onNotify for every channel notification // and onUnlisten if the channel gets unlistened // or the listener connection gets closed for some reason. // It is valid to pass nil for onNotify or onUnlisten to not get those callbacks. // Note that the callbacks are called in sequence from a single go routine, // so callbacks should offload long running or potentially blocking code to other go routines. // Panics from callbacks will be recovered and logged. ListenOnChannel(channel string, onNotify OnNotifyFunc, onUnlisten OnUnlistenFunc) error // UnlistenChannel will stop listening on the channel. // An error is returned, when the channel was not listened to // or the listener connection is closed. UnlistenChannel(channel string) error // IsListeningOnChannel returns if a channel is listened to. IsListeningOnChannel(channel string) bool // Close the connection. // Transactions will be rolled back. Close() error }
Connection represents a database connection or transaction
func ConnectionWithError ¶
func ConnectionWithError(ctx context.Context, err error) Connection
ConnectionWithError returns a dummy Connection where all methods return the passed error.
type ErrCheckViolation ¶
type ErrCheckViolation struct {
Constraint string
}
func (ErrCheckViolation) Error ¶
func (e ErrCheckViolation) Error() string
func (ErrCheckViolation) Unwrap ¶
func (e ErrCheckViolation) Unwrap() error
type ErrExclusionViolation ¶
type ErrExclusionViolation struct {
Constraint string
}
func (ErrExclusionViolation) Error ¶
func (e ErrExclusionViolation) Error() string
func (ErrExclusionViolation) Unwrap ¶
func (e ErrExclusionViolation) Unwrap() error
type ErrForeignKeyViolation ¶
type ErrForeignKeyViolation struct {
Constraint string
}
func (ErrForeignKeyViolation) Error ¶
func (e ErrForeignKeyViolation) Error() string
func (ErrForeignKeyViolation) Unwrap ¶
func (e ErrForeignKeyViolation) Unwrap() error
type ErrIntegrityConstraintViolation ¶
type ErrIntegrityConstraintViolation struct {
Constraint string
}
func (ErrIntegrityConstraintViolation) Error ¶
func (e ErrIntegrityConstraintViolation) Error() string
type ErrNotNullViolation ¶
type ErrNotNullViolation struct {
Constraint string
}
func (ErrNotNullViolation) Error ¶
func (e ErrNotNullViolation) Error() string
func (ErrNotNullViolation) Unwrap ¶
func (e ErrNotNullViolation) Unwrap() error
type ErrRaisedException ¶
type ErrRaisedException struct {
Message string
}
func (ErrRaisedException) Error ¶
func (e ErrRaisedException) Error() string
type ErrRestrictViolation ¶
type ErrRestrictViolation struct {
Constraint string
}
func (ErrRestrictViolation) Error ¶
func (e ErrRestrictViolation) Error() string
func (ErrRestrictViolation) Unwrap ¶
func (e ErrRestrictViolation) Unwrap() error
type ErrUniqueViolation ¶
type ErrUniqueViolation struct {
Constraint string
}
func (ErrUniqueViolation) Error ¶
func (e ErrUniqueViolation) Error() string
func (ErrUniqueViolation) Unwrap ¶
func (e ErrUniqueViolation) Unwrap() error
type FieldFlag ¶
type FieldFlag uint
FieldFlag is a bitmask for special properties of how struct fields relate to database columns.
func (FieldFlag) PrimaryKey ¶
PrimaryKey indicates if FieldFlagPrimaryKey is set
type Logger ¶
Logger has a Printf method used for logging information that could not be returned by any of the package functions directly.
type OnNotifyFunc ¶
type OnNotifyFunc func(channel, payload string)
OnNotifyFunc is a callback type passed to Connection.ListenOnChannel
type OnUnlistenFunc ¶
type OnUnlistenFunc func(channel string)
OnUnlistenFunc is a callback type passed to Connection.ListenOnChannel
type RowScanner ¶
type RowScanner interface { // Scan values of a row into dest variables, which must be passed as pointers. Scan(dest ...any) error // ScanStruct scans values of a row into a dest struct which must be passed as pointer. ScanStruct(dest any) error // ScanValues returns the values of a row exactly how they are // passed from the database driver to an sql.Scanner. // Byte slices will be copied. ScanValues() ([]any, error) // ScanStrings scans the values of a row as strings. // Byte slices will be interpreted as strings, // nil (SQL NULL) will be converted to an empty string, // all other types are converted with fmt.Sprint(src). ScanStrings() ([]string, error) // Columns returns the column names. Columns() ([]string, error) }
RowScanner scans the values from a single row.
func RowScannerWithError ¶
func RowScannerWithError(err error) RowScanner
RowScannerWithError returns a dummy RowScanner where all methods return the passed error.
type RowsScanner ¶
type RowsScanner interface { // ScanSlice scans one value per row into one slice element of dest. // dest must be a pointer to a slice with a row value compatible element type. // In case of zero rows, dest will be set to nil and no error will be returned. // In case of an error, dest will not be modified. // It is an error to query more than one column. ScanSlice(dest any) error // ScanStructSlice scans every row into the struct fields of dest slice elements. // dest must be a pointer to a slice of structs or struct pointers. // In case of zero rows, dest will be set to nil and no error will be returned. // In case of an error, dest will not be modified. // Every mapped struct field must have a corresponding column in the query results. ScanStructSlice(dest any) error // ScanAllRowsAsStrings scans the values of all rows as strings. // Byte slices will be interpreted as strings, // nil (SQL NULL) will be converted to an empty string, // all other types are converted with fmt.Sprint. // If true is passed for headerRow, then a row // with the column names will be prepended. ScanAllRowsAsStrings(headerRow bool) (rows [][]string, err error) // Columns returns the column names. Columns() ([]string, error) // ForEachRow will call the passed callback with a RowScanner for every row. // In case of zero rows, no error will be returned. ForEachRow(callback func(RowScanner) error) error // ForEachRowCall will call the passed callback with scanned values or a struct for every row. // If the callback function has a single struct or struct pointer argument, // then RowScanner.ScanStruct will be used per row, // else RowScanner.Scan will be used for all arguments of the callback. // If the function has a context.Context as first argument, // then the context of the query call will be passed on. // The callback can have no result or a single error result value. // If a non nil error is returned from the callback, then this error // is returned immediately by this function without scanning further rows. // In case of zero rows, no error will be returned. ForEachRowCall(callback any) error }
RowsScanner scans the values from multiple rows.
func RowsScannerWithError ¶
func RowsScannerWithError(err error) RowsScanner
RowsScannerWithError returns a dummy RowsScanner where all methods return the passed error.
type StringScannable ¶
type StringScannable string
StringScannable implements the sql.Scanner interface and converts all scanned values to string. Byte slices will be interpreted as strings, nil (SQL NULL) will be converted to an empty string, all other types are converted with fmt.Sprint(src).
func (*StringScannable) Scan ¶
func (s *StringScannable) Scan(src any) error
Scan implements implements the sql.Scanner interface and converts all scanned values to string. Byte slices will be interpreted as strings, nil (SQL NULL) will be converted to an empty string, all other types are converted with fmt.Sprint(src).
type StructFieldMapper ¶
type StructFieldMapper interface { // MapStructField returns the column name for a reflected struct field // and flags for special column properies. // If false is returned for use then the field is not mapped. // An empty name and true for use indicates an embedded struct // field whose fields should be recursively mapped. MapStructField(field reflect.StructField) (table, column string, flags FieldFlag, use bool) }
StructFieldMapper is used to map struct type fields to column names and indicate special column properies via flags.
type TaggedStructFieldMapping ¶
type TaggedStructFieldMapping struct { // NameTag is the struct field tag to be used as column name NameTag string // Ignore will cause a struct field to be ignored if it has that name Ignore string PrimaryKey string ReadOnly string Default string // UntaggedNameFunc will be called with the struct field name to // return a column name in case the struct field has no tag named NameTag. UntaggedNameFunc func(fieldName string) string // contains filtered or unexported fields }
TaggedStructFieldMapping implements StructFieldMapper with a struct field NameTag to be used for naming and a UntaggedNameFunc in case the NameTag is not set.
func NewTaggedStructFieldMapping ¶
func NewTaggedStructFieldMapping() *TaggedStructFieldMapping
NewTaggedStructFieldMapping returns a default mapping.
func (*TaggedStructFieldMapping) MapStructField ¶
func (m *TaggedStructFieldMapping) MapStructField(field reflect.StructField) (table, column string, flags FieldFlag, use bool)
func (TaggedStructFieldMapping) String ¶
func (n TaggedStructFieldMapping) String() string
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
gen-db-interface
Module
|
|
sqldb-dump
Module
|
|
examples
|
|
user_demo
Module
|
|
Package information contains structs and functions to query the information_schema.
|
Package information contains structs and functions to query the information_schema. |
mssqlconn
module
|
|
mysqlconn
module
|
|