mysql

Documentation

Index

• Variables
• type Commander
  • func NewCmd(e Executable) Commander
• type Config
  • func NewConfig() Config
• type ConfigModifier
• type Connection
  • func New(ctx context.Context, dsn string, modifiers ...ConfigModifier) (Connection, error)
• type ConnectionManager
  • func NewConnectionManager(config Config) ConnectionManager
• type Counter
  • func NewCounter(r Readable) Counter
• type Executable
• type Finder
  • func NewFinder[T any](r Readable) Finder[T]
• type Inserter
  • func NewInserter[T any](e Executable) Inserter[T]
• type Readable
• type RepositoryOption
  • func OnlyFields(fields ...string) RepositoryOption
  • func SkipFields(fields ...string) RepositoryOption
• type Transformer
• type Updater
  • func NewUpdater[T any](e Executable) Updater[T]

Variables

var (
	ErrEmptySQL   = errors.New("SQL command cannot be empty")
	ErrStructOnly = errors.New("expected type must be a struct")
)

Commonly used errors for database operations.

Types

type Commander

type Commander interface {
	// Command sets the SQL query with '?' placeholders for parameters.
	Command(sql string) Commander

	// Replace substitutes a placeholder in the query string before execution.
	// Placeholders are in the @key format (e.g., "@sort", "@order").
	Replace(old, new string) Commander

	// Exec normalizes and executes the SQL command with the provided arguments.
	Exec(ctx context.Context, arguments ...any) (sql.Result, error)
}

Commander provides methods to construct and execute SQL commands.

func NewCmd

func NewCmd(e Executable) Commander

NewCmd creates a new Commander instance with the provided Executable interface.

type Config

type Config interface {
	// Set the host for the MySQL connection.
	Host(host string) Config

	// Set the port for the MySQL connection (validates port range).
	Port(port int) Config

	// Set the user for the MySQL connection.
	User(username string) Config

	// Set the password for the MySQL connection.
	Password(password string) Config

	// Set the database name for the MySQL connection.
	Database(name string) Config

	// Set the charset for the MySQL connection.
	Charset(charset string) Config

	// ParseTime indicates whether to parse time values in the connection.
	ParseTime(parseTime bool) Config

	// Loc sets the location for time interpretation.
	// Example: "UTC" or "America/New_York"
	Loc(loc string) Config

	// UnixSocket sets the Unix socket for MySQL connection.
	// Useful for local connections when using Unix socket instead of TCP.
	UnixSocket(socket string) Config

	// Add a custom option to the connection configuration.
	// Example: AddOption("tls", "true")
	AddOption(key, value string) Config

	// Build the MySQL connection string based on the current configuration.
	Build() string
	// contains filtered or unexported methods
}

Config defines methods for configuring MySQL connection parameters.

func NewConfig

func NewConfig() Config

NewConfig returns a Config instance with default MySQL connection values.

type ConfigModifier

type ConfigModifier func(*sql.DB)

ConfigModifier modifies database config before creation.

type Connection

type Connection interface {
	// Database returns the underlying connection pool.
	Database() *sql.DB

	// Ping verifies the database connection by sending a simple query.
	Ping(ctx context.Context) error

	// Transaction executes a function within a transaction.
	// Commits if successful, rolls back on error.
	Transaction(ctx context.Context, cb func(*sql.Tx) error) error

	// Close terminates the database connection pool.
	Close() error
}

Connection represents a MySQL database connection.

func New

func New(ctx context.Context, dsn string, modifiers ...ConfigModifier) (Connection, error)

New creates a new MySQL connection using a DSN string. Accepts optional ConfigModifier functions to adjust the configuration before establishing the connection.

type ConnectionManager

type ConnectionManager interface {
	// Add registers a new database connection with the given name.
	// Replaces the connection if it already exists.
	// Returns an error if closing the existing connection fails.
	Add(name string, db Connection) error

	// Connect establishes a new database connection and stores it.
	// Replaces the connection if it already exists.
	// Returns an error if closing the existing connection fails or if the new connection attempt fails.
	Connect(ctx context.Context, name string) error

	// Resolve retrieves an existing connection or creates a new one if not found.
	Resolve(ctx context.Context, name string) (Connection, error)

	// Get retrieves a database connection by name.
	// Returns the connection and a boolean indicating if it was found.
	Get(name string) (Connection, bool)

	// Remove closes and deletes the database connection by name.
	// Returns an error if closing the connection fails.
	Remove(name string) error

	// Close shuts down all active database connections.
	// Returns an error if closing any connection fails.
	Close() error
}

