Controlling Pool Size with min_pool_size and max_pool_size

Configuration options

Base workers = idle workers + busy workers. Overflow workers created via max_overflow are not counted.

Setting an upper bound with max_pool_size

Use max_pool_size when you want to prevent the pool from growing beyond a certain size even if callers request more workers at runtime.

children = [
  {Poolex,
    worker_module: MyApp.Worker,
    workers_count: 10,
    max_pool_size: 20}
]

Supervisor.start_link(children, strategy: :one_for_one)

If add_idle_workers!/2 is called and adding all requested workers would exceed the limit, only as many workers as the remaining headroom allows are started. The rest are skipped and an error is logged:

Failed to add 5 worker(s): max_pool_size limit of 20 reached

Setting a lower bound with min_pool_size

Use min_pool_size to guarantee that the pool never shrinks below a certain number of base workers, even when callers request removals at runtime.

children = [
  {Poolex,
    worker_module: MyApp.Worker,
    workers_count: 10,
    min_pool_size: 5}
]

Supervisor.start_link(children, strategy: :one_for_one)

If remove_idle_workers!/2 is called and removing all requested workers would drop the base count below the minimum, only as many workers as the available headroom allows are removed. The rest are skipped and an error is logged:

Failed to remove 3 worker(s): min_pool_size limit of 5 reached

Using both options together

You can combine both options to define an allowed range for the pool size:

children = [
  {Poolex,
    worker_module: MyApp.Worker,
    workers_count: 10,
    min_pool_size: 5,
    max_pool_size: 20}
]

Supervisor.start_link(children, strategy: :one_for_one)

min_pool_size must be less than or equal to max_pool_size. If this invariant is violated at startup, an ArgumentError is raised:

ArgumentError: min_pool_size (10) must be <= max_pool_size (5)

Validation rules

The following values are rejected at startup with an ArgumentError:

• max_pool_size is not a positive integer and is not :infinity
• min_pool_size is not a non-negative integer
• min_pool_size > max_pool_size

Partial execution

Both add_idle_workers!/2 and remove_idle_workers!/2 always return :ok. When a limit prevents some workers from being added or removed, the operation is applied partially — as many workers as the limit allows are processed, and the remainder are skipped after logging an error message.

When to use these options

• max_pool_size: when you want a hard cap on resource usage (e.g., database connections) and use add_idle_workers!/2 to scale up dynamically.
• min_pool_size: when you need a guaranteed pool floor (e.g., always keep at least N workers warm) and use remove_idle_workers!/2 to scale down during low traffic.
• Both together: when you manage pool size dynamically and want guardrails in both directions.