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. SEM@b6e227d0511f3e7d38d29e5059408fe7b2cd56eb: fetch a dedicated DB connection and validate it with a ping (reads DB)

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. SEM@0f58823d7b00057541d6c3e806539e674d5773f4: classify a database error as a transient connection failure; alias for IsRetryableError (pure)

func IsPermanentConnectError ¶

func IsPermanentConnectError(err error) bool

IsPermanentConnectError reports whether a connect error can never succeed on retry. SEM@ab6a7ff21a80d96c9f7c490184f44a06dc5607b9: classify a database connect error as non-retryable (pure)

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. SEM@0f58823d7b00057541d6c3e806539e674d5773f4: classify a database error as a fatal permission or privilege failure, not eligible for retry (pure)

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. SEM@0f58823d7b00057541d6c3e806539e674d5773f4: classify a database error as transient and eligible for retry (pure)

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] SEM@fe6575f1c15d84b67ee9853a0e59055c1ebe44b6: parse a Redis connection URL and return host, port, password, and database index (pure)

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. SEM@3d0d5a8cf02fa74fad102f0f99c2b936a164bbea: evict idle DB connections and warm the pool with fresh validated connections (reads DB)

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. SEM@3080aafd268e1adeeb4b0e7b35049f3b5e926c7c: register the database manager singleton for process-wide access (mutates shared state)

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. SEM@bfe3f043180e288dc7f18690340fbdd493d5813c: run a read closure, retrying transient database errors with jittered backoff and no transaction (reads DB)

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. SEM@b7302144e81a755cfb12d83c8a03782feffcd848: execute a function in a serializable GORM transaction, retrying transient errors with jittered backoff (mutates DB)

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. SEM@b7302144e81a755cfb12d83c8a03782feffcd848: execute a function in a serializable SQL transaction, retrying transient errors with jittered backoff (mutates DB)