README
¶
Database Package
Overview
The db package provides utilities for database connection management and operations in Go applications. It supports multiple database types and provides features for connection pooling, transaction management, and query execution.
Features
-
Connection Management:
- Connection pooling
- Automatic reconnection
- Health checks
-
Supported Databases:
- PostgreSQL (via pgx)
- SQLite
- MongoDB
-
Features:
- Transaction management
- Query execution with retries
- Result mapping
- Migrations
Installation
go get github.com/abitofhelp/servicelib/db
Quick Start
See the Connection Example for a complete, runnable example of how to connect to a database and execute basic operations.
Configuration
See the Repository Example for a complete, runnable example of how to configure the database package.
API Documentation
Core Types
Database
The Database interface provides methods for database operations.
See the Connection Example for a complete, runnable example of how to use the Database interface.
Transaction
The Transaction interface provides methods for transaction management.
See the Transaction Example for a complete, runnable example of how to use transactions.
Key Methods
New
The New function creates a new database connection.
See the Connection Example for a complete, runnable example.
Transaction
The Transaction method executes a function within a transaction.
See the Transaction Example for a complete, runnable example of how to use the Transaction method.
QueryWithRetries
The QueryWithRetries function executes a query with automatic retries.
See the Retry Example for a complete, runnable example of how to use the QueryWithRetries function.
Examples
For complete, runnable examples, see the following files in the examples directory:
- Connection Example - Shows how to connect to a database
- Query Example - Shows how to execute queries
- Transaction Example - Shows how to use transactions
- Retry Example - Shows how to use query retries
- Repository Example - Shows how to implement the repository pattern
- Health Check Example - Shows how to implement database health checks
Best Practices
-
Connection Pooling: Configure connection pools based on your application's needs and the database's capacity.
-
Transactions: Use transactions for operations that need to be atomic.
-
Prepared Statements: Use prepared statements to prevent SQL injection and improve performance.
-
Context: Always pass a context to database operations to enable cancellation and timeouts.
-
Error Handling: Handle database errors appropriately, distinguishing between different types of errors.
-
Repository Pattern: Use the repository pattern to abstract database access and make testing easier.
-
Migrations: Use database migrations to manage schema changes.
Troubleshooting
Common Issues
Connection Pool Exhaustion
Issue: The application runs out of database connections.
Solution: Configure the connection pool appropriately by setting max open connections, max idle connections, and connection lifetime. Monitor connection usage and adjust as needed.
Query Timeouts
Issue: Database queries are timing out.
Solution: Use context with timeouts for long-running queries. Optimize queries that are consistently slow. Consider using indexes or query optimization.
Transaction Deadlocks
Issue: Transactions are deadlocking.
Solution: Keep transactions short and focused. Avoid holding transactions open for long periods. Consider the order of operations to minimize lock contention.
Related Components
- Config - The config component is used to configure database connections.
- Logging - The logging component can be used to log database operations.
- Telemetry - The telemetry component can be used to monitor database performance.
- Transaction - The transaction component provides utilities for distributed transactions.
Contributing
Contributions to this component are welcome! Please see the Contributing Guide for more information.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package db provides utilities for working with databases.
Index ¶
- Constants
- func CheckMongoHealth(ctx context.Context, client *mongo.Client) error
- func CheckPostgresHealth(ctx context.Context, pool *pgxpool.Pool) error
- func CheckSQLiteHealth(ctx context.Context, db *sql.DB) error
- func ExecutePostgresTransaction(ctx context.Context, pool *pgxpool.Pool, fn func(tx pgx.Tx) error, ...) error
- func ExecuteSQLTransaction(ctx context.Context, db *sql.DB, fn func(tx *sql.Tx) error, ...) error
- func InitMongoClient(ctx context.Context, uri string, timeout time.Duration) (*mongo.Client, error)
- func InitPostgresPool(ctx context.Context, config PostgresConfig) (*pgxpool.Pool, error)
- func InitSQLiteDB(ctx context.Context, uri string, timeout, connMaxLifetime time.Duration, ...) (*sql.DB, error)
- func IsTransientError(err error) bool
- func LogDatabaseConnection(ctx context.Context, logger *logging.ContextLogger, dbType string)
- type MongoClientInterface
- type PgxPoolInterface
- type PgxTxInterface
- type PostgresConfig
- type RetryConfig
- type SQLDBInterface
- type SQLTxInterface
Constants ¶
const DefaultTimeout = 30 * time.Second
DefaultTimeout is the default timeout for database operations
Variables ¶
This section is empty.
Functions ¶
func CheckMongoHealth ¶
CheckMongoHealth checks if a MongoDB connection is healthy. Parameters:
- ctx: The context for the operation
- client: The MongoDB client
Returns:
- error: An error if the health check fails
func CheckPostgresHealth ¶
CheckPostgresHealth checks if a PostgreSQL connection is healthy. Parameters:
- ctx: The context for the operation
- pool: The PostgreSQL connection pool
Returns:
- error: An error if the health check fails
func CheckSQLiteHealth ¶
CheckSQLiteHealth checks if a SQLite connection is healthy. Parameters:
- ctx: The context for the operation
- db: The SQLite database connection
Returns:
- error: An error if the health check fails
func ExecutePostgresTransaction ¶
func ExecutePostgresTransaction(ctx context.Context, pool *pgxpool.Pool, fn func(tx pgx.Tx) error, retryConfig ...RetryConfig) error
ExecutePostgresTransaction executes a function within a PostgreSQL transaction. Parameters:
- ctx: The context for the operation
- pool: The PostgreSQL connection pool
- fn: The function to execute within the transaction
- retryConfig: Optional retry configuration for transient errors
Returns:
- error: An error if the transaction fails
func ExecuteSQLTransaction ¶
func ExecuteSQLTransaction(ctx context.Context, db *sql.DB, fn func(tx *sql.Tx) error, retryConfig ...RetryConfig) error
ExecuteSQLTransaction executes a function within a SQL transaction. Parameters:
- ctx: The context for the operation
- db: The SQL database connection
- fn: The function to execute within the transaction
- retryConfig: Optional retry configuration for transient errors
Returns:
- error: An error if the transaction fails
func InitMongoClient ¶
InitMongoClient initializes a MongoDB client. Parameters:
- ctx: The context for the operation
- uri: The MongoDB connection URI
- timeout: The timeout for the connection operation
Returns:
- *mongo.Client: The initialized MongoDB client
- error: An error if initialization fails
func InitPostgresPool ¶
InitPostgresPool initializes a PostgreSQL connection pool. Parameters:
- ctx: The context for the operation
- config: The PostgreSQL connection configuration
Returns:
- *pgxpool.Pool: The initialized PostgreSQL connection pool
- error: An error if initialization fails
func InitSQLiteDB ¶
func InitSQLiteDB(ctx context.Context, uri string, timeout, connMaxLifetime time.Duration, maxOpenConns, maxIdleConns int) (*sql.DB, error)
InitSQLiteDB initializes a SQLite database connection. Parameters:
- ctx: The context for the operation
- uri: The SQLite connection URI
- timeout: The timeout for the connection operation
- maxOpenConns: The maximum number of open connections
- maxIdleConns: The maximum number of idle connections
- connMaxLifetime: The maximum lifetime of a connection
Returns:
- *sql.DB: The initialized SQLite database connection
- error: An error if initialization fails
func IsTransientError ¶ added in v1.2.0
IsTransientError checks if an error is a transient database error that can be retried.
func LogDatabaseConnection ¶
func LogDatabaseConnection(ctx context.Context, logger *logging.ContextLogger, dbType string)
LogDatabaseConnection logs a successful database connection. Parameters:
- ctx: The context for the operation
- logger: The logger to use
- dbType: The type of database (e.g., "MongoDB", "PostgreSQL", "SQLite")
Types ¶
type MongoClientInterface ¶
type MongoClientInterface interface {
Ping(ctx context.Context, rp *readpref.ReadPref) error
Connect(ctx context.Context) error
Database(name string, opts ...*options.DatabaseOptions) *mongo.Database
}
MongoClientInterface defines the interface for mongo.Client operations
type PgxPoolInterface ¶
type PgxPoolInterface interface {
Ping(ctx context.Context) error
Begin(ctx context.Context) (pgx.Tx, error)
Close()
}
PgxPoolInterface defines the interface for pgxpool.Pool operations
type PgxTxInterface ¶
type PgxTxInterface interface {
Commit(ctx context.Context) error
Rollback(ctx context.Context) error
}
PgxTxInterface defines the interface for pgx.Tx operations
type PostgresConfig ¶ added in v1.2.0
type PostgresConfig struct {
// URI is the PostgreSQL connection URI
URI string
// Timeout is the timeout for connection operations
Timeout time.Duration
// MaxOpenConns is the maximum number of open connections
MaxConns int32
// MinOpenConns is the minimum number of open connections
MinConns int32
// MaxConnLifetime is the maximum lifetime of a connection
MaxConnLifetime time.Duration
// MaxConnIdleTime is the maximum idle time of a connection
MaxConnIdleTime time.Duration
// HealthCheckPeriod is the period between health checks
HealthCheckPeriod time.Duration
}
PostgresConfig holds configuration for a PostgreSQL connection pool.
type RetryConfig ¶ added in v1.2.0
type RetryConfig struct {
// MaxRetries is the maximum number of retry attempts
MaxRetries int
// InitialBackoff is the initial backoff duration
InitialBackoff time.Duration
// MaxBackoff is the maximum backoff duration
MaxBackoff time.Duration
// BackoffFactor is the factor by which the backoff increases
BackoffFactor float64
// Logger is the logger to use for logging retries
Logger *logging.ContextLogger
}
RetryConfig holds configuration for retry operations.
func DefaultRetryConfig ¶ added in v1.2.0
func DefaultRetryConfig() RetryConfig
DefaultRetryConfig returns the default retry configuration.
type SQLDBInterface ¶
type SQLDBInterface interface {
PingContext(ctx context.Context) error
BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
SetMaxOpenConns(n int)
SetMaxIdleConns(n int)
SetConnMaxLifetime(d time.Duration)
}
SQLDBInterface defines the interface for sql.DB operations
type SQLTxInterface ¶
SQLTxInterface defines the interface for sql.Tx operations
Source Files
Directories