postgres

type Beginner interface {
	// BeginTx returns a transaction whose finalization is delegated to the runner.
	BeginTx(context.Context, pgx.TxOptions) (pgx.Tx, error)
}

type Config struct {
	// DSN is an admitted credential string passed to ResolveDSN; never log it.
	DSN string

	// ResolveDSN is required. It owns any environment, filesystem or other
	// acquisition used to resolve the admitted DSN, must cooperate with ctx,
	// and transfers a fresh parser-created native configuration exclusively.
	ResolveDSN func(context.Context, string) (*PoolConfig, error)

	// ConfigResolutionTimeout bounds cooperative preparation; zero uses 5s.
	ConfigResolutionTimeout time.Duration
	// Limits selects finite native credential admission budgets.
	Limits ConfigLimits

	// ConnectTimeout bounds native connection attempts; zero selects 5s.
	ConnectTimeout time.Duration
	// AcquireTimeout bounds wrapper acquisition, not subsequent queries; zero
	// selects 5s.
	AcquireTimeout time.Duration
	// PingTimeout bounds wrapper probes and supplies the native default; zero
	// selects 2s.
	PingTimeout time.Duration
	// ShutdownTimeout bounds each wrapper shutdown wait, not native cleanup;
	// zero selects 10s.
	ShutdownTimeout time.Duration

	// MaxConns selects the native connection ceiling; zero selects 10.
	MaxConns int32
	// MinConns requests a native minimum; StartupLazy requires zero.
	MinConns int32
	// MinIdleConns requests a native idle minimum; StartupLazy requires zero.
	MinIdleConns int32

	// MaxConnLifetime selects the native maximum lifetime; zero selects one hour.
	MaxConnLifetime time.Duration
	// MaxConnLifetimeJitter spreads native expiry; zero selects five minutes.
	MaxConnLifetimeJitter time.Duration
	// MaxConnIdleTime selects the native idle lifetime; zero selects thirty minutes.
	MaxConnIdleTime time.Duration
	// HealthCheckPeriod selects native maintenance frequency; zero selects one minute.
	HealthCheckPeriod time.Duration
	// StartupPolicy chooses lazy construction or an explicit connectivity probe.
	StartupPolicy StartupPolicy
	// TLS applies host-specific overrides before Configure.
	TLS TLSConfig
	// Observer receives synchronous wrapper observations; nil disables them.
	Observer Observer

	// SessionInit runs for every newly established connection after any native
	// AfterConnect hook. Returning an error rejects that connection.
	SessionInit func(context.Context, *pgx.Conn) error

	// Configure receives the admitted native configuration and preparation
	// deadline after typed options. It must cooperate with ctx and exclusively
	// mutate the transferred configuration without retaining it for later use.
	Configure func(context.Context, *PoolConfig) error
}

type ConfigError struct {
	// Field names the rejected configuration field or admission boundary.
	Field string
	// Problem is the diagnostic included by Error; package-created text omits
	// credentials.
	Problem string
	// Cause is retained for trusted Configure failures, not resolver failures.
	Cause error
}

type ConfigLimits struct {
	// MaximumDSNBytes admits the input before application resolution.
	MaximumDSNBytes int
	// MaximumFallbacks admits the native fallback slice before traversal.
	MaximumFallbacks int
	// MaximumRuntimeParams admits the native map before traversal.
	MaximumRuntimeParams int
	// MaximumNativeStringBytes charges every native string occurrence, including
	// the retained original connection string, all scalar settings, fallback
	// hosts, and runtime parameter keys/values. Opaque TLS data is not charged.
	MaximumNativeStringBytes int
	// MaximumStatementCacheEntries bounds the native prepared statement cache.
	MaximumStatementCacheEntries int
	// MaximumDescriptionCacheEntries bounds the native description cache.
	MaximumDescriptionCacheEntries int
	// MaximumProtocolMessageBodyBytes bounds each native wire-message body.
	MaximumProtocolMessageBodyBytes int
}

