dal

README

dal - Database Access Layer

Description

This package is very opinionated. It aims to eliminate inline code SQL statemnts by requiring a virtual file system that will hold all the sql templates in memory during runtime.

This package wraps the database/sql package.

Development

This package is still under active development. It is wise to vendor this package because although not planned some breaking API changes may be introduced.

Required Interfaces

type FileStore interface {
    Get(file string) (string, error)
}

The interface FileStore is a required interface that must be implemented in order to instantiate a new DAL because this is need when calling the query methods for the purpose of parsing the SQL template.

Usage

package main

func main() {
    lgr := func(msg string) {
        log.Println(msg)
    }

    dataStore, err := loadDataStore(envcfg.PgDbCreds(), envcfg.DbPingTime(), fileStore, lgr)
    if err != nil {
        log.Fatalln(err)
    }
}


func loadDataStore(dbCreds string, dbPingTime int, fileStore vfs.Store, lgr finlog.Logger) (dal.DAL, error) {
    pgdal, openErr := dal.Open("postgres", envcfg.PgDbCreds())
    if openErr != nil {
            return nil, openErr
    }

    lgrFunc := func(msg string) {
            lgr.Info(msg)
    }

    pingErr := dal.PingDatabase(pgdal, dbPingTime, lgrFunc)
    if pingErr != nil {
            return nil, pingErr
    }

    return dal.New(pgdal, fileStore), nil
}

Documentation

Overview

Package dal is an opinionated package that wraps the functions of go's standard database/sql package. The versions of sql.Query, sql.QueryRow, et al. all are left untouched so that the interfaces are a superset of the standard ones.

The key opinionated approaches used by this libraray is the implementation of an interface: type FileStore interface { Get(sqlTemplate string) (string, error) } that MUST return the string of a SQL template. The other opinionated approach is that the parameters passed on the the Query, QueryRow functions be of: map[string]interface{} versus: interface{} This makes the execution a bit faster than other libraries.

Index

• func PingDatabase(db DB, dbPingTime int, lgr func(msg string)) error
• func RowsToMap(rows *sql.Rows) map[int]map[string]interface{}
• type DAL
  • func New(db DB, fileStore FileStore) DAL
• type DB
  • func Open(driver string, dbCreds string) (DB, error)
• type FileStore

Examples

• New

Functions

func PingDatabase

func PingDatabase(db DB, dbPingTime int, lgr func(msg string)) error

PingDatabase is a helper function to ping the database with backoff to ensure a connection can be established before we proceed with a database setup whilst logging each ping and returns an error if it fails using the given function to log.

func RowsToMap

func RowsToMap(rows *sql.Rows) map[int]map[string]interface{}

RowsToMap takes the current sql.Rows and maps each column and value to a map[string]interface{}.

Types

type DAL

type DAL interface {
	Exec(sqlFile string, params map[string]interface{}) (sql.Result, error)
	Query(sqlFile string, params map[string]interface{}) (*sql.Rows, error)
	QueryRow(sqlFile string, params map[string]interface{}) (*sql.Row, error)
}

DAL (database access layer) is the type returned when initializing an new instance of this package. The functions listed are the functions that can be used for this package.

func New

func New(db DB, fileStore FileStore) DAL

New returns a DAL using the given DB and FileStore.

Example

db, openErr := sql.Open("postgres", "dbname=dbdal_test sslmode=disable")
if openErr != nil {
	log.Fatalln(openErr)
}

// vfs: github.com/magicalbanana/vfs
fileStore, fsErr := vfs.LoadFiles("tests")
if fsErr != nil {
	log.Fatalln(fsErr)
}

New(db, fileStore)

type DB

type DB interface {
	Prepare(query string) (*sql.Stmt, error)
	Exec(query string, args ...interface{}) (sql.Result, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(query string, args ...interface{}) *sql.Row
	Ping() error
}

DB is an interface modeled after the go's standard database/sql package.

func Open

func Open(driver string, dbCreds string) (DB, error)

Open opens a new database connection using the given driver and the dbCreds. If an error occurs when opening a connection an error is returned.

type FileStore

type FileStore interface {
	Get(file string) (string, error)
}

FileStore is a package agnostic interface for any type of virtual file system that returns the value as string.

Of course the string MUST be the SQL template that will be used upon executing a query function (Query, QueryRow, etc).