database

Documentation

Overview

Package database contains functions to interact with the database.

The package is imported like this:

import "github.com/gouniverse/base/database"

Index

• Constants
• func DatabaseType(q QueryableInterface) string
• func Execute(ctx QueryableContext, sqlStr string, args ...any) (sql.Result, error)
• func IsQueryableContext(ctx context.Context) bool
• func Open(options openOptionsInterface) (*sql.DB, error)
• func Options() openOptionsInterface
• func Query(ctx QueryableContext, sqlStr string, args ...any) (*sql.Rows, error)
• func SelectToMapAny(ctx QueryableContext, sqlStr string, args ...any) ([]map[string]any, error)
• func SelectToMapString(ctx QueryableContext, sqlStr string, args ...any) ([]map[string]string, error)
• type QueryableContext
  • func Context(ctx context.Context, queryable QueryableInterface) QueryableContext
  • func NewQueryableContext(ctx context.Context, queryable QueryableInterface) QueryableContext
  • func (ctx QueryableContext) IsConn() bool
  • func (ctx QueryableContext) IsDB() bool
  • func (ctx QueryableContext) IsTx() bool
  • func (ctx QueryableContext) Queryable() QueryableInterface
• type QueryableInterface

Constants

const DATABASE_TYPE_MSSQL = "mssql"

const DATABASE_TYPE_MYSQL = "mysql"

const DATABASE_TYPE_POSTGRES = "postgres"

const DATABASE_TYPE_SQLITE = "sqlite"

Functions

func DatabaseType

func DatabaseType(q QueryableInterface) string

DatabaseType finds the driver name from database

It returns the type of the database in the following way:

• "mysql" for MySQL
• "postgres" for PostgreSQL
• "sqlite" for SQLite
• "mssql" for Microsoft SQL Server
• the full name of the driver otherwise

The function is useful when you want to find the type of the database, without knowing it during compilation.

Parameters: - db *sql.DB: the database connection

Returns: - string: the type of the database

#nosec G103 - we use unsafe deliberately to get private fields of sql.Tx and sql.Conn

func Execute

func Execute(ctx QueryableContext, sqlStr string, args ...any) (sql.Result, error)

func IsQueryableContext

func IsQueryableContext(ctx context.Context) bool

IsQueryableContext checks if the given context is a QueryableContext.

Parameters: - ctx: The context to check.

Returns: - bool: True if the context is a QueryableContext, false otherwise.

func Open

func Open(options openOptionsInterface) (*sql.DB, error)

Open opens the database

Note:

• drivers are not included to this package to prevent size bloat
• you must add only the required database driver

Drivers: - sqlite add the following includes: ``` _ "modernc.org/sqlite" ``` - mysql add the following includes: ``` _ "github.com/go-sql-driver/mysql" ``` - postgres add the following includes: ``` _ "github.com/lib/pq" ```

Business logic:

• opens the database based on the driver name
• each driver has its own set of parameters

Parameters: - options openOptionsInterface

Returns: - *sql.DB: the database connection - error: the error if any

func Options

func Options() openOptionsInterface

func Query

func Query(ctx QueryableContext, sqlStr string, args ...any) (*sql.Rows, error)

func SelectToMapAny

func SelectToMapAny(ctx QueryableContext, sqlStr string, args ...any) ([]map[string]any, error)

func SelectToMapString

func SelectToMapString(ctx QueryableContext, sqlStr string, args ...any) ([]map[string]string, error)

Types

type QueryableContext

type QueryableContext struct {
	context.Context
	// contains filtered or unexported fields
}

QueryableContext extends the context.Context interface with a queryable field. The queryable field may be of type *sql.DB, *sql.Conn, or *sql.Tx.

func Context

func Context(ctx context.Context, queryable QueryableInterface) QueryableContext

Context returns a new context with the given QueryableInterface. It is a shortcut for NewQueryableContext.

Example:

ctx := database.Context(context.Background(), tx)

Parameters: - ctx: The parent context. - queryable: The QueryableInterface to be associated with the context.

Returns: - QueryableContext: A new context with the given QueryableInterface.

func NewQueryableContext

func NewQueryableContext(ctx context.Context, queryable QueryableInterface) QueryableContext

NewQueryableContext returns a new context with the given QueryableInterface.

func (QueryableContext) IsConn

func (ctx QueryableContext) IsConn() bool

func (QueryableContext) IsDB

func (ctx QueryableContext) IsDB() bool

func (QueryableContext) IsTx

func (ctx QueryableContext) IsTx() bool

func (QueryableContext) Queryable

func (ctx QueryableContext) Queryable() QueryableInterface

type QueryableInterface

type QueryableInterface interface {
	// ExecContext executes a SQL query in the given context.
	// It returns a sql.Result object containing information about the execution,
	// or an error if the query failed.
	//
	// The context is used to control the execution of the query, allowing for
	// cancellation and timeout control.
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

	// PrepareContext creates a prepared statement for use within a transaction.
	//
	// The returned statement operates within the transaction and will be closed
	// when the transaction has been committed or rolled back.
	//
	// To use an existing prepared statement on this transaction, see [Tx.Stmt].
	//
	// The provided context will be used for the preparation of the context, not
	// for the execution of the returned statement. The returned statement
	// will run in the transaction context.
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)

	// QueryContext executes a SQL query in the given context and returns a
	// *sql.Rows object containing the query results.
	//
	// The context is used to control the execution of the query, allowing for
	// cancellation and timeout control.
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

	// QueryRowContext executes a SQL query in the given context and returns a
	// *sql.Row object containing a single row of results.
	//
	// The context is used to control the execution of the query, allowing for
	// cancellation and timeout control.
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
}

Queryable is an interface that defines a set of methods for executing SQL queries on a database or data source.

It can be one of the following: - *sql.DB - *sql.Conn - *sql.Tx

Implementations of this interface provide a way to execute queries in a context, allowing for cancellation and timeout control.