Common dependency

Add the following dependency to your Maven project

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-core</artifactId>
  <version>2.9.1</version>
  <type>pom</type>
</dependency>

IMPORTANT: Make sure to include the <type>pom</type> line (this has changed in junixsocket 2.4.0).

Some applications may have problems with this POM dependency. You can also manually specify the following two dependencies instead:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-common</artifactId>
  <version>2.9.1</version>
</dependency>

and

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-native-common</artifactId>
  <version>2.9.1</version>
</dependency>

Optional dependencies

If you're going to use AFUNIXSocketServer code, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-server</artifactId>
  <version>2.9.1</version>
</dependency>

If you're going to use RMI over Unix sockets, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-rmi</artifactId>
  <version>2.9.1</version>
</dependency>

If you're going to use the mySQL Connector for Unix sockets, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-mysql</artifactId>
  <version>2.9.1</version>
</dependency>

If you're going to use TIPC, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-tipc</artifactId>
  <version>2.9.1</version>
</dependency>

If you're going to use VSOCK, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-vsock</artifactId>
  <version>2.9.1</version>
</dependency>

If you're going to use the Jetty connectors, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-jetty</artifactId>
  <version>2.9.1</version>
</dependency>

If you're going to use the SSL extension, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-ssl</artifactId>
  <version>2.9.1</version>
</dependency>

(On Android, you may also want to add org.bouncycastle:bcprov-jdk18on and org.bouncycastle:bctls-jdk18on, since the default SSL implementation is incomplete)

If you're going to use Darwin-specific sockets, add the following dependency:

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-darwin</artifactId>
  <version>2.9.1</version>
</dependency>

Custom architectures (usually not required)

See here how to add support for custom architectures that aren't supported out of the box.

Snapshot versions

If you're testing a -SNAPSHOT version, make sure that the Sonatype snapshot repository is enabled in your POM:

<repositories>
    <repository>
        <id>sonatype.snapshots</id>
        <name>Sonatype snapshot repository</name>
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
        <layout>default</layout>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Snapshot versions

Add the following “maven” line to settings.gradle, or update accordingly:

dependencyResolutionManagement {
    repositories {
        mavenLocal()
        mavenCentral()
        repositories {
            maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
        }
    }
}

MySQL

If you can't use Maven (instructions above), make sure that the following jars are on your classpath:

• junixsocket-common-2.9.1.jar
• junixsocket-mysql-2.9.1.jar
• mysql-connector-j-8.0.31.jar (or newer)
• (typically required; can be skipped if you use the custom library below) junixsocket-native-common-2.9.1.jar
• (optionally, if you have a custom architecture) junixsocket-native-custom-2.9.1.jar

Use the following connection properties (along with user, password, and other properties you may have).

(1) This SocketFactory currently implements the “old” Connector/J SocketFactory interface. This may change in the future. For the time being, you can use a value of org.newsclub.net.mysql.AFUNIXDatabaseSocketFactoryCJ to forcibly use the new “CJ”-style SocketFactory.

(2) This is the full path to the MySQL socket. The location on your system may be different. Try /var/lib/mysql.sock if you can't find it in /tmp.

(3) This is optional, and forcibly disables the use of SSL. Since the connection is local, there's no point in encrypting the communication. Disabling SSL may improve performance.

(4) sslMode is only available with mysql-connector-java 8.0.13 or newer. Try useSSL with a value of false to disable SSL with older versions of Connector/J.

PostgreSQL

Make sure that the following jars are on your classpath:

• junixsocket-common-2.9.1.jar
• postgresql-42.2.5.jar (or newer; earlier versions should work, too)
• (typically, omit if you use the custom library below) junixsocket-native-common-2.9.1.jar
• (optionally, if you have a custom architecture) junixsocket-native-custom-2.9.1.jar

Use the following connection properties (along with user, password, and other properties you may have).

There are currently three distinct ways (socket factories) how to configure the connection to your database:

NOTE When specifying these class names from the command line, you may need to put them in single quotes (or escape the $ sign), otherwise your shell may erroneously interpret $FactoryArg etc. as a variable and fail with java.lang.ClassNotFoundException: org.newsclub.net.unix.AFUNIXSocketFactory

1. org.newsclub.net.unix.AFUNIXSocketFactory$FactoryArg

   You provide the socket path via the socketFactoryArg JDBC property.

   NOTE This is the recommended way for graphical database applications.

   The connection hostname must be set to “localhost”, any other value will not work.

   Connection URL: jdbc:postgresql://localhost/postgres

   property name	value	remarks
   socketFactory	org.newsclub.net.unix.AFUNIXSocketFactory$FactoryArg
   socketFactoryArg	/tmp/.s.PGSQL.5432	(1)
   sslmode	disable	(2)

2. org.newsclub.net.unix.AFUNIXSocketFactory$SystemProperty

   You provide the socket path via the system property org.newsclub.net.unix.socket.default

   The connection hostname must be set to “localhost”, any other value will not work.

   Connection URL: jdbc:postgresql://localhost/postgres

   property name	value	remarks
   socketFactory	org.newsclub.net.unix.AFUNIXSocketFactory$SystemProperty
   sslMode	disable	(2)

3. org.newsclub.net.unix.AFUNIXSocketFactory$URIScheme

   You provide the socket path via the connection URL's hostname.

   The connection “hostname” can be specified as a file: URL (e.g., file:///tmp/.s.PGSQL.5432).

   Since file URLs aren't valid hostnames and contain forward slashes, we have to encode them somehow to pacify PostgreSQL's connection parser. This can be achieved using URL encoding: If the plain URL is file:///tmp/.s.PGSQL.5432, then the URL-encoded version is file%3A%2F%2F%2Ftmp%2F.s.PGSQL.5432.

   Performance trick: By placing a square bracket ([) in front of the host name, we can prevent any attempt to lookup the hostname in DNS. However, this is not mandatory.

   Connection URL: jdbc:postgresql://[file%3A%2F%2F%2Ftmp%2F.s.PGSQL.5432/postgres

   property name	value	remarks
   socketFactory	org.newsclub.net.unix.AFUNIXSocketFactory$URIScheme
   sslMode	disable	(2)

DBeaver

DBeaver is an Open-Source universal database tool. To use junixsocket with DBeaver, for example to connect to PostgreSQL or MySQL databases, add junixsocket to the corresponding driver settings.

DBeaver has problems with the POM-only junixsocket-core artifact, so we have to specify both junixsocket-common and junixsocket-native-common:

Select “Connect by URL” (not Host), then specify a JDBC URL from the variants above. Click “Driver properties” and adjust the driver properties as instructed above.

In the “Connect to a database” dialog, click “Edit Driver Settings”. Under the “Libraries” tab, then add both junixsocket-common and junixsocket-native-common dependencies via “Add Artifact” each; make sure to copy the full <dependency>...</dependency> XML fragment from the Common dependency section above. Afterwards, click “Download/Update” to ensure the drivers are accessible.