Missing documentation for Pool

[bryanoltman]

I am migrating my app away from the discontinued postgres_pool. The documentation for this package says that pooling is supported, but there is no documentation that the Pool class exists or how to use it. Reading through the doc comments has helped, but it's still not clear what reasonable/correct use of "locality" is.

[isoos]

@bryanoltman: locality is useful if you have (1) a sharded (e.g. multiple database instances), (2) a distributed (e.g. cockroachdb) database system or (3) custom fallback rules for connecting to a read-only replica. I don't have a public implementation for any of the use cases yet, and if you don't have these use-cases, you can safely ignore it.

If you have any of these, I'm happy to take PRs that create public implementation for these.

[bryanoltman]

I don't – I'm not totally sure what that would look like, to be honest. I've been using Pool<void> to silence the analyzer warnings, but I'm not positive this is correct.

[isoos]

@bryanoltman: yeah, that is fine.

[bryanoltman]

Good to know. I think updating the readme to include a code snippet under the Connection pooling header would be useful.