Add support for level 7 proxies (PgBouncer with pool_mode=transaction) in Postgres client.

Author: vietj

vertx-pg-client/pom.xml

@@ -114,6 +114,7 @@
       <version>${jmh.version}</version>
       <scope>test</scope>
     </dependency>
+
   </dependencies>
 
   <build>

vertx-pg-client/src/main/asciidoc/index.adoc

@@ -20,6 +20,7 @@ The client is reactive and non-blocking, allowing to handle many database connec
 * SSL/TLS
 * Unix domain socket
 * HTTP/1.x CONNECT, SOCKS4a or SOCKS5 proxy support
+* Proxy (level 4 and 7) support
 
 == Usage
 
@@ -564,12 +565,32 @@ All https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION[
 
 More information can be found in the http://vertx.io/docs/vertx-core/java/#ssl[Vert.x documentation].
 
-== Using a proxy
+== Using a level 4 proxy
 
-You can also configure the client to use an HTTP/1.x CONNECT, SOCKS4a or SOCKS5 proxy.
+You can configure the client to use an HTTP/1.x CONNECT, SOCKS4a or SOCKS5 level 4 proxy.
 
 More information can be found in the http://vertx.io/docs/vertx-core/java/#_using_a_proxy_for_client_connections[Vert.x documentation].
 
+== Using a level 7 proxy
+
+Level 7 proxies can load balance queries on several connections to the actual database. When it happens, the client can be confused by the lack of session affinity and unwanted errors can happen like _ERROR: unnamed prepared statement does not exist (26000)_.
+
+Supported proxies:
+
+- https://www.pgbouncer.org[PgBouncer] configured with `_pool_mode=transaction`.
+
+You can configure the client to interact differently to the proxy:
+
+[source,$lang]
+----
+{@link examples.PgClientExamples#pgBouncer}
+----
+
+When doing so, prepared statement cannot be cached and therefore
+
+- prepared statement caching must be disabled
+- explicit prepared statement can only live within the scope of a transaction, it means you can use cursors but the prepared statement for the cursor must be created and destroyed within the scope of a transaction
+
 == Advanced pool configuration
 
 include::pool_config.adoc[]

vertx-pg-client/src/main/generated/io/vertx/pgclient/PgConnectOptionsConverter.java

@@ -30,6 +30,11 @@ public static void fromJson(Iterable<java.util.Map.Entry<String, Object>> json,
             obj.setSslMode(io.vertx.pgclient.SslMode.valueOf((String)member.getValue()));
           }
           break;
+        case "useLayer7Proxy":
+          if (member.getValue() instanceof Boolean) {
+            obj.setUseLayer7Proxy((Boolean)member.getValue());
+          }
+          break;
       }
     }
   }
@@ -43,5 +48,6 @@ public static void toJson(PgConnectOptions obj, java.util.Map<String, Object> js
     if (obj.getSslMode() != null) {
       json.put("sslMode", obj.getSslMode().name());
     }
+    json.put("useLayer7Proxy", obj.getUseLayer7Proxy());
   }
 }

vertx-pg-client/src/main/java/examples/PgClientExamples.java

@@ -732,4 +732,8 @@ public void batchReturning(SqlClient client) {
         }
       });
   }
+
+  public void pgBouncer(PgConnectOptions connectOptions) {
+    connectOptions.setUseLayer7Proxy(true);
+  }
 }

vertx-pg-client/src/main/java/io/vertx/pgclient/PgConnectOptions.java

@@ -18,6 +18,7 @@
 package io.vertx.pgclient;
 
 import io.vertx.codegen.annotations.GenIgnore;
+import io.vertx.codegen.annotations.Unstable;
 import io.vertx.core.tracing.TracingPolicy;
 import io.vertx.pgclient.impl.PgConnectionUriParser;
 import io.vertx.codegen.annotations.DataObject;
