postgres

type ConnectionConfig struct {
	Host     string
	Port     string
	UserName string
	Password string
	DbName   string

	// TLS/SSL: "disable", "require", "verify-ca", "verify-full"
	SSLMode string

	// Pool sizing (per process)
	MaxOpenConn int
	MaxIdleConn int

	ConnMaxLifetime time.Duration
	ConnMaxIdleTime time.Duration

	// Defaults applied if zero.
	ConnectTimeout time.Duration
	PingTimeout    time.Duration

	// DefaultQueryTimeout is used by DBContext when it needs to add a timeout
	// to context-less calls.
	DefaultQueryTimeout time.Duration

	// PgBouncer config — if transaction/statement pooling, we will disable
	// server-side prepared statements at the driver level.
	PgBouncer PgBouncerMode

	// RuntimeParams are sent to Postgres at connection startup:
	// application_name, search_path, statement_timeout, timezone, etc.
	RuntimeParams map[string]string
}

type DBContext struct {
	// Tx represents an active PostgreSQL transaction.
	// If set, all SQL operations are executed inside this transaction.
	Tx Tx

	// Conn is a direct PostgreSQL connection interface.
	// Used when Tx is nil.
	Conn PostgresDbInterface

	// Cluster is a named PostgreSQL cluster.
	// Used to lazily obtain a connection if both Tx and Conn are nil.
	Cluster string

	// DefaultTimeout is applied when callers use non-context methods
	// (Exec/Query/Prepare) or pass a context without deadline.
	//
	// If <= 0, no implicit deadline is added.
	DefaultTimeout time.Duration

	// ExecFn optionally overrides execution of non-query statements.
	ExecFn func(ctx context.Context, query string, args ...any) (sql.Result, error)

	// PrepareFn optionally overrides preparation of SQL statements.
	PrepareFn func(ctx context.Context, query string) (*sql.Stmt, error)

	// QueryFn optionally overrides execution of queries returning rows.
	QueryFn func(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

type PgBouncerMode string

type PostgresDb struct {
	DB *sql.DB
}

type PostgresDbConnector struct {
	DB *PostgresDb
}

type PostgresDbConnectorInterface interface {
	Open(driverName string, dataSourceName string) (PostgresDbInterface, error)
}

type PostgresDbInterface interface {
	Close() error
	Ping() error
	PingContext(ctx context.Context) error

	Exec(query string, args ...any) (sql.Result, error)
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

	Query(query string, args ...any) (*sql.Rows, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)

	QueryRow(query string, args ...any) *sql.Row
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row

	Prepare(query string) (*sql.Stmt, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)

	Begin() (*sql.Tx, error)
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)

	SetConnMaxLifetime(d time.Duration)
	SetMaxIdleConns(n int)
	SetMaxOpenConns(n int)
	SetConnMaxIdleTime(d time.Duration)
	Stats() sql.DBStats

	Raw() *sql.DB
}

type ReadQueryInput struct {
	Query             string
	Params            []any
	CapitaliseColumns bool
}

type Tx interface {
	Exec(query string, args ...any) (sql.Result, error)
	Prepare(query string) (*sql.Stmt, error)
	Query(query string, args ...any) (*sql.Rows, error)
}

type TxContext interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}