Unable to connect to a Unix Domain Socket without native transport on JDK16+ (eclipse-vertx#1635)

See eclipse-vertx#1634

Replaced native transport enabled check with UDS supported check and updated tests.
Fixed documentation and examples.

Fix documentation

Some portions of this content were created with the assistance of IBM Bob

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

Author: tsegismont

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

@@ -23,7 +23,7 @@ The client is reactive and non-blocking, allowing to handle many database connec
 * MySQL utilities commands support
 * Working with MySQL and MariaDB
 * Rich collation and charset support
-* Unix domain socket
+* Unix Domain Socket
 
 == Usage
 
@@ -132,42 +132,16 @@ include::pool_sharing.adoc[]
 
 === Unix Domain Socket
 
-Sometimes for simplicity, security or performance reasons, it is required to connect via a https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_socket[Unix Domain Socket].
+Sometimes for simplicity, security, or performance reasons, it is required to connect via a https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_socket[Unix Domain Socket].
 
-Since the JVM does not support domain sockets, first you must add native transport extensions to your project.
-
-* Maven (in your `pom.xml`):
-
-[source,xml]
-----
-<dependency>
-  <groupId>io.netty</groupId>
-  <artifactId>netty-transport-native-epoll</artifactId>
-  <version>${netty.version}</version>
-  <classifier>linux-x86_64</classifier>
-</dependency>
-----
-* Gradle (in your `build.gradle` file):
-
-[source,groovy]
-----
-dependencies {
-  compile 'io.netty:netty-transport-native-epoll:${netty.version}:linux-x86_64'
-}
-----
-
-NOTE: The native `epoll` support for ARM64 can also be added with the classifier `linux-aarch64`.
-
-NOTE: If there are Mac users in your team, add `netty-transport-native-kqueue` with the classifier `osx-x86_64`.
-
-Then set the path to the domain socket in {@link io.vertx.mysqlclient.MySQLConnectOptions#setHost MySQLConnectOptions#setHost}:
+To do so, set the path to the domain socket in {@link io.vertx.mysqlclient.MySQLConnectOptions#setHost MySQLConnectOptions#setHost}:
 
 [source,$lang]
 ----
 {@link examples.MySQLClientExamples#connectWithUnixDomainSocket}
 ----
 
-More information about native transports can be found in the [Vert.x documentation](https://vertx.io/docs/vertx-core/java/#_native_transports).
+NOTE: Unix Domain Sockets are supported when running on JDK 16+, or using a link:/docs/vertx-core/java/#_native_transports[native transport].
 
 == Configuration
 

vertx-mysql-client/src/main/java/examples/MySQLClientExamples.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
@@ -290,15 +290,6 @@ public void connectWithUnixDomainSocket(Vertx vertx) {
       .connectingTo(connectOptions)
       .using(vertx)
       .build();
-
-    // Create the pooled client with a vertx instance
-    // Make sure the vertx instance has enabled native transports
-    // vertxOptions.setPreferNativeTransport(true);
-    Pool client2 = MySQLBuilder.pool()
-      .with(poolOptions)
-      .connectingTo(connectOptions)
-      .using(vertx)
-      .build();
   }
 
   public void reconnectAttempts(MySQLConnectOptions options) {

vertx-mysql-client/src/main/java/io/vertx/mysqlclient/impl/MySQLConnectionImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
@@ -25,11 +25,13 @@
 import io.vertx.sqlclient.internal.SqlConnectionBase;
 import io.vertx.sqlclient.spi.ConnectionFactory;
 
+import static io.vertx.sqlclient.impl.ConnectionFactoryBase.UDS_NOT_SUPPORTED;
+
 public class MySQLConnectionImpl extends SqlConnectionBase<MySQLConnectionImpl> implements MySQLConnection {
 
   public static Future<MySQLConnection> connect(ContextInternal ctx, MySQLConnectOptions options) {
-    if (options.isUsingDomainSocket() && !ctx.owner().isNativeTransportEnabled()) {
-      return ctx.failedFuture("Native transport is not available");
+    if (options.isUsingDomainSocket() && !ctx.owner().transport().supportsDomainSockets()) {
+      return ctx.failedFuture(UDS_NOT_SUPPORTED);
     }
     MySQLConnectionFactory client;
     try {

vertx-mysql-client/src/test/java/io/vertx/tests/mysqlclient/MySQLUnixDomainSocketTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2020 Contributors to the Eclipse Foundation
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
@@ -28,6 +28,7 @@
 import java.io.UnsupportedEncodingException;
 import java.net.URLEncoder;
 
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assume.assumeTrue;
 
@@ -51,7 +52,10 @@ public void setUp() {
       options.setHost(rule.domainSocketPath());
     }
     assumeTrue(options.isUsingDomainSocket());
-    vertx = Vertx.vertx(new VertxOptions().setPreferNativeTransport(true));
+    // Only use native transport for JDK < 16 (Unix domain socket support added in JDK 16)
+    boolean useNativeTransport = Runtime.version().feature() < 16;
+    vertx = Vertx.vertx(new VertxOptions().setPreferNativeTransport(useNativeTransport));
+    assertEquals(useNativeTransport, vertx.isNativeTransportEnabled());
   }
 
   @After
@@ -93,7 +97,10 @@ public void simpleConnect(TestContext context) {
 
   @Test
   public void connectWithVertxInstance(TestContext context) {
-    Vertx vertx = Vertx.vertx(new VertxOptions().setPreferNativeTransport(true));
+    // Only use native transport for JDK < 16 (Unix domain socket support added in JDK 16)
+    boolean useNativeTransport = Runtime.version().feature() < 16;
+    Vertx vertx = Vertx.vertx(new VertxOptions().setPreferNativeTransport(useNativeTransport));
+    assertEquals(useNativeTransport, vertx.isNativeTransportEnabled());
     try {
       client = MySQLBuilder.pool(builder -> builder.connectingTo(new MySQLConnectOptions(options)).using(vertx));
       Async async = context.async();

vertx-pg-client/README.adoc

@@ -19,7 +19,7 @@ Documentation:
 - Direct memory to object without unnecessary copies
 - Java 8 Date and Time
 - SSL/TLS
-- Unix domain socket
+- Unix Domain Socket
 - HTTP/1.x CONNECT, SOCKS4a or SOCKS5 proxy
 - Request cancellation
 
@@ -66,11 +66,8 @@ You need to add some properties for testing:
 - connection.uri(mandatory): configure the client to connect the specified database
 - tls.connection.uri(mandatory): configure the client to run `TLSTest` with the specified Postgres with SSL enabled
 - tls.force.connection.uri(mandatory): configure the client to run `TLSTest` with the specified Postgres with SSL forced (only option)
-- unix.socket.directory(optional): the single unix socket directory(multiple socket directories are not supported) to test Unix domain socket with a specified database, domain socket tests will be skipped if this property is not specified
-(Note: Make sure you can access the unix domain socket with this directory under your host machine)
-- unix.socket.port(optional): unix socket file is named `.s.PGSQL.nnnn` and `nnnn` is the server's port number,
-this property is mostly used when you test with Docker, when you publish your Postgres container port other than 5432 in your host but Postgres may actually listen on a different port in the container,
-you will then need this property to help you connect the Postgres with Unix domain socket
+- unix.socket.directory(optional): the single unix socket directory(multiple socket directories are not supported) to test Unix Domain Socket with a specified database, domain socket tests will be skipped if this property is not specified (Note: Make sure you can access the Unix Domain Socket with this directory under your host machine)
+- unix.socket.port(optional): unix socket file is named `.s.PGSQL.nnnn` and `nnnn` is the server's port number, this property is mostly used when you test with Docker, when you publish your Postgres container port other than 5432 in your host but Postgres may actually listen on a different port in the container, you will then need this property to help you connect the Postgres with Unix Domain Socket
 
 === Testing with Docker
 

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

@@ -18,7 +18,7 @@ The client is reactive and non-blocking, allowing to handle many database connec
 * Direct memory to object without unnecessary copies
 * Java 8 Date and Time
 * SSL/TLS
-* Unix domain socket
+* Unix Domain Socket
 * HTTP/1.x CONNECT, SOCKS4a or SOCKS5 proxy support
 * Proxy (level 4 and 7) support
 
@@ -123,18 +123,18 @@ The {@link io.vertx.pgclient.PgBuilder} allows you to create a pool or a pooled
 
 include::pool_sharing.adoc[]
 
-== Unix domain sockets
+== Unix Domain Socket
 
-Sometimes you want to improve performance via Unix domain socket connection, we achieve this with Vert.x Native transports.
+Sometimes for simplicity, security, or performance reasons, it is required to connect via a Unix Domain Socket.
 
-Make sure you have added the required `netty-transport-native` dependency in your classpath and enabled the Unix domain socket option.
+To do so, set the path to the domain socket in {@link io.vertx.pgclient.PgConnectOptions#setHost PgConnectOptions#setHost}:
 
 [source,$lang]
 ----
 {@link examples.PgClientExamples#unixDomainSockets}
 ----
 
-More information can be found in the https://vertx.io/docs/vertx-core/java/#_native_transports[Vert.x documentation].
+NOTE: Unix Domain Sockets are supported when running on JDK 16+, or using a link:/docs/vertx-core/java/#_native_transports[native transport].
 
 == Connect retries
 

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

@@ -1,18 +1,12 @@
 /*
- * Copyright (C) 2017 Julien Viet
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
  *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
  */
 
 package examples;
@@ -334,14 +328,6 @@ public void unixDomainSockets(Vertx vertx) {
 
     // Create the pooled client
     Pool client = PgBuilder
-      .pool()
-      .connectingTo(connectOptions)
-      .with(poolOptions)
-      .build();
-
-    // Create the pooled client with a vertx instance
-    // Make sure the vertx instance has enabled native transports
-    Pool client2 = PgBuilder
       .pool()
       .connectingTo(connectOptions)
       .with(poolOptions)

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

@@ -1,18 +1,12 @@
 /*
- * Copyright (C) 2017 Julien Viet
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
  *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
  */
 
 package io.vertx.pgclient.impl;
@@ -159,8 +153,8 @@ private Future<Connection> doConnect(ConnectOptions connectOptions, ContextInter
   @Override
   public Future<SqlConnection> connect(Context context, PgConnectOptions options) {
     ContextInternal contextInternal = (ContextInternal) context;
-    if (options.isUsingDomainSocket() && !vertx.isNativeTransportEnabled()) {
-      return contextInternal.failedFuture(new IllegalArgumentException(NATIVE_TRANSPORT_REQUIRED));
+    if (options.isUsingDomainSocket() && !vertx.transport().supportsDomainSockets()) {
+      return contextInternal.failedFuture(UDS_NOT_SUPPORTED);
     }
     PromiseInternal<SqlConnection> promise = contextInternal.promise();
     connect(asEventLoopContext(contextInternal), options)

vertx-pg-client/src/test/java/io/vertx/tests/pgclient/UnixDomainSocketTest.java

@@ -1,28 +1,22 @@
 /*
- * Copyright (C) 2018 Julien Viet
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
  *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
  */
 package io.vertx.tests.pgclient;
 
-import io.vertx.pgclient.PgBuilder;
-import io.vertx.pgclient.PgConnectOptions;
-import io.vertx.pgclient.SslMode;
 import io.vertx.core.Vertx;
 import io.vertx.core.VertxOptions;
 import io.vertx.ext.unit.TestContext;
 import io.vertx.ext.unit.junit.VertxUnitRunner;
+import io.vertx.pgclient.PgBuilder;
+import io.vertx.pgclient.PgConnectOptions;
+import io.vertx.pgclient.SslMode;
 import io.vertx.sqlclient.Pool;
 import io.vertx.sqlclient.SqlClient;
 import io.vertx.sqlclient.SqlConnectOptions;
@@ -31,8 +25,6 @@
 import org.junit.*;
 import org.junit.runner.RunWith;
 
-import java.io.File;
-
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assume.assumeTrue;
@@ -49,7 +41,10 @@ public class UnixDomainSocketTest {
   @Before
   public void before() {
     Assume.assumeNotNull(rule.domainSocketPath());
-    vertx = Vertx.vertx(new VertxOptions().setPreferNativeTransport(true));
+    // Only use native transport for JDK < 16 (Unix domain socket support added in JDK 16)
+    boolean useNativeTransport = Runtime.version().feature() < 16;
+    vertx = Vertx.vertx(new VertxOptions().setPreferNativeTransport(useNativeTransport));
+    assertEquals(useNativeTransport, vertx.isNativeTransportEnabled());
     options = rule.options().setHost(rule.domainSocketPath()).setPort(5432);
   }
 
@@ -104,9 +99,10 @@ public void testIgnoreSslMode(TestContext context) {
 
   @Test
   public void testNativeTransportMustBeEnabled(TestContext ctx) {
+    assumeTrue("Unix Domain Sockets are supported on Java 16+", Runtime.version().feature() < 16);
     Pool pool = PgBuilder.pool().connectingTo(SqlConnectOptions.fromUri("postgresql:///dbname?host=/var/lib/postgresql")).build();
     pool.getConnection().onComplete(ctx.asyncAssertFailure(err -> {
-      assertEquals(ConnectionFactoryBase.NATIVE_TRANSPORT_REQUIRED, err.getMessage());
+      assertEquals(ConnectionFactoryBase.UDS_NOT_SUPPORTED, err);
     }));
   }
 }

vertx-sql-client/src/main/java/io/vertx/sqlclient/impl/ConnectionFactoryBase.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2020 Contributors to the Eclipse Foundation
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
@@ -12,13 +12,13 @@
 
 import io.vertx.core.Completable;
 import io.vertx.core.Future;
-import io.vertx.core.Promise;
-import io.vertx.core.net.NetClient;
-import io.vertx.core.net.NetClientOptions;
+import io.vertx.core.VertxException;
 import io.vertx.core.internal.CloseSequence;
 import io.vertx.core.internal.ContextInternal;
 import io.vertx.core.internal.PromiseInternal;
 import io.vertx.core.internal.VertxInternal;
+import io.vertx.core.net.NetClient;
+import io.vertx.core.net.NetClientOptions;
 import io.vertx.sqlclient.SqlConnectOptions;
 import io.vertx.sqlclient.internal.Connection;
 import io.vertx.sqlclient.spi.ConnectionFactory;
@@ -28,7 +28,7 @@
  */
 public abstract class ConnectionFactoryBase<C extends SqlConnectOptions> implements ConnectionFactory<C> {
 
-  public static final String NATIVE_TRANSPORT_REQUIRED = "The Vertx instance must use a native transport in order to connect to connect through domain sockets";
+  public static final VertxException UDS_NOT_SUPPORTED = new VertxException("Unix Domain Sockets are not supported, use Java 16+ or enable a native transport", true);
 
   protected final VertxInternal vertx;
   protected final NetClient client;