Improve documentation of load_async

[casperisfine]

The feature is a bit under documented and since it is disabled by default I fear that it might cause confusion.

@eileencodes @rafaelfranca

[ghiculescu]

@byroot - @joshuay03 and I are trying to wrap our heads around what this means. Maybe an example would be helpful.

Our assumption is that the pool config in database.yml is per-process, which is why by default it matches the max thread count: 5 in puma.rb (for now), 5 in database.yml.

From what I've read (eg. here), if you're using async queries then you should probably have a pool of at least 10, so that each puma thread can also run 1 async query.

But then if this defaults to 4, then based on this logic you probably need a pool of 25.

Is this what you are trying to say here? If so could I suggest this wording:

This number must be considered in accordance with the database pool size configured in `database.yml`.
The connection pool should be large enough to accommodate both the foreground threads (.e.g web server or job worker threads) and background threads.
You can calculate this by doing `(thread_count + 1) * global_executor_concurrency`

For example, if your web server uses 3 threads per process, and you use the default setting (4) here, then in `database.yml` your `pool` config should be 16.

[byroot]

But then if this defaults to 4, then based on this logic you probably need a pool of 25.

No, it's 4 threads in addition to the 5 puma threads. The pool is global, each puma thread doesn't have its own async threads pool. They all share the same process global one.

So it's (puma_thread_count + 1) + global_executor_concurrency, not *