pgkit

README

pgKit

pgKit simplifies using Postgres in your Go applications. It does this by acting as a wrapper around your connection to the database. It uses lib/pq under the hood. Additionally, it provides some convience utilities for handling testing with your databases - such as providing a way to setup transactioned test cases and temporary databases with your tests.

Documentation

Documentation can be found here.

Testing

pgKit has unit tests, they require a user and a database to run, to get these setup:

1. Create a new user with the CREATEDB permission.
2. Create a new database.
3. Provide the connection url to the test via the PGKIT_TEST_URL environment variable.

For example, given the user pgkit_test with the password pgkit and a the database pgkit_test running on localhost with default port and SSL options, the provided URL would be: postgresql://pgkit_test:pgkit@localhost:5432/pgkit_test?sslmode=disable

To run the tests then:

PGKIT_TEST_URL="postgresql://pgkit_test:pgkit@localhost:5432/pgkit_test?sslmode=disable" go test ./...

Documentation

Index

• type ConnectionDetail
  • func NewConnectionDetail() ConnectionDetail
  • func ParseDetails(connection string) (ConnectionDetail, error)
  • func (cd *ConnectionDetail) Copy() ConnectionDetail
  • func (cd *ConnectionDetail) IsValid() bool
  • func (cd *ConnectionDetail) String() string
• type DB
  • func Open(connection string) (DB, error)
• type DataProvider

Types

type ConnectionDetail

type ConnectionDetail struct {
	User     string
	Password string
	Location string
	Port     string
	Database string
	Options  map[string]string
}

ConnectionDetail represents the information used to connect to the database.

func NewConnectionDetail

func NewConnectionDetail() ConnectionDetail

NewConnectionDetail will return a ConnectionDetail with the Options map correctly initialized.

func ParseDetails

func ParseDetails(connection string) (ConnectionDetail, error)

ParseDetails extracts the connection details out of the connection URI.

func (*ConnectionDetail) Copy

func (cd *ConnectionDetail) Copy() ConnectionDetail

Copy returns a deep copy of the ConnectionDetail so it can be manipulated without impacting the original.

func (*ConnectionDetail) IsValid

func (cd *ConnectionDetail) IsValid() bool

IsValid indicates if the information in the ConnectionDetail can be used to construct a valid connection.

func (*ConnectionDetail) String

func (cd *ConnectionDetail) String() string

Returns a URL with the same values as the ConnectionDetail represents. It will not check if the returned URL is valid, that is left up to the user.

type DB

type DB struct {
	*sql.DB
	Connection ConnectionDetail
}

DB wraps around *sql.DB so that additional information, such as the name of the server and current database name can be recorded.

func Open

func Open(connection string) (DB, error)

Open will attempt to open a connection to a Postgres Database as specified by the connection string provided, it will then ping the database to see if the connection is valid.

type DataProvider

type DataProvider interface {
	Query(string, ...interface{}) (*sql.Rows, error)
	QueryRow(string, ...interface{}) *sql.Row
	Exec(string, ...interface{}) (sql.Result, error)
}

DataProvider provides methods for interating with a SQL database, and is fulfilled by both *sql.DB and *sql.TX which allow for transactioned unit tests or mock structs.