type ErrorInfo struct {
	// Kind is the selected policy category, with native PostgreSQL errors
	// taking precedence.
	Kind ErrorKind
	// SQLState is the unredacted native code when a PgError matches.
	SQLState string
	// Retryable is advisory for serialization/deadlock or native safe-to-retry
	// network errors.
	Retryable bool
	// Cause is the exact input error, including sensitive data it may carry.
	Cause error
	// Postgres borrows the matched native error; it is not cloned or redacted.
	Postgres *pgconn.PgError

	// Severity retains native server severity text.
	Severity string
	// Constraint retains the native constraint name.
	Constraint string
	// Schema retains the native schema name.
	Schema string
	// Table retains the native table name.
	Table string
	// Column retains the native column name.
	Column string
	// Detail retains server detail text and may contain sensitive values.
	Detail string
	// Hint retains server advice and may contain sensitive values.
	Hint string
}

type ErrorKind string

type Health struct {
	// Ready reports success of this probe, not a persistent availability guarantee.
	Ready bool
	// Err preserves the probe error; nil means the probe succeeded.
	Err error
	// Stats is sampled separately from the readiness ping or liveness check.
	Stats Stats
}

type Observation struct {
	// Operation identifies a wrapper lifecycle operation, not application SQL.
	Operation Operation
	// Outcome identifies completion, error, panic or goroutine termination.
	Outcome Outcome
	// Duration is sampled before observer delivery and excludes its own callback time.
	Duration time.Duration
	// ErrorKind is the finite projection of diagnostic classification.
	ErrorKind ErrorKind
	// SQLState is an exact recognized state, empty, or the fixed unknown category.
	SQLState string
	// Pool contains a separate native statistics snapshot when HasPoolStats is true.
	Pool Stats
	// HasPoolStats distinguishes an actual zero-valued snapshot from an
	// operation, such as a transaction, that did not sample pool state.
	HasPoolStats bool
}

type Observer interface {
	// Observe consumes metadata synchronously; concurrent calls must be safe.
	Observe(context.Context, Observation)
}

type ObserverFunc func(context.Context, Observation)

type Operation string

type Outcome string

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

type PoolConfig = pgxpool.Config

type SavepointOptions struct {
	// CleanupTimeout bounds cooperative rollback; zero selects 5s, negative
	// expires immediately.
	CleanupTimeout time.Duration
	// Observer receives the final synchronous savepoint observation; nil disables it.
	Observer Observer
}

type StartupPolicy uint8

type Stats struct {
	// AcquireCount is the native count of successful acquisitions.
	AcquireCount int64
	// AcquiredConns is the number of connections currently borrowed.
	AcquiredConns int32
	// CanceledAcquireCount is the native count of canceled acquisitions.
	CanceledAcquireCount int64
	// ConstructingConns is the number of connections being constructed.
	ConstructingConns int32
	// EmptyAcquireCount counts successful acquisitions that waited for an empty pool.
	EmptyAcquireCount int64
	// EmptyAcquireWaitTime is cumulative wait time for successful acquisitions
	// from an empty pool; canceled waits are not included.
	EmptyAcquireWaitTime time.Duration
	// IdleConns is the number of currently idle connections.
	IdleConns int32
	// MaxConns is the configured native maximum connection count.
	MaxConns int32
	// NewConnsCount is the native cumulative count of created connections.
	NewConnsCount int64
	// TotalConns includes idle, acquired and constructing connections.
	TotalConns int32
}

type TLSConfig struct {
	// Mode chooses DSN preservation, TLS disablement or an explicit override.
	Mode TLSMode
	// Config is required for TLSRequire; it is ignored by other modes.
	Config *tls.Config
}

type TLSMode uint8

type TransactionOptions struct {
	// TxOptions passes native transaction modes through without validation.
	pgx.TxOptions
	// CleanupTimeout bounds cooperative rollback; zero selects 5s, negative
	// expires immediately.
	CleanupTimeout time.Duration
	// Observer receives the final synchronous transaction observation; nil disables it.
	Observer Observer
}