px

package
v2.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 6, 2025 License: MIT Imports: 11 Imported by: 0

README

px: PostgreSQL Helper Functions Package

This package is a set of helper functions for working with PostgreSQL via pgx/v5 in Go. It is part of the github.com/n-r-w/pgh/v2 project and provides a collection of utilities that simplify database operations using the Squirrel SQL builder.

Function Groups

1. Query Execution Helpers

These functions execute SQL queries built with Squirrel. They include basic execution functions (Exec) and query functions for retrieving one or multiple rows (SelectOne, Select, and SelectFunc). They automatically convert Squirrel queries into executable SQL with appropriate arguments, bridging the gap between query construction and execution using pgx.

2. Batch Operations Helpers

Designed for handling bulk operations efficiently. This group includes:

  • Batch execution: Functions like ExecBatch execute multiple queries together.
  • Splitting operations: Functions such as ExecSplit, InsertSplit, and InsertSplitQuery divide large query sets into smaller batches, optimizing transaction management.
  • Batch selection: SelectBatch facilitates executing multiple select queries concurrently.
3. Transaction Management Helpers

These functions encapsulate transaction management by automatically handling commit and rollback. The primary helpers (BeginTxFunc and BeginFunc) execute a callback within a transaction context, ensuring reliable error management and resource handling.

4. Error Handling Helpers

Utilities to interpret PostgreSQL error codes and provide coherent error checking. Functions like IsNoRows, IsUniqueViolation, and IsForeignKeyViolation detect common database errors, helping maintain consistent error handling across operations.

5. Squirrel Integration

Underlying all helper functions is seamless integration with Squirrel. This integration simplifies converting Squirrel queries to SQL and ensures that both simple and complex SQL operations are handled efficiently.

Documentation

Overview

Package px is a generated GoMock package.

Package px is a generated GoMock package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeginFunc 

func BeginFunc(ctx context.Context,
	conn ITransactionBeginner,
	f func(ctx context.Context, tx pgx.Tx) error,
) error

BeginFunc starts a transaction, executes the callback function, and handles commit/rollback automatically. If the callback returns an error, the transaction is rolled back. Otherwise, it is committed. If commit/rollback fails, the error is wrapped with the original error if any. Unlike pgx.BeginFunc, it passes the context to the function f.

func BeginTxFunc 

func BeginTxFunc(ctx context.Context,
	conn ITransactionBeginner,
	options pgx.TxOptions,
	f func(ctx context.Context, tx pgx.Tx) error,
) (err error)

BeginTxFunc starts a transaction, executes the callback function, and handles commit/rollback automatically. If the callback returns an error, the transaction is rolled back. Otherwise, it is committed. If commit/rollback fails, the error is wrapped with the original error if any. Unlike pgx.BeginTxFunc, it passes the context to the function f.

func Exec 

func Exec(ctx context.Context, querier IQuerier, sqlizer sq.Sqlizer) (pgconn.CommandTag, error)

Exec executes a modification query. Querier can be either pgx.Tx or pg_types.Pool

func ExecBatch 

func ExecBatch(ctx context.Context, queries []sq.Sqlizer, tx IBatcher) (rowsAffected int64, err error)

ExecBatch executes a batch of queries with error checking. tx can be either pgx.Tx or pg_types.Pool.

func ExecPlain 

func ExecPlain(ctx context.Context, querier IQuerier, sql string, args pgh.Args) (pgconn.CommandTag, error)

ExecPlain executes a modification query. Querier can be either pgx.Tx or pg_types.Pool

func ExecSplit 

func ExecSplit(
	ctx context.Context, tx IBatcher, queries []sq.Sqlizer, splitSize int,
) (rowsAffected int64, err error)

ExecSplit splits queries into groups of splitSize and executes them separately within a transaction. tx can be either pgx.Tx or pg_types.Pool

func ExecSplitPlain 

func ExecSplitPlain(
	ctx context.Context,
	tx IBatcher,
	queries []string,
	args []pgh.Args,
	splitSize int,
) (rowsAffected int64, err error)

ExecSplitPlain splits queries into groups of splitSize and executes them separately within a transaction. tx can be either pgx.Tx or pg_types.Pool ExecSplitPlain splits queries into groups of splitSize and executes them separately within a transaction. tx can be either pgx.Tx or pg_types.Pool.

func InsertSplit 

func InsertSplit(
	ctx context.Context,
	tx IBatcher,
	base sq.InsertBuilder,
	values []pgh.Args,
	splitSize int,
) (rowsAffected int64, err error)

