package postgres

import (
	"context"

	"github.com/jackc/pgx/v5"
)

// Provider is the database access interface consumed by repositories and services.
// All methods are safe for concurrent use.
type Provider interface {
	// GetExecutor returns the active transaction injected by [UnitOfWork] if one
	// is present in ctx, otherwise returns the connection pool.
	GetExecutor(ctx context.Context) Executor
	// Begin starts a new transaction with default options.
	Begin(ctx context.Context) (Tx, error)
	// BeginTx starts a new transaction with the given options.
	BeginTx(ctx context.Context, opts pgx.TxOptions) (Tx, error)
	// Ping verifies that the database connection is alive.
	Ping(ctx context.Context) error
	// HandleError maps a pgx or PostgreSQL error to a typed [xerrors] value.
	// Call this at every point where a pgx error is first observed.
	HandleError(err error) error
}