Documentation
¶
Overview ¶
Package db provides PostgreSQL connection management with retry, keep-alive, and schema migration utilities.
Index ¶
- func Connect(databaseURL string, opts ...ConnectOption) (*sqlx.DB, error)
- func ConnectContext(ctx context.Context, databaseURL string, opts ...ConnectOption) (*sqlx.DB, error)
- func Migrate(db *sqlx.DB, cfg MigrateConfig) error
- func MigrateDown(db *sqlx.DB, cfg MigrateConfig) error
- func MigrateForce(db *sqlx.DB, cfg MigrateConfig, version int) error
- func MigrateSteps(db *sqlx.DB, cfg MigrateConfig, n int) error
- func MigrateVersion(db *sqlx.DB, cfg MigrateConfig) (version uint, dirty bool, err error)
- func StartKeepAlive(ctx context.Context, db *sqlx.DB, interval time.Duration, _ int)
- func StartKeepAliveWithConfig(ctx context.Context, db *sqlx.DB, cfg KeepAliveConfig)
- type ConnectConfig
- type ConnectOption
- func WithAttemptTimeout(d time.Duration) ConnectOption
- func WithConnMaxIdleTime(d time.Duration) ConnectOption
- func WithConnMaxLifetime(d time.Duration) ConnectOption
- func WithLogger(l *slog.Logger) ConnectOption
- func WithMaxIdleConns(n int) ConnectOption
- func WithMaxOpenConns(n int) ConnectOption
- func WithMaxRetries(n int) ConnectOption
- func WithOnRetry(fn OnRetryFunc) ConnectOption
- func WithPgBouncerSafe(enabled bool) ConnectOption
- type KeepAliveConfig
- type MigrateConfig
- type OnRetryFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Connect ¶
func Connect(databaseURL string, opts ...ConnectOption) (*sqlx.DB, error)
Connect opens a PostgreSQL connection using context.Background(). Use ConnectContext to control startup cancellation.
func ConnectContext ¶
func ConnectContext(ctx context.Context, databaseURL string, opts ...ConnectOption) (*sqlx.DB, error)
ConnectContext opens a PostgreSQL connection with retry and exponential backoff + jitter. On success it configures pool parameters and validates connectivity via PingContext.
func Migrate ¶
func Migrate(db *sqlx.DB, cfg MigrateConfig) error
Migrate runs all up migrations from the embedded filesystem. ErrNoChange is silently ignored.
func MigrateDown ¶
func MigrateDown(db *sqlx.DB, cfg MigrateConfig) error
MigrateDown rolls back all migrations.
func MigrateForce ¶
func MigrateForce(db *sqlx.DB, cfg MigrateConfig, version int) error
MigrateForce sets the migration version without running any migrations. Use this to fix a dirty migration state.
func MigrateSteps ¶
func MigrateSteps(db *sqlx.DB, cfg MigrateConfig, n int) error
MigrateSteps runs n migration steps. Positive n migrates up, negative migrates down.
func MigrateVersion ¶
MigrateVersion returns the current migration version and dirty flag.
func StartKeepAlive ¶
StartKeepAlive launches an optional keep-alive loop. For backward compatibility, poolSize is ignored; only one goroutine is started.
func StartKeepAliveWithConfig ¶
func StartKeepAliveWithConfig(ctx context.Context, db *sqlx.DB, cfg KeepAliveConfig)
StartKeepAliveWithConfig launches one goroutine that periodically runs PingContext with a timeout. This is intended for explicit opt-in usage.
Types ¶
type ConnectConfig ¶
type ConnectConfig struct {
MaxOpenConns int
MaxIdleConns int
ConnMaxIdleTime time.Duration
ConnMaxLifetime time.Duration
MaxRetries int
AttemptTimeout time.Duration
PgBouncerSafe bool
Logger *slog.Logger
OnRetry OnRetryFunc
}
ConnectConfig holds connection pool and retry parameters.
type ConnectOption ¶
type ConnectOption func(*ConnectConfig)
ConnectOption configures a ConnectConfig.
func WithAttemptTimeout ¶
func WithAttemptTimeout(d time.Duration) ConnectOption
WithAttemptTimeout sets the timeout for each connectivity check attempt.
func WithConnMaxIdleTime ¶
func WithConnMaxIdleTime(d time.Duration) ConnectOption
WithConnMaxIdleTime sets the maximum idle time for a connection.
func WithConnMaxLifetime ¶
func WithConnMaxLifetime(d time.Duration) ConnectOption
WithConnMaxLifetime sets the maximum lifetime of a connection.
func WithLogger ¶
func WithLogger(l *slog.Logger) ConnectOption
WithLogger sets the logger used to log retry attempts. A nil logger disables retry logging.
func WithMaxIdleConns ¶
func WithMaxIdleConns(n int) ConnectOption
WithMaxIdleConns sets the maximum number of idle connections.
func WithMaxOpenConns ¶
func WithMaxOpenConns(n int) ConnectOption
WithMaxOpenConns sets the maximum number of open connections.
func WithMaxRetries ¶
func WithMaxRetries(n int) ConnectOption
WithMaxRetries sets the number of connection retry attempts.
func WithOnRetry ¶
func WithOnRetry(fn OnRetryFunc) ConnectOption
WithOnRetry sets a callback invoked before each retry sleep.
func WithPgBouncerSafe ¶
func WithPgBouncerSafe(enabled bool) ConnectOption
WithPgBouncerSafe forces pgx simple protocol mode, which is compatible with PgBouncer transaction pooling.
type KeepAliveConfig ¶
KeepAliveConfig configures optional background connectivity checks.
type MigrateConfig ¶
MigrateConfig configures the migration runner.
Source Files
Directories