db

func EnsureHealthyConnection ¶

func EnsureHealthyConnection(ctx context.Context, db *sql.DB) (*sql.Conn, error)

EnsureHealthyConnection gets a dedicated connection from the pool and validates it. The caller is responsible for closing the returned connection when done. This is useful when you need guaranteed connection health for a specific operation.

func IsConnectionError ¶

func IsConnectionError(err error) bool

IsConnectionError is a convenience function that checks specifically for connection errors. This is equivalent to IsRetryableError — both check for transient conditions. Kept for backward compatibility.

func IsPermanentConnectError ¶

func IsPermanentConnectError(err error) bool

IsPermanentConnectError reports whether a connect error can never succeed on retry.

func IsPermissionError ¶

func IsPermissionError(err error) bool

IsPermissionError checks if an error indicates a database permission or privilege failure. These errors are not transient and indicate server misconfiguration.

func IsRetryableError ¶

func IsRetryableError(err error) bool

IsRetryableError determines if an error should trigger a retry. Delegates to dberrors.Classify for driver-specific error detection.

func NowFunc ¶ added in v1.21.31

func NowFunc() time.Time

NowFunc is the GORM clock for autoCreateTime/autoUpdateTime and hooks. It returns UTC truncated to microseconds: PostgreSQL timestamptz and Oracle TIMESTAMP(6) store microsecond precision, so a nanosecond value echoed in a write response would differ from what a later GET returns (#1155).

func ParseRedisURL ¶

func ParseRedisURL(rawURL string) (host, port, password string, db int, err error)

ParseRedisURL parses a Redis connection URL and returns connection parameters. Supported URL format: redis://[:password@]host:port[/db]

func RefreshConnectionPool ¶

func RefreshConnectionPool(db *sql.DB) error

RefreshConnectionPool closes idle connections and validates the pool with fresh connections. This should be called before long-running batch operations to ensure all connections are healthy. It works by temporarily setting MaxIdleConns to 0 (forcing closure of idle connections), then restoring the original value and warming the pool with multiple pings.

func SetGlobalManager ¶

func SetGlobalManager(m *Manager)

SetGlobalManager sets the global database manager singleton. This should be called once during application startup after the manager is fully initialized.

func WithRetryableGormRead ¶

func WithRetryableGormRead(ctx context.Context, cfg RetryConfig, fn func() error) error

WithRetryableGormRead retries a read against transient database errors WITHOUT opening a transaction.

WithRetryableGormTransaction is the wrong tool for a single-statement lookup: it begins a SERIALIZABLE transaction, which on Autonomous Database costs extra round trips for a read that needs no isolation guarantee at all. But leaving such reads entirely unretried is also wrong — dberrors.Classify tags ORA-03113/12519/12520/12537 as transient precisely because ADB raises them during autoscale, and with nothing retrying them a handler maps a momentary listener hiccup to a 500 (#616 note 6).

Same backoff and retry classification as the transactional variant; only the transaction is dropped. Use it for idempotent reads only — the closure may run more than once.

func WithRetryableGormTransaction ¶

func WithRetryableGormTransaction(ctx context.Context, gormDB *gorm.DB, cfg RetryConfig, fn func(tx *gorm.DB) error, opts ...*sql.TxOptions) error

WithRetryableGormTransaction executes a function within a GORM transaction with retry logic. It automatically retries on connection errors and other transient failures. The transaction is managed by GORM (auto-commit on nil return, auto-rollback on error).

The caller MUST pass a ROOT *gorm.DB, never an in-progress transaction handle. GORM's Transaction only forwards txOpts (the SERIALIZABLE isolation) to BeginTx when the handle is a root pool; if handed an in-progress tx it silently opens a SavePoint and DROPS the isolation level — reintroducing the weak-isolation Oracle bug this wrapper exists to prevent, with no error to signal it.

fn may run more than once: on a serialization failure (40001 / ORA-08177) the whole closure is retried. fn must therefore be idempotent — keep any non-idempotent side effect (outbound calls, one-time-token consumption) out of the closure, or guard it so a replay is harmless.

func WithRetryableTransaction ¶

func WithRetryableTransaction(ctx context.Context, db *sql.DB, cfg RetryConfig, fn func(*sql.Tx) error, opts ...*sql.TxOptions) error

WithRetryableTransaction executes a function within a transaction with retry logic. It automatically retries on connection errors and other transient failures. The transaction is rolled back on error and committed on success.