InsertSplit splits queries into groups of splitSize and executes them separately within a transaction. values - rows with the same number of values in each. tx can be either pgx.Tx or pg_types.Pool. Use this when COPY cannot be used, for example, when ON CONFLICT is required.

func InsertSplitPlain 

func InsertSplitPlain(
	ctx context.Context,
	tx IBatcher,
	sql string,
	values []pgh.Args,
	splitSize int,
) (rowsAffected int64, err error)

InsertSplitPlain splits queries into groups of splitSize and executes them separately within a transaction. values - rows with the same number of values in each. tx can be either pgx.Tx or pg_types.Pool. Use this when COPY cannot be used, for example, when ON CONFLICT is required.

func InsertSplitQuery 

func InsertSplitQuery[T any](
	ctx context.Context,
	tx IBatcher,
	base sq.InsertBuilder,
	values []pgh.Args,
	splitSize int,
	dst *[]T,
) (err error)

InsertSplitQuery splits queries into groups of splitSize and executes them separately within a transaction. values - rows with the same number of values in each. tx can be either pgx.Tx or pg_types.Pool. Use this when COPY cannot be used, for example, when ON CONFLICT is required. Unlike InsertSplit, it allows using the RETURNING clause to get data into dst.

func InsertValuesPlain 

func InsertValuesPlain(ctx context.Context, querier IQuerier, sql string, values []pgh.Args) error

InsertValuesPlain executes a query to insert a group of values. sql should be in the form "INSERT INTO table (col1, col2)" without VALUES. VALUES is added automatically.

func IsForeignKeyViolation added in v2.1.0 

func IsForeignKeyViolation(err error) bool

IsForeignKeyViolation checks if the error is a foreign key constraint violation.

func IsNoRows added in v2.1.0 

func IsNoRows(err error) bool

IsNoRows checks if the error is a "no rows" error.

func IsUniqueViolation added in v2.1.0 

func IsUniqueViolation(err error) bool

IsUniqueViolation checks if the error is a unique constraint violation.

func Select 

func Select[T any](ctx context.Context, querier IQuerier, sqlizer sq.Sqlizer, dst *[]T) error

Select executes a query. Querier can be either pgx.Tx or pg_types.Pool

func SelectBatch 

func SelectBatch[T any](ctx context.Context, queries []sq.Sqlizer, tx IBatcher, dst *[]T) error

SelectBatch executes a batch of queries with error checking. tx can be either pgx.Tx or pg_types.Pool.

func SelectFunc 

func SelectFunc(ctx context.Context, querier IQuerier, sqlizer sq.Sqlizer, f func(row pgx.Row) error) error

SelectFunc executes a query and passes each row to function f. Querier can be either pgx.Tx or pg_types.Pool.

func SelectFuncPlain 

func SelectFuncPlain(ctx context.Context, querier IQuerier, sql string, args pgh.Args,
	f func(pgx.Row) error,
) error

SelectFuncPlain executes a query and passes each row to function f. Querier can be either pgx.Tx or pg_types.Pool.

func SelectOne 

func SelectOne[T any](ctx context.Context, querier IQuerier, sqlizer sq.Sqlizer, dst *T) error

SelectOne executes a query. Querier can be either pgx.Tx or pg_types.Pool. dst must contain a variable, not a slice.

func SelectOnePlain 

func SelectOnePlain[T any](ctx context.Context, querier IQuerier, sql string, dst *T, args pgh.Args) error

SelectOnePlain executes a query. Querier can be either pgx.Tx or pg_types.Pool. dst must contain a variable, not a slice.

func SelectPlain 

func SelectPlain[T any](ctx context.Context, querier IQuerier, sql string, dst *[]T, args pgh.Args) error

SelectPlain executes a query. Querier can be either pgx.Tx or pg_types.Pool

func SendBatch 

func SendBatch(ctx context.Context, tx IBatcher, batch *pgx.Batch) (rowsAffected int64, err error)

SendBatch executes a batch of queries with error checking. tx can be either pgx.Tx or pg_types.Pool.

func SendBatchQuery 

func SendBatchQuery[T any](ctx context.Context, tx IBatcher, batch *pgx.Batch, dst *[]T) error

SendBatchQuery executes a batch of queries with error checking. tx can be either pgx.Tx or pg_types.Pool. Returns query results as a single slice.

Types

type IBatcher 

type IBatcher interface {
	SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
}

