@spec checkin(pool_ref(), term()) :: :ok

Return a checked-out connection to the pool.

Always call this after checkout/2 to return the connection.

@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 reference
• opts - 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
  Postgrex.query!(conn, "BEGIN", [])
  Postgrex.query!(conn, "INSERT INTO ...", [...])
  Postgrex.query!(conn, "COMMIT", [])
after
  Selecto.ConnectionPool.checkin(pool, conn)
end

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec clear_cache(pool_ref()) :: :ok

Clear prepared statement cache for a pool.

@spec execute(pool_ref(), String.t(), list(), Keyword.t()) ::
  {:ok, Postgrex.Result.t()} | {:error, term()}

Execute a query using a pooled connection.

Automatically handles connection checkout/checkin and prepared statement caching.

@spec pool_stats(pool_ref()) :: map()

Get pool statistics for monitoring.

Returns information about pool health, connection counts, and cache statistics.

@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 configuration
• pool_options - Pool-specific options (optional)

returns

Returns

• {:ok, pool_ref} - Pool started successfully
• {:error, reason} - Pool startup failed

examples

Examples

# Start pool with Postgrex config (default adapter)
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: Selecto.DB.MySQL
)

@spec stop_pool(pool_ref()) :: :ok

Stop a connection pool.

Gracefully shuts down the pool and all its connections.

@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 ->
  Postgrex.query!(conn, "INSERT INTO orders ...", [...])
  Postgrex.query!(conn, "UPDATE inventory ...", [...])
end)

@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 ->
  Postgrex.query!(conn, "SELECT * FROM users", [])
end)