pgsq

README

pgsq

About

Wrapper for pgx/v5 pool.

scany/v2 is used to provide Select & Get convenience methods.

All basic (i.e. not raw) methods take sqlizer interface as a query, which is provided by squirrel query builder.

Usage example

Actual data-access methods should take pgsq.Queryable as an argument–this way CreateEntity can be called using a connection pool or a transaction depending on logical requirements.

package database

import (
    "context"
    "fmt"

    "github.com/vaardan/pgsq"
    "github.com/Masterminds/squirrel"
)


// CreateEntity creates new entity with the given name and returns its ID.
func CreateEntity(ctx context.Context, q pgsq.Queryable, name string) (int, error) {
	query := squirrel.StatementBuilder.
		PlaceholderFormat(squirrel.Dollar).
		Insert("entity_table").
		Columns("name").
		Values(name).
		Suffix("returning id")

	var id int
	err := q.Get(ctx, &id, query)
	if err != nil {
		return 0, fmt.Errorf("insert entity: %w", err)
	}

	return id, nil
}

Documentation

Index

• type Pool
  • func NewPool(pool *pgxpool.Pool) Pool
• type Queryable
• type Tx

Types

type Pool

type Pool interface {
	Queryable
	BeginTx(ctx context.Context, txOptions *pgx.TxOptions) (Tx, error)
}

Pool contains operations necessary to query with the database.

func NewPool

func NewPool(pool *pgxpool.Pool) Pool

NewPool creates new Pool.

type Queryable

type Queryable interface {
	// Exec executes the builder query.
	Exec(ctx context.Context, query sqlizer) (pgconn.CommandTag, error)

	// ExecRaw executes the raw query.
	ExecRaw(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)

	// Get queries a single row. Returns pgx.ErrNoRows, if there are no rows satisfying the builder query.
	Get(ctx context.Context, dst any, sqlizer sqlizer) error

	// GetRaw queries a single row. Returns pgx.ErrNoRows, if there are no rows satisfying the raw query.
	GetRaw(ctx context.Context, dst any, sql string, args ...any) error

	// Select queries multiple rows. Returns nil, if there are no rows satisfying the builder query.
	Select(ctx context.Context, dst any, query sqlizer) error

	// SelectRaw queries multiple rows. Returns nil, if there are no rows satisfying the raw query.
	SelectRaw(ctx context.Context, dst any, sql string, args ...any) error
}

Queryable interface containing operations necessary to query database. Both Pool and Tx implement it.

type Tx

type Tx interface {
	Queryable

	// Commit commits transaction.
	// Will return an error where errors.Is(pgx.ErrTxClosed) is true if the Tx is already closed, but is
	// otherwise safe to call multiple times. If the commit fails with a rollback status (e.g. the transaction was already
	// in a broken state) then an error where errors.Is(ErrTxCommitRollback) is true will be returned.
	Commit(ctx context.Context) error

	// Rollback cancels transaction.
	// Will return an error where errors.Is(pgx.ErrTxClosed) is true if the Tx is already
	// closed, but is otherwise safe to call multiple times. Hence, a defer tx.Rollback() is safe even if tx.Commit() will
	// be called first in a non-error condition. Any other failure of a real transaction will result in the connection
	// being closed.
	Rollback(ctx context.Context) error
}

Tx transaction interface.