xmysql

README

xmysql - MySQL Utilities for Go

Copyright (c) 2022, 2023, Geert JM Vanderkelen

The Go xmysql package offers functionality for MySQL.
For example, to create and drop a schema you could use respectively CreateSchema() and DropSchema().

This package is SQL driver agnostic as long as MySQL is used. Both Go MySQL Driver, using the conventional protocol, and Go MySQL Driver using X Protocol will work.

License

Distributed under the MIT license. See LICENSE.md for more information.

Documentation

Index

• Constants
• func CreateSchema(db *sql.DB, name string) error
• func CurrentSchema(db *sql.DB) (string, error)
• func DisableGeneralLog(db *sql.DB) error
• func DropSchema(db *sql.DB, name string) error
• func EnableGeneralLog(db *sql.DB) error
• func ErrorIs(err error, number int) bool
• func FlushGeneralLog(db *sql.DB) error
• func GeneralQueryLogEnabled(db *sql.DB) (bool, error)
• func GlobalVariable(db *sql.DB, name string) (string, error)
• func IsDBCreateExists(err error) bool
• func MaskPasswordInDSN(dsn string) string
• func MustSQLw(statement string, keyValuePairs ...string) string
• func ReplaceDSNDatabase(dsn string, name string) (string, error)
• func SQLw(statement string, keyValuePairs ...string) (string, error)
• func SchemaExists(db *sql.DB, name string) (bool, error)
• func SetDSNParams(dsn string, parameters map[string]string) (string, error)
• func SetLogOutput(db *sql.DB, outputs ...LogOutput) error
• func SetTableComment(db *sql.DB, table string, comment string, schema ...string) error
• func SetTableCommentJSON(db *sql.DB, table string, comment any, schema ...string) error
• func TableComment(db *sql.DB, table string, schema ...string) (string, error)
• func TableCommentJSON(db *sql.DB, table string, dest any, schema ...string) error
• func TableExists(db *sql.DB, name string) (bool, error)
• type Error
  • func ErrorTxBegin(err error) Error
  • func ErrorTxCommit(err error) Error
  • func NewError(err error) Error
  • func NewErrorQuery(err error, query string, values []any) Error
  • func NewErrorSprintf(err error, format string, a ...any) Error
  • func (e Error) Error() string
• type GeneralLogEvent
  • func GetGeneralLogEvents(db *sql.DB, argLike string, limit int) ([]*GeneralLogEvent, error)
• type LogOutput

Constants

const (
	ErrDBCreateExists    int = 1007
	ErrDBDropExists      int = 1008
	ErrDubEntry          int = 1062
	ErrClientConnRefused int = 2005
)

Error numbers of MySQL handled by this package.

Functions

func CreateSchema

func CreateSchema(db *sql.DB, name string) error

CreateSchema creates schema (or database) using the already open connection db.

When error is returned, it is of type xmysql.Error.

func CurrentSchema

func CurrentSchema(db *sql.DB) (string, error)

CurrentSchema returns the name of the current schema of db.

func DisableGeneralLog

func DisableGeneralLog(db *sql.DB) error

DisableGeneralLog turns off the General Log.

func DropSchema

func DropSchema(db *sql.DB, name string) error

DropSchema drops schema (or database) using the already open connection db.

When error is returned, it is of type xmysql.Error.

func EnableGeneralLog

func EnableGeneralLog(db *sql.DB) error

EnableGeneralLog turns on the General Log. Since all queries are logged, it is recommended not doing this on a production instance.

func ErrorIs

func ErrorIs(err error, number int) bool

ErrorIs returns whether err matches the MySQL Server Error number.

func FlushGeneralLog

func FlushGeneralLog(db *sql.DB) error

FlushGeneralLog will flush the general log file and truncate the general_log table. During these operations, the genera log is disabled, and enabled again after when it was enabled before.

func GeneralQueryLogEnabled

func GeneralQueryLogEnabled(db *sql.DB) (bool, error)

GeneralQueryLogEnabled turns whether the General Query Log is enabled. Since all queries are logged, it is recommended not doing this on a production instance.

func GlobalVariable

func GlobalVariable(db *sql.DB, name string) (string, error)

GlobalVariable returns value of a global variable by its name.

func IsDBCreateExists

func IsDBCreateExists(err error) bool

IsDBCreateExists returns whether err is Error and ErrDBCreateExists.

func MaskPasswordInDSN

func MaskPasswordInDSN(dsn string) string

MaskPasswordInDSN masks the password within the MySQL data source name dsn. This function is usually used when displaying or logging the DSN.

When password is empty (not provided) the mask is added anyway. When the DSN is something that was not a DSN, the mask itself is returned to prevent possible mistakes. Deprecated: use github.com/golistic/xgo/xsql

