Selecto.ConnectionPool (Selecto v0.4.3)
Connection pooling and management for Selecto.
Provides a high-performance connection pool using DBConnection for efficient database connection reuse, prepared statement caching, and connection health monitoring.
features
Features
- Connection pooling with configurable pool sizes
- Prepared statement caching for repeated queries
- Connection health monitoring and automatic recovery
- Adapter-owned pool startup and pooled execution
- Graceful fallback to direct connections when pooling is disabled
configuration
Configuration
# Application config
config :selecto, Selecto.ConnectionPool,
pool_size: 10,
max_overflow: 20,
prepared_statement_cache_size: 1000,
connection_timeout: 5000,
checkout_timeout: 5000
usage
Usage
# Start a connection pool
{:ok, pool} = Selecto.ConnectionPool.start_pool(connection_input)
# Configure Selecto with pooled connection
selecto = Selecto.configure(domain, {:pool, pool})
# Or use default pool management
selecto = Selecto.configure(domain, connection_input, pool: true)Link to this section Summary
Functions
Return a checked-out connection to the pool.
Checkout a connection from the pool for manual management.
Returns a specification to start this module under a supervisor.
Clear prepared statement cache for a pool.
Execute a query using a pooled connection.
Get pool statistics for monitoring.
Start a connection pool with the given configuration.
Stop a connection pool.
Execute a transaction on a pooled connection.
Execute a function with a checked-out connection.
Link to this section Types
connection_config()
pool_options()
@type pool_options() :: Keyword.t()
pool_ref()
Link to this section Functions
checkin(pool_ref, arg2)
Return a checked-out connection to the pool.
Always call this after checkout/2 to return the connection.
checkout(pool_ref, opts \\ [])
@spec checkout(pool_ref(), Keyword.t()) :: {:ok, DBConnection.conn()} | {:error, term()}
Checkout a connection from the pool for manual management.
This is useful for transactions or when you need to execute multiple queries on the same connection.
parameters
Parameters
pool_ref- The pool referenceopts- Options including :timeout
returns
Returns
{:ok, connection_ref}- Connection checked out successfully{:error, reason}- Checkout failed
examples
Examples
{:ok, conn} = Selecto.ConnectionPool.checkout(pool)
try do
run_checkout_queries(conn)
after
Selecto.ConnectionPool.checkin(pool, conn)
endchild_spec(init_arg)
Returns a specification to start this module under a supervisor.
See Supervisor.
clear_cache(pool_ref)
@spec clear_cache(pool_ref()) :: :ok
Clear prepared statement cache for a pool.
execute(pool_ref, query, params, opts \\ [])
Execute a query using a pooled connection.
Automatically handles connection checkout/checkin and prepared statement caching.
generate_cache_key(query)
generate_pool_name(connection_config)
get_manager_pid(pool_name)
get_pool_pid(pool_pid)
pool_stats(pool_ref)
Get pool statistics for monitoring.
Returns information about pool health, connection counts, and cache statistics.
start_link(opts)
@spec start_link(keyword()) :: GenServer.on_start()
start_pool(connection_config, pool_options \\ [])
@spec start_pool(connection_config(), pool_options()) :: {:ok, pool_ref()} | {:error, term()}
Start a connection pool with the given configuration.
parameters
Parameters
connection_config- Database connection configurationpool_options- Pool-specific options (optional)
returns
Returns
{:ok, pool_ref}- Pool started successfully{:error, reason}- Pool startup failed
examples
Examples
# Start pool with default adapter config
config = [
hostname: "localhost",
username: "user",
password: "pass",
database: "mydb"
]
{:ok, pool} = Selecto.ConnectionPool.start_pool(config)
# Start pool with custom options and adapter
{:ok, pool} = Selecto.ConnectionPool.start_pool(config,
pool_size: 20,
adapter: SelectoDBMySQL.Adapter
)stop_pool(pool_pid)
@spec stop_pool(pool_ref()) :: :ok
Stop a connection pool.
Gracefully shuts down the pool and all its connections.
transaction(pool_ref, fun, opts \\ [])
@spec transaction(pool_ref(), (DBConnection.conn() -> result), Keyword.t()) :: {:ok, result} | {:error, term()} when result: term()
Execute a transaction on a pooled connection.
All queries in the function are executed within a database transaction.
examples
Examples
Selecto.ConnectionPool.transaction(pool, fn conn ->
run_transaction_steps(conn)
end)with_connection(pool_ref, fun)
@spec with_connection(pool_ref(), (DBConnection.conn() -> result)) :: {:ok, result} | {:error, term()} when result: term()
Execute a function with a checked-out connection.
This is the recommended way to use connections for multiple operations. The connection is automatically returned to the pool when the function completes.
examples
Examples
Selecto.ConnectionPool.with_connection(pool, fn conn ->
run_queries_with_adapter_connection(conn)
end)