@@ -111,6 +112,7 @@ public static PgConnectOptions fromEnv() {
   public static final String DEFAULT_PASSWORD = "pass";
   public static final int DEFAULT_PIPELINING_LIMIT = 256;
   public static final SslMode DEFAULT_SSLMODE = SslMode.DISABLE;
+  public static final boolean DEFAULT_USE_LAYER_7_PROXY = false;
   public static final Map<String, String> DEFAULT_PROPERTIES;
 
   static {
@@ -124,6 +126,7 @@ public static PgConnectOptions fromEnv() {
 
   private int pipeliningLimit = DEFAULT_PIPELINING_LIMIT;
   private SslMode sslMode = DEFAULT_SSLMODE;
+  private boolean useLayer7Proxy = DEFAULT_USE_LAYER_7_PROXY;
 
   public PgConnectOptions() {
     super();
@@ -235,6 +238,27 @@ public PgConnectOptions setSslMode(SslMode sslmode) {
     return this;
   }
 
+  /**
+   * @return whether the client interacts with a layer 7 proxy instead of a server
+   */
+  @Unstable
+  public boolean getUseLayer7Proxy() {
+    return useLayer7Proxy;
+  }
+
+  /**
+   * Set the client to use a layer 7 (application) proxy compatible protocol, set to {@code true} when the client
+   * interacts with a layer 7 proxy like PgBouncer instead of a server. Prepared statement caching must be disabled.
+   *
+   * @param useLayer7Proxy whether to use a layer 7 proxy instead of a server
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Unstable
+  public PgConnectOptions setUseLayer7Proxy(boolean useLayer7Proxy) {
+    this.useLayer7Proxy = useLayer7Proxy;
+    return this;
+  }
+
   @Override
   public PgConnectOptions setSendBufferSize(int sendBufferSize) {
     return (PgConnectOptions)super.setSendBufferSize(sendBufferSize);

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/PgConnectionFactory.java

@@ -45,16 +45,21 @@ public class PgConnectionFactory extends ConnectionFactoryBase {
 
   private SslMode sslMode;
   private int pipeliningLimit;
+  private boolean useLayer7Proxy;
 
   public PgConnectionFactory(VertxInternal context, PgConnectOptions options) {
     super(context, options);
+    if (options.getCachePreparedStatements() && options.getUseLayer7Proxy()) {
+      throw new IllegalArgumentException("Prepared statement caching must be disabled when using proxy mode");
+    }
   }
 
   @Override
   protected void initializeConfiguration(SqlConnectOptions connectOptions) {
     PgConnectOptions options = (PgConnectOptions) connectOptions;
     this.pipeliningLimit = options.getPipeliningLimit();
     this.sslMode = options.isUsingDomainSocket() ? SslMode.DISABLE : options.getSslMode();
+    this.useLayer7Proxy = options.getUseLayer7Proxy();
 
     // check ssl mode here
     switch (sslMode) {
@@ -162,6 +167,6 @@ public Future<SqlConnection> connect(Context context) {
   }
 
   private PgSocketConnection newSocketConnection(EventLoopContext context, NetSocketInternal socket) {
-    return new PgSocketConnection(socket, cachePreparedStatements, preparedStatementCacheSize, preparedStatementCacheSqlFilter, pipeliningLimit, context);
+    return new PgSocketConnection(socket, cachePreparedStatements, preparedStatementCacheSize, preparedStatementCacheSqlFilter, pipeliningLimit, useLayer7Proxy, context);
   }
 }

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/PgSocketConnection.java

@@ -50,6 +50,7 @@
 public class PgSocketConnection extends SocketConnectionBase {
 
   private PgCodec codec;
+  private final boolean useLayer7Proxy;
   public int processId;
   public int secretKey;
   public PgDatabaseMetadata dbMetaData;
@@ -59,13 +60,15 @@ public PgSocketConnection(NetSocketInternal socket,
                             int preparedStatementCacheSize,
                             Predicate<String> preparedStatementCacheSqlFilter,
                             int pipeliningLimit,
+                            boolean useLayer7Proxy,
                             EventLoopContext context) {
     super(socket, cachePreparedStatements, preparedStatementCacheSize, preparedStatementCacheSqlFilter, pipeliningLimit, context);
+    this.useLayer7Proxy = useLayer7Proxy;
   }
 
   @Override
   public void init() {
-    codec = new PgCodec();
+    codec = new PgCodec(useLayer7Proxy);
     ChannelPipeline pipeline = socket.channelHandlerContext().pipeline();
     pipeline.addBefore("handler", "codec", codec);
     super.init();

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/codec/ExtendedQueryCommandCodec.java

@@ -48,12 +48,18 @@ void encode(PgEncoder encoder) {
           completionHandler.handle(CommandResponse.failure("Can not execute batch query with 0 sets of batch parameters."));
           return;
         } else {
+          if (encoder.useLayer7Proxy) {
+            encoder.writeParse(ps.sql, ps.bind.statement, new DataType[0]);
+          }
           for (TupleInternal param : cmd.paramsList()) {
             encoder.writeBind(ps.bind, cmd.cursorId(), param);
             encoder.writeExecute(cmd.cursorId(), cmd.fetch());
           }
         }
       } else {
+        if (encoder.useLayer7Proxy && ps.bind.statement.length == 1) {
+          encoder.writeParse(ps.sql, ps.bind.statement, new DataType[0]);
+        }
         encoder.writeBind(ps.bind, cmd.cursorId(), cmd.params());
         encoder.writeExecute(cmd.cursorId(), cmd.fetch());
       }

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/codec/PgCodec.java

@@ -29,9 +29,9 @@ public class PgCodec extends CombinedChannelDuplexHandler<PgDecoder, PgEncoder>
 
   private final ArrayDeque<PgCommandCodec<?, ?>> inflight = new ArrayDeque<>();
 
-  public PgCodec() {
+  public PgCodec(boolean useLayer7Proxy) {
     PgDecoder decoder = new PgDecoder(inflight);
-    PgEncoder encoder = new PgEncoder(inflight);
+    PgEncoder encoder = new PgEncoder(useLayer7Proxy, inflight);
     init(decoder, encoder);
   }
 

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/codec/PgEncoder.java

@@ -62,12 +62,14 @@ final class PgEncoder extends ChannelOutboundHandlerAdapter {
   private static final byte SYNC = 'S';
 
   private final ArrayDeque<PgCommandCodec<?, ?>> inflight;
+  final boolean useLayer7Proxy;
   private ChannelHandlerContext ctx;
   private ByteBuf out;
   private final HexSequence psSeq = new HexSequence(); // used for generating named prepared statement name
   boolean closeSent;
 
-  PgEncoder(ArrayDeque<PgCommandCodec<?, ?>> inflight) {
+  PgEncoder(boolean useLayer7Proxy, ArrayDeque<PgCommandCodec<?, ?>> inflight) {
+    this.useLayer7Proxy = useLayer7Proxy;
     this.inflight = inflight;
   }