GizmoSQL JDBC Driver

A JDBC driver for GizmoSQL, based on Arrow Flight SQL.

This project is a fork of Apache Arrow Java.

Installation

Maven

<dependency>
    <groupId>com.gizmodata</groupId>
    <artifactId>gizmosql-jdbc-driver</artifactId>
    <version>1.5.0</version>
</dependency>

Gradle

dependencies {
    implementation 'com.gizmodata:gizmosql-jdbc-driver:1.5.0'
}

Usage

Basic Connection (with TLS)

import java.sql.*;

public class Example {
    public static void main(String[] args) throws SQLException {
        // Recommended: TLS enabled with certificate verification
        String url = "jdbc:gizmosql://your-server.example.com:31337?useEncryption=true";

        try (Connection conn = DriverManager.getConnection(url, "user", "password");
             Statement stmt = conn.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT * FROM my_table")) {

            while (rs.next()) {
                System.out.println(rs.getString(1));
            }
        }
    }
}

Development/Testing (Skip Certificate Verification)

For development environments with self-signed certificates:

// TLS enabled but skip certificate verification (development only!)
String url = "jdbc:gizmosql://localhost:31337?useEncryption=true&disableCertificateVerification=true";

try (Connection conn = DriverManager.getConnection(url, "user", "password")) {
    // ...
}

Connection URL Format

jdbc:gizmosql://[host]:[port]?[param1=value1&param2=value2...]

The driver also accepts jdbc:arrow-flight-sql:// for backward compatibility.

Connection Properties

Property	Description	Default
Authentication
user	Username for user/password authentication	-
password	Password for user/password authentication	-
token	Bearer token for token authentication	-
TLS/Encryption
useEncryption	Whether to use TLS encryption	true
disableCertificateVerification	Skip server certificate verification (dev only)	false
useSystemTrustStore	Use the system certificate store	true
trustStore	Path to Java truststore (JKS) for TLS	-
trustStorePassword	Password for the truststore	-
tlsRootCerts	Path to PEM-encoded root certificates (alternative to trustStore)	-
Mutual TLS (mTLS)
clientCertificate	Path to PEM-encoded client certificate for mTLS	-
clientKey	Path to PEM-encoded client private key for mTLS	-
OAuth / SSO
authType	Set to external to use server-side OAuth (browser-based SSO)	-
Advanced
threadPoolSize	Size of internal thread pool	1
retainCookies	Retain cookies from initial connection	true
retainAuth	Retain bearer tokens from initial connection	true

Note: URI parameter values must be URI-encoded (e.g., password=my%23password for my#password). Properties object values should not be encoded.

Properties can be passed either in the URL or via the Properties object:

Properties props = new Properties();
props.setProperty("user", "myuser");
props.setProperty("password", "mypassword");
props.setProperty("useEncryption", "true");

Connection conn = DriverManager.getConnection("jdbc:gizmosql://localhost:31337", props);

Building from Source

# Clone the repository
git clone https://github.com/gizmodata/gizmosql-jdbc-driver.git
cd gizmosql-jdbc-driver

# Build the JDBC driver
./mvnw -pl flight/flight-sql-jdbc-driver -am -DskipTests package

# The shaded JAR will be at:
# flight/flight-sql-jdbc-driver/target/gizmosql-jdbc-driver-VERSION.jar

Compatibility

• Java 11 or later
• GizmoSQL server with Flight SQL support

License

Apache License 2.0 - see LICENSE.txt

This project is a fork of Apache Arrow Java. See NOTICE.txt for attribution.