IBatcher is a subset of pgxpool.Pool, pgx.Conn and pgx.Tx interfaces for batches

type IQuerier 

type IQuerier interface {
	Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
	Exec(ctx context.Context, sql string, arguments ...any) (commandTag pgconn.CommandTag, err error)
}

IQuerier is a subset of pgxpool.Pool, pgx.Conn and pgx.Tx interfaces for queries

type ITransactionBeginner 

type ITransactionBeginner interface {
	BeginTx(context.Context, pgx.TxOptions) (pgx.Tx, error)
}

ITransactionBeginner is a subset of pgxpool.Pool, pgx.Conn for starting transactions.

type MockBatchResults 

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

MockBatchResults is a mock of BatchResults interface.

func NewMockBatchResults 

func NewMockBatchResults(ctrl *gomock.Controller) *MockBatchResults

NewMockBatchResults creates a new mock instance.

func (*MockBatchResults) Close 

func (m *MockBatchResults) Close() error

Close mocks base method.

func (*MockBatchResults) EXPECT 

func (m *MockBatchResults) EXPECT() *MockBatchResultsMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockBatchResults) Exec 

func (m *MockBatchResults) Exec() (pgconn.CommandTag, error)

Exec mocks base method.

func (*MockBatchResults) Query 

func (m *MockBatchResults) Query() (pgx.Rows, error)

Query mocks base method.

func (*MockBatchResults) QueryRow 

func (m *MockBatchResults) QueryRow() pgx.Row

QueryRow mocks base method.

type MockBatchResultsMockRecorder 

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

MockBatchResultsMockRecorder is the mock recorder for MockBatchResults.

func (*MockBatchResultsMockRecorder) Close 

func (mr *MockBatchResultsMockRecorder) Close() *gomock.Call

Close indicates an expected call of Close.

func (*MockBatchResultsMockRecorder) Exec 

func (mr *MockBatchResultsMockRecorder) Exec() *gomock.Call

Exec indicates an expected call of Exec.

func (*MockBatchResultsMockRecorder) Query 

func (mr *MockBatchResultsMockRecorder) Query() *gomock.Call

Query indicates an expected call of Query.

func (*MockBatchResultsMockRecorder) QueryRow 

func (mr *MockBatchResultsMockRecorder) QueryRow() *gomock.Call

QueryRow indicates an expected call of QueryRow.

type MockIBatcher 

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

MockIBatcher is a mock of IBatcher interface.

func NewMockIBatcher 

func NewMockIBatcher(ctrl *gomock.Controller) *MockIBatcher

NewMockIBatcher creates a new mock instance.

func (*MockIBatcher) EXPECT 

func (m *MockIBatcher) EXPECT() *MockIBatcherMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockIBatcher) SendBatch 

func (m *MockIBatcher) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults

SendBatch mocks base method.

type MockIBatcherMockRecorder 

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

MockIBatcherMockRecorder is the mock recorder for MockIBatcher.

func (*MockIBatcherMockRecorder) SendBatch 

func (mr *MockIBatcherMockRecorder) SendBatch(ctx, b any) *gomock.Call

SendBatch indicates an expected call of SendBatch.

type MockIQuerier 

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

MockIQuerier is a mock of IQuerier interface.

func NewMockIQuerier 

func NewMockIQuerier(ctrl *gomock.Controller) *MockIQuerier

NewMockIQuerier creates a new mock instance.

func (*MockIQuerier) EXPECT 

func (m *MockIQuerier) EXPECT() *MockIQuerierMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockIQuerier) Exec 

func (m *MockIQuerier) Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)

Exec mocks base method.

func (*MockIQuerier) Query 

func (m *MockIQuerier) Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)

Query mocks base method.

type MockIQuerierMockRecorder 

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

MockIQuerierMockRecorder is the mock recorder for MockIQuerier.

func (*MockIQuerierMockRecorder) Exec 

func (mr *MockIQuerierMockRecorder) Exec(ctx, sql any, arguments ...any) *gomock.Call

Exec indicates an expected call of Exec.

func (*MockIQuerierMockRecorder) Query 

func (mr *MockIQuerierMockRecorder) Query(ctx, query any, args ...any) *gomock.Call

Query indicates an expected call of Query.

type MockITransactionBeginner 

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

MockITransactionBeginner is a mock of ITransactionBeginner interface.

func NewMockITransactionBeginner 

func NewMockITransactionBeginner(ctrl *gomock.Controller) *MockITransactionBeginner

NewMockITransactionBeginner creates a new mock instance.

