Documentation
¶
Overview ¶
Package postgresql provides a PostgreSQL integration bundle for Forge applications.
The PostgreSQL bundle provides:
- Database connection management with connection pooling
- Health checks for database connectivity and performance
- Transaction utilities and patterns
- Graceful connection lifecycle management
- Production-ready connection pool configuration
Basic Usage ¶
Add the PostgreSQL bundle to your application:
config := postgresql.Config{
DatabaseURL: "postgres://user:pass@localhost/dbname?sslmode=require",
MaxOpenConns: 25,
MaxIdleConns: 10,
ConnMaxLifetime: 30 * time.Minute,
}
bundle := postgresql.NewBundle(config)
app, err := framework.New(
framework.WithConfig(&baseConfig),
framework.WithBundle(bundle),
)
Accessing the Database ¶
The bundle registers a database instance that can be accessed via dependency injection:
type UserService struct {
db *sql.DB
}
func NewUserService(db *sql.DB) *UserService {
return &UserService{db: db}
}
Health Checks ¶
The bundle automatically provides database health checks that verify:
- Database connectivity (ping)
- Query execution capability
- Connection pool health
Database Migrations ¶
The bundle focuses on runtime database connectivity. For database migrations, use dedicated tools during deployment:
- golang-migrate/migrate CLI tool
- Flyway for enterprise deployments
- Custom deployment scripts
- Kubernetes init containers
This separation keeps the runtime bundle lightweight and follows the principle that migrations are a deployment concern, not a runtime concern.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bundle ¶
type Bundle struct {
// contains filtered or unexported fields
}
Bundle provides PostgreSQL integration for Forge applications.
func (*Bundle) Close ¶
Close is deprecated. Use Stop() instead for proper lifecycle integration. Maintained for backward compatibility.
func (*Bundle) HealthChecks ¶
func (b *Bundle) HealthChecks() []forgeHealth.Check
HealthChecks returns health checks for the PostgreSQL connection.
func (*Bundle) Initialize ¶
Initialize validates the configuration, opens the PostgreSQL connection pool, applies the configured pool limits, and verifies connectivity with a ping before the bundle is considered ready. It does not run migrations, which are treated as a deployment concern (see the package documentation).
type Config ¶
type Config struct {
// DatabaseURL is the PostgreSQL connection string.
// Example: "postgres://user:password@localhost:5432/dbname?sslmode=disable"
DatabaseURL string
// Connection pool configuration
MaxOpenConns int // Maximum number of open connections (default: 25)
MaxIdleConns int // Maximum number of idle connections (default: 10)
ConnMaxLifetime time.Duration // Maximum connection lifetime (default: 30 minutes)
ConnMaxIdleTime time.Duration // Maximum connection idle time (default: 15 minutes)
// Health check configuration
HealthCheckTimeout time.Duration // Timeout for health check queries (default: 5 seconds)
}
Config contains PostgreSQL-specific configuration options.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with sensible defaults.
type PostgreSQLHealthCheck ¶
type PostgreSQLHealthCheck struct {
// contains filtered or unexported fields
}
PostgreSQLHealthCheck implements health checking for PostgreSQL connections.
func (*PostgreSQLHealthCheck) Liveness ¶
func (c *PostgreSQLHealthCheck) Liveness(ctx context.Context) error
Liveness performs a basic connectivity check.
func (*PostgreSQLHealthCheck) Name ¶
func (c *PostgreSQLHealthCheck) Name() string
Name returns the health check name.
Source Files