postgres

README

go-postgres

A library that simplifies access to PostgreSQL databases.

Some considerations

1. Despite go-postgres uses Jack Christensen's PGX library internally, it aims to act as a generic database driver like database/sql and avoid the developer to use specific PGX types and routines.
2. Most of the commonly used types in Postgres can be mapped to standard Golang types including time.Time for timestamps (except Postgres' time with tz which is not supported)
3. When reading JSON/JSONB fields, the code will try to unmarshall it into the destination variable. In order to just retrieve the json value as a string, add the ::text suffix to the field in the SELECT query.
4. To avoid overflows on high uint64 values, you can store them in NUMERIC(24,0) fields.
5. When reading time-only fields, the date part of the time.Time variable is set to January 1, 2000.

Usage with example

package main

import (
	"context"

	"github.com/randlabs/go-postgres"
)

type Data struct {
	Id   int
	Name string
}

func main() {
	ctx := context.Background()

	// Create database driver
	db, err := postgres.New(ctx, postgres.Options{
		Host:     "127.0.0.1",
		Port:     5432,
		User:     "postgres",
		Password: "1234",
		Name:     "sampledb",
	})
	if err != nil {
		// ....
	}
	defer db.Close()

	// Insert some data
	data := Data{
		Id:   1,
		Name: "example",
	}

	_, err = db.Exec(ctx, `INSERT INTO test_table (id, name) VALUES ($1, $2)`, data.Id, data.Name)
	if err != nil {
		// ....
	}

	// Read it
	var name string
	err = db.QueryRow(ctx, `SELECT name FROM test_table WHERE id = $1)`, 1).Scan(&name)
	if err != nil {
		// ....
		if postgres.IsNoRowsError(err) {
			// This should not happen. We cannot find the record we just inserted.
		}
	}

	// ....
}

LICENSE

See LICENSE file for details.

Documentation

Index

• func IsDatabaseError(err error) bool
• func IsNetworkError(err error) bool
• func IsNoRowsError(err error) bool
• type CopyCallback
• type Database
  • func New(ctx context.Context, opts Options) (*Database, error)
  • func NewFromURL(ctx context.Context, rawUrl string) (*Database, error)
  • func (db *Database) Close()
  • func (db *Database) Copy(ctx context.Context, tableName string, columnNames []string, ...) (int64, error)
  • func (db *Database) Exec(ctx context.Context, sql string, args ...interface{}) (int64, error)
  • func (db *Database) QueryRow(ctx context.Context, sql string, args ...interface{}) Row
  • func (db *Database) QueryRows(ctx context.Context, sql string, args ...interface{}) Rows
  • func (db *Database) SetEventHandler(handler ErrorHandler)
  • func (db *Database) WithinTx(ctx context.Context, callback WithinTxCallback) error
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorDetails
• type ErrorHandler
• type NoRowsError
  • func (e *NoRowsError) Error() string
• type Options
• type Row
• type Rows
• type SSLMode
• type ScanRowsCallback
• type Tx
  • func (tx *Tx) Copy(ctx context.Context, tableName string, columnNames []string, ...) (int64, error)
  • func (tx *Tx) DB() *Database
  • func (tx *Tx) Exec(ctx context.Context, sql string, args ...interface{}) (int64, error)
  • func (tx *Tx) QueryRow(ctx context.Context, sql string, args ...interface{}) Row
  • func (tx *Tx) QueryRows(ctx context.Context, sql string, args ...interface{}) Rows
• type WithinTxCallback

Functions

func IsDatabaseError

func IsDatabaseError(err error) bool

IsDatabaseError returns true if the given error object is a database error.

func IsNetworkError

func IsNetworkError(err error) bool

IsNetworkError returns true if the error is related to a network issue.

func IsNoRowsError

func IsNoRowsError(err error) bool

IsNoRowsError returns true if the given error is the result of returning an empty result set.

Types

type CopyCallback

type CopyCallback func(ctx context.Context, idx int) ([]interface{}, error)

CopyCallback defines a callback that is called for each record being copied to the database

type Database

type Database struct {
	// contains filtered or unexported fields
}

Database represents a PostgreSQL database accessor.

func New

func New(ctx context.Context, opts Options) (*Database, error)

New creates a new postgresql database driver.

func NewFromURL

func NewFromURL(ctx context.Context, rawUrl string) (*Database, error)

NewFromURL creates a new postgresql database driver from an URL

func (*Database) Close

func (db *Database) Close()

Close shutdown the connection pool

func (*Database) Copy

func (db *Database) Copy(ctx context.Context, tableName string, columnNames []string, callback CopyCallback) (int64, error)

Copy executes a SQL copy query within the transaction.

func (*Database) Exec

func (db *Database) Exec(ctx context.Context, sql string, args ...interface{}) (int64, error)

Exec executes an SQL statement on a new connection

func (*Database) QueryRow

func (db *Database) QueryRow(ctx context.Context, sql string, args ...interface{}) Row

QueryRow executes a SQL query on a new connection

NOTES: ~~~~~

1. Most of the commonly used types in Postgres can be mapped to standard Golang type including time.Time for timestamps (except time with tz which is not supported)
2. When reading JSON/JSONB fields, the underlying library (PGX) tries to unmarshall it into the destination variable. In order to just retrieve the json string, add the `::text` suffix to the field in the query.
3. To avoid overflows on high uint64 values, store them in NUMERIC(24,0) fields.
4. For time-only fields, date is set to Jan 1, 2000 by PGX in time.Time variables.

func (*Database) QueryRows

func (db *Database) QueryRows(ctx context.Context, sql string, args ...interface{}) Rows

QueryRows executes a SQL query on a new connection

func (*Database) SetEventHandler

func (db *Database) SetEventHandler(handler ErrorHandler)

SetEventHandler sets a new error handler callback

func (*Database) WithinTx

func (db *Database) WithinTx(ctx context.Context, callback WithinTxCallback) error

WithinTx executes a callback function within the context of a transaction

type Error

type Error struct {
	Details *ErrorDetails
	// contains filtered or unexported fields
}

Error is the error type usually returned by us.

func (*Error) Error

func (e *Error) Error() string

Error returns a string representation of the error.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying error.

type ErrorDetails

type ErrorDetails struct {
	Severity       string
	Code           string
	Message        string
	Detail         string
	Hint           string
	Position       int32
	Where          string
	SchemaName     string
	TableName      string
	ColumnName     string
	DataTypeName   string
	ConstraintName string
	File           string
	Line           int32
	Routine        string
}

type ErrorHandler

type ErrorHandler func(err error)

ErrorHandler defines a custom error handler.

type NoRowsError

type NoRowsError struct {
}

NoRowsError is the error we return if the query does not return any row.

func (*NoRowsError) Error

func (e *NoRowsError) Error() string

type Options

type Options struct {
	Host     string `json:"host"`
	Port     uint16 `json:"port"`
	User     string `json:"user"`
	Password string `json:"password"`
	Name     string `json:"name"`
	MaxConns int32  `json:"maxConns"`
	SSLMode  SSLMode
}

Options defines the database connection options.

type Row

type Row interface {
	// Scan saves the content of the current row in the destination variables.
	Scan(dest ...interface{}) error
}

Row defines a returned record.

type Rows

type Rows interface {
	// Do calls the provided callback for each row returned by the executed query.
	Do(callback ScanRowsCallback) error
}

Rows defines a set of returned records.

type SSLMode

type SSLMode int

SSLMode states if secure communication with the server is optional or mandatory.

const (
	SSLModeAllow SSLMode = iota
	SSLModeRequired
	SSLModeDisable
)

type ScanRowsCallback

type ScanRowsCallback = func(ctx context.Context, row Row) (bool, error)

ScanRowsCallback defines a callback that is called on each row returned by the executed query.

type Tx

type Tx struct {
	// contains filtered or unexported fields
}

Tx encloses a transation object.

func (*Tx) Copy

func (tx *Tx) Copy(ctx context.Context, tableName string, columnNames []string, callback CopyCallback) (int64, error)

Copy executes a SQL copy query within the transaction.

func (*Tx) DB

func (tx *Tx) DB() *Database

DB returns the underlying database driver.

func (*Tx) Exec

func (tx *Tx) Exec(ctx context.Context, sql string, args ...interface{}) (int64, error)

Exec executes an SQL statement within the transaction.

func (*Tx) QueryRow

func (tx *Tx) QueryRow(ctx context.Context, sql string, args ...interface{}) Row

QueryRow executes a SQL query within the transaction.

func (*Tx) QueryRows

func (tx *Tx) QueryRows(ctx context.Context, sql string, args ...interface{}) Rows

QueryRows executes a SQL query within the transaction.

type WithinTxCallback

type WithinTxCallback = func(ctx context.Context, tx Tx) error

WithinTxCallback defines a callback called in the context of the initiated transaction.