ConnectionManager handles multiple MySQL database connections.

func NewConnectionManager

func NewConnectionManager(config Config) ConnectionManager

NewConnectionManager creates and returns a new ConnectionManager instance.

type Counter

type Counter interface {
	// Query sets the SQL query for counting rows.
	Query(sql string) Counter

	// Replace substitutes placeholders in the query string before execution.
	// Placeholders are in the @key format (e.g., "@column_name").
	Replace(old, new string) Counter

	// Count executes the query and returns the row count.
	// It uses the provided arguments for parameterized queries.
	// Returns the count and any errors encountered.
	Count(ctx context.Context, args ...any) (int64, error)
}

Counter provides methods for constructing and executing SQL queries to count results.

func NewCounter

func NewCounter(r Readable) Counter

NewCounter creates a new Counter instance with the provided Readable interface.

type Executable

type Executable interface {
	// ExecContext runs a SQL command with optional parameters.
	// Returns a pgconn.CommandTag containing metadata about the execution result.
	ExecContext(ctx context.Context, sql string, args ...any) (sql.Result, error)
}

Executable defines an interface for executing SQL commands.

type Finder

type Finder[T any] interface {
	// Query sets the SQL query string to be executed.
	Query(sql string) Finder[T]

	// Replace updates specific placeholders in the SQL query.
	// Placeholders are in the @key format (e.g., "@column_name").
	Replace(old, new string) Finder[T]

	// WithTransformer adds a transformation function to modify the result.
	WithTransformer(func(*T) error) Finder[T]

	// Rows executes the query and returns a pgx.Rows iterator for processing result rows.
	// Auto replace @fields with struct fields list
	Rows(ctx context.Context, args ...any) (*sql.Rows, error)

	// Struct executes the query and retrieves a single result, or an error if the query fails.
	Struct(ctx context.Context, args ...any) (*T, error)

	// Structs executes the query and retrieves multiple results, or an error if the query fails.
	Structs(ctx context.Context, args ...any) ([]T, error)
}

Finder provides methods to construct and execute SQL queries that return structured results.

func NewFinder

func NewFinder[T any](r Readable) Finder[T]

NewFinder creates a new Finder instance with the provided Readable interface.

type Inserter

type Inserter[T any] interface {
	// Table sets the target table for the insert operation.
	Table(table string) Inserter[T]

	// Insert performs an insert operation with the given record and options.
	Insert(ctx context.Context, record T, options ...RepositoryOption) (sql.Result, error)
}

Inserter provides methods for inserting a struct into a specified database table.

func NewInserter

func NewInserter[T any](e Executable) Inserter[T]

NewInserter initializes and returns a new Inserter instance for the given Executable interface.

type Readable

type Readable interface {
	// QueryContext runs a SQL query with optional parameters and returns a pgx.Rows iterator.
	// The provided context is used for managing timeouts and cancellations.
	QueryContext(ctx context.Context, sql string, args ...any) (*sql.Rows, error)

	// QueryRowContext runs a SQL query expecting a single result and returns a pgx.Row.
	// The provided context is used for managing timeouts and cancellations.
	QueryRowContext(ctx context.Context, sql string, args ...any) *sql.Row
}

Readable defines an interface for executing SQL queries.

type RepositoryOption

type RepositoryOption func(*options)

func OnlyFields

func OnlyFields(fields ...string) RepositoryOption

OnlyFields returns a RepositoryOption function that specifies which fields to include.

func SkipFields

func SkipFields(fields ...string) RepositoryOption

SkipFields returns a RepositoryOption function that specifies which fields to exclude.

type Transformer

type Transformer interface {
	// Transform processes and extracts data.
	// Returns an error if the transformation fails.
	Transform() error
}

Transformer defines an interface for decoding and transforming data.

type Updater

type Updater[T any] interface {
	// Table sets the target table for the update operation.
	Table(table string) Updater[T]

	// Where specifies the WHERE condition for the update.
	Where(condition string, args ...any) Updater[T]

	// Update performs the update operation with the provided record and options.
	Update(ctx context.Context, record T, options ...RepositoryOption) (sql.Result, error)
}

Updater provides methods for updating records in a specified database table.

func NewUpdater

func NewUpdater[T any](e Executable) Updater[T]

NewUpdater initializes and returns a new Updater instance for the given Executable interface.