func MustSQLw

func MustSQLw(statement string, keyValuePairs ...string) string

MustSQLw calls SQLw but instead of returning errors, it panics.

func ReplaceDSNDatabase

func ReplaceDSNDatabase(dsn string, name string) (string, error)

ReplaceDSNDatabase takes dsn and replaces the database name. It returns the new Data Source Name. Deprecated: use github.com/golistic/xgo/xsql

func SQLw

func SQLw(statement string, keyValuePairs ...string) (string, error)

SQLw takes the SQL statement and substitutes the key/value pairs using the placeholder format `$(key)`. For example, executing `SQLw("SELECT c1 FROM $(tblName)", tblName, "t1")` results in `SELECT c1 FROM $(tblName)`. If a key is found within a quoted part of the statement, it is not substituted. Dangling keys (key without value) are ignored.

Important! You must use as much as possible parameter placeholders such as '?' or '$1'. This is however not always possible: for example, when using a dynamic schema or table based on context.

func SchemaExists

func SchemaExists(db *sql.DB, name string) (bool, error)

SchemaExists returns whether schema with given name exists.

func SetDSNParams

func SetDSNParams(dsn string, parameters map[string]string) (string, error)

SetDSNParams sets parameters for the given dsn.

Some parameters are always set, if not provided through parameters or when none were given: * parseTime = true Deprecated: use github.com/golistic/xgo/xsql

func SetLogOutput

func SetLogOutput(db *sql.DB, outputs ...LogOutput) error

SetLogOutput sets the destination of the general and slow query logs. It is possible to specify multiple destination. If LogOutputNone is provided, it will take precedence over all others. No-op if no output is provided.

func SetTableComment

func SetTableComment(db *sql.DB, table string, comment string, schema ...string) error

SetTableComment sets the table's comment. If schema is not provided, current schema will be used.

func SetTableCommentJSON

func SetTableCommentJSON(db *sql.DB, table string, comment any, schema ...string) error

SetTableCommentJSON sets the table's comment marshalled as JSON. If schema is not provided, current schema will be used.

func TableComment

func TableComment(db *sql.DB, table string, schema ...string) (string, error)

TableComment retrieves the comment of a table. If schema is not provided, current schema will be used.

func TableCommentJSON

func TableCommentJSON(db *sql.DB, table string, dest any, schema ...string) error

TableCommentJSON retrieves the comment of a table, unmarshalls it as JSON, and stores it in dest. If schema is not provided, current schema will be used. Panics for same reasons as Go's json.Unmarshal would.

func TableExists

func TableExists(db *sql.DB, name string) (bool, error)

TableExists returns whether table with given name exists in schema db.

Types

type Error

type Error struct {
	Message     string
	DriverError error
	Query       string
	Values      []any
	Filename    string
	Line        int
	Number      int
}

Error wraps mysql.MySQLError with additional information such as file information where the error occurred, query with values when available, and normalized and nicer message.

func ErrorTxBegin

func ErrorTxBegin(err error) Error

ErrorTxBegin returns a xmysql.Error, storing err, and setting a fixed message 'failed starting transaction'.

func ErrorTxCommit

func ErrorTxCommit(err error) Error

ErrorTxCommit returns a xmysql.Error, storing err, and setting a fixed message 'failed committing transaction'.

func NewError

func NewError(err error) Error

NewError returns a new xmysql.Error, storing err. The filename and line number where the error occurred is saved. Panics when the app.Package is not part of the caller's filename.

func NewErrorQuery

func NewErrorQuery(err error, query string, values []any) Error

NewErrorQuery returns a new xmysql.Error, storing err with query and its values that were interpolated. Note: use this with care and only in debugging/development situations.

func NewErrorSprintf

func NewErrorSprintf(err error, format string, a ...any) Error

NewErrorSprintf returns a new xmysql.Error, storing err, but sets also the message to format and its optional arguments.

func (Error) Error

func (e Error) Error() string

Error returns the string representation of the e.

type GeneralLogEvent

type GeneralLogEvent struct {
	Time        time.Time
	UserHost    string
	ThreadID    int
	ServerID    int
	CommandType string
	Argument    string
}

func GetGeneralLogEvents

func GetGeneralLogEvents(db *sql.DB, argLike string, limit int) ([]*GeneralLogEvent, error)

GetGeneralLogEvents retrieves events from the General Query Log using the argLike string, if not empty, to filter through the argument field. When limit is 0, or over the hard limit of 1000, the hard limit will be used. Note that this only works when log output TABLE is active.

type LogOutput

type LogOutput string

const (
	LogOutputNone  LogOutput = "NONE"
	LogOutputFile  LogOutput = "FILE"
	LogOutputTable LogOutput = "TABLE"
)