func (*MockITransactionBeginner) BeginTx 

func (m *MockITransactionBeginner) BeginTx(arg0 context.Context, arg1 pgx.TxOptions) (pgx.Tx, error)

BeginTx mocks base method.

func (*MockITransactionBeginner) EXPECT 

func (m *MockITransactionBeginner) EXPECT() *MockITransactionBeginnerMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

type MockITransactionBeginnerMockRecorder 

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

MockITransactionBeginnerMockRecorder is the mock recorder for MockITransactionBeginner.

func (*MockITransactionBeginnerMockRecorder) BeginTx 

func (mr *MockITransactionBeginnerMockRecorder) BeginTx(arg0, arg1 any) *gomock.Call

BeginTx indicates an expected call of BeginTx.

type MockRow 

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

MockRow is a mock of Row interface.

func NewMockRow 

func NewMockRow(ctrl *gomock.Controller) *MockRow

NewMockRow creates a new mock instance.

func (*MockRow) EXPECT 

func (m *MockRow) EXPECT() *MockRowMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockRow) Scan 

func (m *MockRow) Scan(arg0 ...any) error

Scan mocks base method.

type MockRowMockRecorder 

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

MockRowMockRecorder is the mock recorder for MockRow.

func (*MockRowMockRecorder) Scan 

func (mr *MockRowMockRecorder) Scan(arg0 ...any) *gomock.Call

Scan indicates an expected call of Scan.

type MockRows 

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

MockRows is a mock of Rows interface.

func NewMockRows 

func NewMockRows(ctrl *gomock.Controller) *MockRows

NewMockRows creates a new mock instance.

func (*MockRows) Close 

func (m *MockRows) Close()

Close mocks base method.

func (*MockRows) CommandTag 

func (m *MockRows) CommandTag() pgconn.CommandTag

CommandTag mocks base method.

func (*MockRows) Conn 

func (m *MockRows) Conn() *pgx.Conn

Conn mocks base method.

func (*MockRows) EXPECT 

func (m *MockRows) EXPECT() *MockRowsMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockRows) Err 

func (m *MockRows) Err() error

Err mocks base method.

func (*MockRows) FieldDescriptions 

func (m *MockRows) FieldDescriptions() []pgconn.FieldDescription

FieldDescriptions mocks base method.

func (*MockRows) Next 

func (m *MockRows) Next() bool

Next mocks base method.

func (*MockRows) RawValues 

func (m *MockRows) RawValues() [][]byte

RawValues mocks base method.

func (*MockRows) Scan 

func (m *MockRows) Scan(arg0 ...any) error

Scan mocks base method.

func (*MockRows) Values 

func (m *MockRows) Values() ([]any, error)

Values mocks base method.

type MockRowsMockRecorder 

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

MockRowsMockRecorder is the mock recorder for MockRows.

func (*MockRowsMockRecorder) Close 

func (mr *MockRowsMockRecorder) Close() *gomock.Call

Close indicates an expected call of Close.

func (*MockRowsMockRecorder) CommandTag 

func (mr *MockRowsMockRecorder) CommandTag() *gomock.Call

CommandTag indicates an expected call of CommandTag.

func (*MockRowsMockRecorder) Conn 

func (mr *MockRowsMockRecorder) Conn() *gomock.Call

Conn indicates an expected call of Conn.

func (*MockRowsMockRecorder) Err 

func (mr *MockRowsMockRecorder) Err() *gomock.Call

Err indicates an expected call of Err.

func (*MockRowsMockRecorder) FieldDescriptions 

func (mr *MockRowsMockRecorder) FieldDescriptions() *gomock.Call

FieldDescriptions indicates an expected call of FieldDescriptions.

func (*MockRowsMockRecorder) Next 

func (mr *MockRowsMockRecorder) Next() *gomock.Call

Next indicates an expected call of Next.

func (*MockRowsMockRecorder) RawValues 

func (mr *MockRowsMockRecorder) RawValues() *gomock.Call

RawValues indicates an expected call of RawValues.

func (*MockRowsMockRecorder) Scan 

func (mr *MockRowsMockRecorder) Scan(arg0 ...any) *gomock.Call

Scan indicates an expected call of Scan.

func (*MockRowsMockRecorder) Values 

func (mr *MockRowsMockRecorder) Values() *gomock.Call

Values indicates an expected call of Values.

type MockTx 

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

MockTx is a mock of Tx interface.

func NewMockTx 

func NewMockTx(ctrl *gomock.Controller) *MockTx

