dbquery

type AuditFunc func(ctx context.Context, e Event) error

type Auditor interface {
	Audit(ctx context.Context, e Event) error
}

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

type Column struct {
	Name string `json:"name"`
	// PGType is Postgres' name for the type ("int4", "timestamptz", an enum's
	// name).
	PGType string `json:"pg_type"`
}

type Error struct {
	Kind Kind
	// Reason is a stable machine-readable subcode within Kind
	// ("multiple_statements", "statement_timeout", ...), empty when Kind says
	// it all.
	Reason string
	// Message is safe to show the caller who wrote the SQL.
	Message string
	// Err is the underlying cause, if any.
	Err error
}

type Event struct {
	SQL       string
	SQLSHA256 string
	// Leader is the statement's leading keyword, empty when the guard
	// refused before finding one.
	Leader string
	// Outcome is "ok", or the [Kind] of the failure.
	Outcome string
	// Err is the failure, nil on success.
	Err        error
	RowCount   int
	Bytes      int
	Truncated  bool
	StartedAt  time.Time
	Duration   time.Duration
	MaxRows    int
	TimeoutSec float64
	// Args are the values bound to the statement's parameters, in order; nil
	// when none were. Values only: they are never part of SQL.
	Args []any
}

type Kind string

type Options struct {
	// MaxRows is the row cap. 0 means DefaultMaxRows; above MaxRowsLimit is
	// refused.
	MaxRows int
	// Timeout is the statement timeout. 0 means DefaultTimeout; above
	// MaxTimeout is refused.
	Timeout time.Duration
	// LockTimeout is how long the statement waits for a lock. 0 means
	// DefaultLockTimeout; above MaxLockTimeout is refused.
	LockTimeout time.Duration
	// IdleTimeout is idle_in_transaction_session_timeout. 0 means
	// DefaultIdleTimeout; above MaxTimeout is refused.
	IdleTimeout time.Duration
	// MaxBytes caps the encoded size of the cells kept, below the response
	// cap. 0 means MaxResponseBytes; above it is refused.
	MaxBytes int
	// Args are the values of the statement's $1, $2, ... parameters, bound
	// over the extended protocol so a value is never spliced into the SQL.
	// Only $1..$n for the highest $n the statement references are bound (see
	// [ParamRefs]); a reference past len(Args) is refused. Postgres infers a
	// parameter's type from its use, so cast one that has no context
	// ($1::timestamptz).
	Args []any
	// Auditor, when set, is told how every attempt went.
	Auditor Auditor
	// contains filtered or unexported fields
}

type Result struct {
	Columns []Column `json:"columns"`
	Rows    [][]any  `json:"rows"`
	// RowCount is len(Rows).
	RowCount int `json:"row_count"`
	// Truncated is true when a cap cut the result; TruncatedBy names it:
	// "rows" or "bytes".
	Truncated   bool   `json:"truncated"`
	TruncatedBy string `json:"truncated_by,omitempty"`
	// CellsTruncated counts cells cut to MaxCellBytes.
	CellsTruncated int   `json:"cells_truncated,omitempty"`
	DurationMS     int64 `json:"duration_ms"`
	// Bytes is the encoded size of the cells kept, the figure the response
	// cap counts.
	Bytes int `json:"bytes"`
}