sqldb

README

Sqldb

The sqldb module defines a supercharged native sql.DB driver that simplifies configuration and add some usefull methods. It aims to minify code repetition that the database/sql" module can create.

Overview

The sqldb module offers:

• Simplified configuration
• A TryConnection method for pinging your database, triggering an error if the timeout is exceeded
• Convenient methods to streamline SQL database queries

Concepts

Easily configure your connector with the provided Conf structure and its factory methods:

type Conf struct {
	Driver string `yaml:"driver"` // Database driver (e.g., "mysql", "postgres", etc.).
	DSN    string `yaml:"dsn"`    // Data Source Name (DSN) for connecting to the database.
}

Usage

Configuration

The sqldb.Conf uses a YAML tags, it's easy to load SqlDB config with configuration file in your project

type Conf struct {
	Driver string `yaml:"driver"` // example: postgres, mysql
	DSN    string `yaml:"dsn"` // connection string (format depends on the driver, read the associated documentation)
}

Example DSN:

• postgres: user=postgres password=example dbname=postgres host=localhost port=5432 sslmode=disable TimeZone=UTC
• mysql: root:example@tcp(localhost:3306)/dbtest?loc=UTC&tls=false&parseTime=true (WARNING: parseTime=true is require)

Create new connector

To create new SqlDB Connector use this function with as configuration the structure sqldb.FactoryConnector(c sqldb.Conf) (*sqldb.Connector, error) and try connection with sqldb.Connector.TryConnection(t int) err

var config = sqldb.Conf{
	Driver:     "mysql",
	DSN:      	"root:example@tcp(localhost:13306)/dbtest?loc=UTC&tls=false&parseTime=trueword",
}

// Build Connector
connector, err = sqldb.FactoryConnector(config)
if err != nil {
	return fmt.Errorf("fail to init SqlDB connector: %w", err)
}

// Test connection
err = connector.TryConnection(10)
if err != nil {
	return fmt.Errorf("fail to ping SqlDB: %w", err)
}

Contributing

This section will be added soon.

License

Sqldb module is released under the MIT license. See LICENSE.txt.

Documentation

Index

• type Conf
• type Connector
  • func FactoryConnector(c Conf) (*Connector, error)
  • func (con *Connector) Commit(tx *sql.Tx) error
  • func (con *Connector) Exec(tx *sql.Tx, query string, args ...interface{}) (sql.Result, error)
  • func (con *Connector) ExecQueryRow(tx *sql.Tx, query string, args ...interface{}) (*sql.Row, error)
  • func (con *Connector) TryConnection(t int) error

Types

type Conf

type Conf struct {
	Driver string `yaml:"driver"` // Database driver (e.g., "mysql", "postgres", etc.).
	DSN    string `yaml:"dsn"`    // Data Source Name (DSN) for connecting to the database.
}

Conf represents the configuration structure for opening a connection to the database. It includes fields for specifying the database driver and Data Source Name (DSN) for connecting to the database.

type Connector

type Connector struct {
	*sql.DB
}

Connector is a struct representing a database connector. It embeds a *sql.DB to provide the functionalities of a SQL database connection.

func FactoryConnector

func FactoryConnector(c Conf) (*Connector, error)

FactoryConnector creates and returns a new *Connector by opening a connection to the SQL database using the provided Conf configuration. It returns the initialized Connector and an error if the connection cannot be established. The function uses the database driver and Data Source Name (DSN) specified in the configuration.

func (*Connector) Commit

func (con *Connector) Commit(tx *sql.Tx) error

Commit commits the provided SQL transaction. It takes a *sql.Tx parameter and attempts to commit the transaction. If the commit is successful, the function returns nil; otherwise, it returns an error with relevant information.

func (*Connector) Exec

func (con *Connector) Exec(tx *sql.Tx, query string, args ...interface{}) (sql.Result, error)

Exec executes the provided SQL query within the specified transaction. It takes a *sql.Tx, a query string, and optional query arguments. The function prepares the query, executes the prepared statement with the given arguments, and returns the sql.Result. If any error occurs during preparation or execution, the function returns an error with relevant information.

func (*Connector) ExecQueryRow

func (con *Connector) ExecQueryRow(tx *sql.Tx, query string, args ...interface{}) (*sql.Row, error)

ExecQueryRow executes the provided SQL query within the specified transaction and returns a *sql.Row representing the result. It takes a *sql.Tx, a query string, and optional query arguments. The function prepares the query, creates a *sql.Row with the prepared statement and the given arguments, and returns it. If any error occurs during preparation, the function returns an error with relevant information.

func (*Connector) TryConnection

func (con *Connector) TryConnection(t int) error

TryConnection attempts to establish a connection to the SQL database by repeatedly pinging it within a specified time duration. It takes an integer parameter 't' representing the maximum time duration in seconds for attempting the connection. The function returns an error if the connection cannot be established within the specified time or if an error occurs during the connection attempt.