NewMockTx creates a new mock instance.

func (*MockTx) Begin 

func (m *MockTx) Begin(arg0 context.Context) (pgx.Tx, error)

Begin mocks base method.

func (*MockTx) Commit 

func (m *MockTx) Commit(arg0 context.Context) error

Commit mocks base method.

func (*MockTx) Conn 

func (m *MockTx) Conn() *pgx.Conn

Conn mocks base method.

func (*MockTx) CopyFrom 

func (m *MockTx) CopyFrom(arg0 context.Context, arg1 pgx.Identifier, arg2 []string, arg3 pgx.CopyFromSource) (int64, error)

CopyFrom mocks base method.

func (*MockTx) EXPECT 

func (m *MockTx) EXPECT() *MockTxMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockTx) Exec 

func (m *MockTx) Exec(arg0 context.Context, arg1 string, arg2 ...any) (pgconn.CommandTag, error)

Exec mocks base method.

func (*MockTx) LargeObjects 

func (m *MockTx) LargeObjects() pgx.LargeObjects

LargeObjects mocks base method.

func (*MockTx) Prepare 

func (m *MockTx) Prepare(arg0 context.Context, arg1, arg2 string) (*pgconn.StatementDescription, error)

Prepare mocks base method.

func (*MockTx) Query 

func (m *MockTx) Query(arg0 context.Context, arg1 string, arg2 ...any) (pgx.Rows, error)

Query mocks base method.

func (*MockTx) QueryRow 

func (m *MockTx) QueryRow(arg0 context.Context, arg1 string, arg2 ...any) pgx.Row

QueryRow mocks base method.

func (*MockTx) Rollback 

func (m *MockTx) Rollback(arg0 context.Context) error

Rollback mocks base method.

func (*MockTx) SendBatch 

func (m *MockTx) SendBatch(arg0 context.Context, arg1 *pgx.Batch) pgx.BatchResults

SendBatch mocks base method.

type MockTxMockRecorder 

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

MockTxMockRecorder is the mock recorder for MockTx.

func (*MockTxMockRecorder) Begin 

func (mr *MockTxMockRecorder) Begin(arg0 any) *gomock.Call

Begin indicates an expected call of Begin.

func (*MockTxMockRecorder) Commit 

func (mr *MockTxMockRecorder) Commit(arg0 any) *gomock.Call

Commit indicates an expected call of Commit.

func (*MockTxMockRecorder) Conn 

func (mr *MockTxMockRecorder) Conn() *gomock.Call

Conn indicates an expected call of Conn.

func (*MockTxMockRecorder) CopyFrom 

func (mr *MockTxMockRecorder) CopyFrom(arg0, arg1, arg2, arg3 any) *gomock.Call

CopyFrom indicates an expected call of CopyFrom.

func (*MockTxMockRecorder) Exec 

func (mr *MockTxMockRecorder) Exec(arg0, arg1 any, arg2 ...any) *gomock.Call

Exec indicates an expected call of Exec.

func (*MockTxMockRecorder) LargeObjects 

func (mr *MockTxMockRecorder) LargeObjects() *gomock.Call

LargeObjects indicates an expected call of LargeObjects.

func (*MockTxMockRecorder) Prepare 

func (mr *MockTxMockRecorder) Prepare(arg0, arg1, arg2 any) *gomock.Call

Prepare indicates an expected call of Prepare.

func (*MockTxMockRecorder) Query 

func (mr *MockTxMockRecorder) Query(arg0, arg1 any, arg2 ...any) *gomock.Call

Query indicates an expected call of Query.

func (*MockTxMockRecorder) QueryRow 

func (mr *MockTxMockRecorder) QueryRow(arg0, arg1 any, arg2 ...any) *gomock.Call

QueryRow indicates an expected call of QueryRow.

func (*MockTxMockRecorder) Rollback 

func (mr *MockTxMockRecorder) Rollback(arg0 any) *gomock.Call

Rollback indicates an expected call of Rollback.

func (*MockTxMockRecorder) SendBatch 

func (mr *MockTxMockRecorder) SendBatch(arg0, arg1 any) *gomock.Call

SendBatch indicates an expected call of SendBatch.

Source Files

View all Source files

Directories

Path Synopsis
db
Package db is a generated GoMock package.
 Package db is a generated GoMock package.
conn
Package conn is a generated GoMock package.
 Package conn is a generated GoMock package.
sharded/bucket
sharded/example
sharded/shard
telemetry

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.