README
¶
This effort is just getting underway. There is nothing working here at this time.
The goal of this project is to deliver a package that will generate a pool of connections that will behave similar to the the stdlib database/sql pool but overcome some of its shortcomings for sqlite. The primary shortcoming from my experience is the inability to retain prepared queries when a connection is returned to the pool and to subsequently access these prepared statements when a connection is received from the pool.
Installation
To use this module in your Go project, you can use the go get command:
$ go get -u github.com/lbe/sqlitepool
Usage
TBD: Explain how users can import and use your module in their Go projects. Provide code examples if necessary.
package main
import (
"fmt"
"github.com/lbe/sqlitepool"
)
func main() {
// Example usage
fmt.Println(your_module_name.YourFunction())
}
Configuration
TBD: If your module has configuration options, document them here.
Contributing
TBD: Explain how others can contribute to your project. Include guidelines for reporting issues, submitting feature requests, and making pull requests.
License
This project is licensed under the MIT License - see the LICENSE.md file for details.
Acknowledgments
TBD: Give credit to any contributors, libraries, or tools that your module depends on.
Contact
Please contact me by adding issues to this repository.
Release History
See the RELEASE-NOTES.tpl.md file for details.
Support
If you encounter any issues or have questions, feel free to create an issue.
Documentation
¶
Overview ¶
Package sqlitepool provides a connection pool for SQLite databases using database/sql. It manages connection lifecycle including acquisition, validation, release and cleanup. The pool maintains both maximum total connections and minimum idle connections, automatically scaling between these bounds based on demand.
Package sqlitepool provides a template for Go modules. Simply clone this GitHub repository and start coding.
Index ¶
Constants ¶
const (
// Version holds the semantic version number of this module.
Version = "0.3.0"
)
Variables ¶
var ( // ErrPoolClosed is returned when attempting to get a connection from a closed pool. ErrPoolClosed = errors.New("connection pool is closed") ErrConnectionUnavailable = errors.New("no connections available and max connections reached") )
Common errors that can be returned by the connection pool.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// DriverName specifies the name of the database driver to use (e.g., "sqlite").
DriverName string
// Open connection in read-only mode.
ReadOnly bool
// Maximum number of connections the pool will create.
MaxConnections int64
// Minimum number of idle connections to maintain.
MinIdleConnections int64
// QueriesFunc is a function to instantiate a Queries object for a new connection.
QueriesFunc func(db queries.DBTX) *queries.Queries
// MonitorInterval specifies how often the connection maintenance monitor should run.
MonitorInterval time.Duration
}
Config holds the configuration parameters for DbSQLConnPool.
type ConnectionError ¶
type ConnectionError struct {
Op string // the operation that failed (e.g., "ping", "connect")
Err error // the underlying error
}
ConnectionError represents an error that occurred with a specific connection.
func (*ConnectionError) Error ¶
func (e *ConnectionError) Error() string
func (*ConnectionError) Unwrap ¶
func (e *ConnectionError) Unwrap() error
type CpConn ¶
type CpConn struct {
// Conn is the underlying database connection.
Conn *sql.Conn
// Queries holds the sqlc-generated query methods for this connection.
Queries *queries.Queries
}
CpConn wraps an underlying *sql.Conn and holds a set of prepared queries associated with that connection.
func (*CpConn) PragmaOptimize ¶
type DbSQLConnPool ¶
type DbSQLConnPool struct {
// Config holds the pool's configuration.
Config Config
// NumConnections is the current number of connections in the pool.
NumConnections atomic.Int64
// contains filtered or unexported fields
}
DbSQLConnPool manages a pool of SQL database connections. It provides thread-safe access to connections through a buffered channel, maintains connection health, and automatically scales the pool size.
func NewDbSQLConnPool ¶
func NewDbSQLConnPool(ctx context.Context, dataSourceName string, config Config) (*DbSQLConnPool, error)
NewDbSQLConnPool creates a new connection pool with the specified parameters. driverName and dataSourceName are passed to sql.Open to create the base pool. config specifies the pool's connection limits and behavior. Returns error if the database connection cannot be established.
func (*DbSQLConnPool) Close ¶
func (p *DbSQLConnPool) Close() error
Close initiates a graceful shutdown of the connection pool and releases all resources. It signals the Monitor goroutine to stop, closes all idle connections, the connections channel, and the underlying sql.DB. Returns error if the underlying pool close operation fails. After Close() is called, all subsequent Put() operations will close their connections.
func (*DbSQLConnPool) DB ¶
func (p *DbSQLConnPool) DB() *sql.DB
DB returns the underlying *sql.DB instance. This method should be used with caution, primarily for tools like database migrators that require direct access to the `*sql.DB` object. The connection pool should not be in active use when the returned `*sql.DB` is being manipulated.
func (*DbSQLConnPool) DbStats ¶
func (p *DbSQLConnPool) DbStats() sql.DBStats
DbStats returns database/sql DBStats for the underlying sql.DB pool.
func (*DbSQLConnPool) Get ¶
func (p *DbSQLConnPool) Get() (*CpConn, error)
Get acquires a connection from the pool. It will: - Return an existing idle connection if available - Create a new connection if below maxConnections - Block waiting for a connection if at maxConnections Each returned connection is validated with PingContext before return. Returns error if connection cannot be established or validated.
func (*DbSQLConnPool) Monitor ¶
func (p *DbSQLConnPool) Monitor()
Monitor maintains the pool's connection count within configured bounds. Running as a goroutine, it periodically: - Creates new connections if idle count is below minIdleConnections - Closes excess idle connections if above minIdleConnections - Validates connections before adding them to the idle pool Exits when context is cancelled or done channel is closed.
func (*DbSQLConnPool) NumIdleConnections ¶
func (p *DbSQLConnPool) NumIdleConnections() int
NumIdleConnections returns the current number of idle connections in the pool.
func (*DbSQLConnPool) Put ¶
func (p *DbSQLConnPool) Put(cpc *CpConn)
Put returns a connection to the pool for reuse. The connection is added to the idle pool via the connections channel if the pool is not closed. If the pool is closed, the connection is closed immediately. This operation never blocks as the channel is buffered to maxConnections.
Source Files
Directories