PostgresSQL Client: pool vs pooled client confusion

[Mark G]

I need a little help understanding the difference between a "pool" and a "pooled client." I think my confusion is a result of the inconsistent usage of these terms in the documentation for the PostgresSQL Client.

From what I understand so far, PgPool.pool() creates a pool of connections...

// io/vertx/pgclient/PgPool.java#L127-L129

static PgPool pool(Vertx vertx, List<PgConnectOptions> databases, PoolOptions poolOptions) {

    return (PgPool) PgDriver.INSTANCE.createPool(vertx, databases, poolOptions);

}

And PgPool.client() looks like it too creates a "pool" (?), but unlike PgPool.pool(), pipelining is enabled...

// io/vertx/pgclient/PgPool.java#L200-L202

static SqlClient client(Vertx vertx, List<PgConnectOptions> databases, PoolOptions options) {

    return PgDriver.INSTANCE.createPool(vertx, databases, new PgPoolOptions(options).setPipelined(true));

}

Does the choice to use PgPool.pool() over PgPool.client() just come down to whether or not you want pipelining? Here's where I think I start getting confused. The example in the "Pool versus pooled client" section of the docs appears to imply that PgPool.pool().query() will not be pipelined whereas PgPool.client().query() will. So far so good, but if you look at the example in the previous section (Command Pipelining), it sounds like you actually can enable pipelining in PgPool.pool() after all?

// vertx-pg-client/java/#_command_pipelining

PgPool pool = PgPool.pool(vertx, connectOptions.setPipeliningLimit(16), poolOptions);

Also, if you search the documentation page for the exact phrase "the pooled client" (e.g., used in code comments from the examples) you'll find it flip-flops between being associated with both PgPool.pool() and PgPool.client().

These two bullet points are from the docs:

• pool operations are not pipelined, only connections acquired from the pool are pipelined
  
• pooled client operations are pipelined, you cannot acquire a connection from a pooled client
  

Is the first bullet point referring to PgPool.pool() and the second to PgPool.client() or do I have that reversed?

The second bullet point notes that "you cannot acquire a connection from a pooled client." Does this mean then it's not actually a "pool of connections" despite PgPool.client()'s underlying call to PgDriver.INSTANCE.createPool()? Is PgPool.pool() generally preferred?

The docs mention to use a "pool" to connect to PostgreSQL "most of the time". According to the docs, an example to illustrate that point used PgPool.client(), but shouldn't that example use PgPool.pool() instead?

Any help is appreciated!

[Julien Viet]

Hi,

as you said:

- the Pool is a pool of connection that you can borrow or perform pool
operations (pool.query()...)
- the pooled client is a SqlClient that uses under the hood of pool of
connections that only allows to perform pool operations
(pool.query()...)

A pool operation is:
- borrow any connection from the pool
- perform the operation
- return the connection to the pool immediately

Pipelining on a connection requires you to use the connection exclusively.

- when you use a Pool, operations can be pipelined on a connection
because you acquire the connection and the pipelining constraint is
satisfied
- Pool operations can only be pipelined if there is the guarantee that
nobody else will use the connection on which pipelining happens so it
excludes Pool because one can acquire a connection and only a pooled
client can do it

In practice
- if you don't use pipelining
- use a Pool and either acquire connection or perform pool operations
- if you use pipelining
- if you perform one shot operations then use a pooled client
- otherwise use a Pool and acquire connections
- if you need both : create a Pool and a pooled client and use
them for each scenario

HTH

Julien

> --
> You received this message because you are subscribed to the Google Groups "vert.x" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to vertx+un...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/vertx/6b7593ea-a40e-40bd-ba48-0c87cf38bbean%40googlegroups.com.