HeliosDB JDBC Driver

Official Type 4 (pure Java) JDBC driver for HeliosDB v2.0, providing seamless integration with the Java ecosystem.

Features

JDBC 4.2+ Compliance: Full compliance with JDBC 4.2 specification
Pure Java: Type 4 driver with no native dependencies
PostgreSQL Protocol: Leverages PostgreSQL wire protocol for compatibility
Connection Pooling: Built-in HikariCP integration for high performance
Vector Data Support: Native support for vector/embedding data types
Prepared Statement Caching: Automatic caching for improved performance
Batch Operations: Efficient batch insert/update operations
Transaction Management: Full ACID transaction support with savepoints
Comprehensive Metadata: Complete database and result set metadata
Thread-Safe: Designed for multi-threaded applications

Installation

Maven

<dependency>
    <groupId>com.heliosdb</groupId>
    <artifactId>heliosdb-jdbc</artifactId>
    <version>2.0.0</version>
</dependency>

Gradle

implementation 'com.heliosdb:heliosdb-jdbc:2.0.0'

Quick Start

Basic Connection

import java.sql.*;

public class Example {
    public static void main(String[] args) throws SQLException {
        // Connection URL format: jdbc:heliosdb://host:port/database
        String url = "jdbc:heliosdb://localhost:5432/mydb";
        String user = "username";
        String password = "password";

        try (Connection conn = DriverManager.getConnection(url, user, password)) {
            // Your database operations here
            System.out.println("Connected to HeliosDB!");
        }
    }
}

Simple Query

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

    while (rs.next()) {
        int id = rs.getInt("id");
        String name = rs.getString("name");
        System.out.printf("User %d: %s%n", id, name);
    }
}

Prepared Statements

String sql = "INSERT INTO users (name, email, age) VALUES (?, ?, ?)";

try (Connection conn = DriverManager.getConnection(url, user, password);
     PreparedStatement pstmt = conn.prepareStatement(sql)) {

    pstmt.setString(1, "Alice");
    pstmt.setString(2, "alice@example.com");
    pstmt.setInt(3, 30);

    int rows = pstmt.executeUpdate();
    System.out.println("Inserted " + rows + " row(s)");
}

Connection Pooling with HikariCP

import com.heliosdb.jdbc.HeliosDataSource;

// Create a connection pool
HeliosDataSource dataSource = new HeliosDataSource(
    "jdbc:heliosdb://localhost:5432/mydb",
    "username",
    "password"
);

// Get connections from the pool
try (Connection conn = dataSource.getConnection()) {
    // Use the connection
}

// Close the pool when done
dataSource.close();

Advanced Pool Configuration

HeliosDataSource dataSource = HeliosDataSource.builder()
    .jdbcUrl("jdbc:heliosdb://localhost:5432/mydb")
    .username("user")
    .password("pass")
    .maximumPoolSize(20)
    .minimumIdle(5)
    .connectionTimeout(30000)
    .enablePreparedStatementCache()
    .enableBatchRewrite()
    .build();

Vector Data Support

HeliosDB has native support for vector/embedding data types, commonly used in AI/ML applications.

Storing Vectors

// Create vector as float array
float[] embedding = {1.0f, 2.5f, 3.7f, ...};

// Convert to bytes for storage
byte[] vectorBytes = convertToBytes(embedding);

// Insert with prepared statement
String sql = "INSERT INTO documents (title, embedding) VALUES (?, ?)";
try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
    pstmt.setString(1, "Document Title");
    pstmt.setBytes(2, vectorBytes);
    pstmt.executeUpdate();
}

Retrieving Vectors

import com.heliosdb.jdbc.HeliosResultSet;

String sql = "SELECT title, embedding FROM documents WHERE id = ?";
try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
    pstmt.setInt(1, documentId);

    try (ResultSet rs = pstmt.executeQuery()) {
        if (rs.next()) {
            String title = rs.getString("title");
            byte[] embeddingBytes = rs.getBytes("embedding");

            // Convert back to float array
            float[] embedding = HeliosResultSet.bytesToFloatArray(embeddingBytes);
            System.out.println("Retrieved " + embedding.length + " dimensions");
        }
    }
}

Vector Similarity Search

// Perform KNN search using L2 distance
String sql = """
    SELECT id, title, l2_distance(embedding, ?) as distance
    FROM documents
    ORDER BY distance
    LIMIT 10
    """;

try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
    pstmt.setBytes(1, queryVectorBytes);

    try (ResultSet rs = pstmt.executeQuery()) {
        while (rs.next()) {
            int id = rs.getInt("id");
            String title = rs.getString("title");
            double distance = rs.getDouble("distance");
            System.out.printf("%d: %s (distance: %.4f)%n", id, title, distance);
        }
    }
}

Connection URL Format

jdbc:heliosdb://host:port/database?property1=value1&property2=value2

Supported Properties

Property	Description	Default
`user`	Database username	(required)
`password`	Database password	(required)
`ssl`	Enable SSL encryption	`false`
`sslmode`	SSL mode (disable, allow, prefer, require, verify-ca, verify-full)	`prefer`
`connectTimeout`	Connection timeout in seconds	`10`
`socketTimeout`	Socket read timeout in seconds (0 = infinite)	`0`
`loginTimeout`	Login timeout in seconds	`10`
`prepareThreshold`	Executions before server-side prepare	`5`
`preparedStatementCacheQueries`	Maximum cached prepared statements	`256`
`preparedStatementCacheSizeMiB`	Cache size in MiB	`5`
`defaultRowFetchSize`	Default fetch size for result sets	`0`
`applicationName`	Application name for monitoring	`HeliosDB JDBC Driver`

Example URLs

// Basic connection
"jdbc:heliosdb://localhost:5432/mydb"

// With SSL
"jdbc:heliosdb://db.example.com:5432/mydb?ssl=true&sslmode=require"

// With timeout settings
"jdbc:heliosdb://localhost:5432/mydb?connectTimeout=30&socketTimeout=60"

// Full configuration
"jdbc:heliosdb://host:5432/db?user=admin&password=secret&ssl=true&prepareThreshold=3"

Transaction Management

Auto-Commit Mode

try (Connection conn = DriverManager.getConnection(url, user, password)) {
    // Auto-commit is enabled by default
    Statement stmt = conn.createStatement();
    stmt.executeUpdate("INSERT INTO users (name) VALUES ('Alice')");
    // Automatically committed
}

Manual Transaction Control

try (Connection conn = DriverManager.getConnection(url, user, password)) {
    conn.setAutoCommit(false);

    try {
        Statement stmt = conn.createStatement();
        stmt.executeUpdate("INSERT INTO users (name) VALUES ('Alice')");
        stmt.executeUpdate("INSERT INTO orders (user_id, amount) VALUES (1, 100)");

        conn.commit(); // Commit both operations

    } catch (SQLException e) {
        conn.rollback(); // Rollback on error
        throw e;
    }
}

Savepoints

conn.setAutoCommit(false);

Savepoint savepoint1 = conn.setSavepoint("sp1");
// ... some operations ...

Savepoint savepoint2 = conn.setSavepoint("sp2");
// ... more operations ...

if (error) {
    conn.rollback(savepoint2); // Rollback to savepoint2
} else {
    conn.commit();
}

Isolation Levels

// Set transaction isolation level
conn.setTransactionIsolation(Connection.TRANSACTION_SERIALIZABLE);

// Available levels:
// - TRANSACTION_READ_UNCOMMITTED
// - TRANSACTION_READ_COMMITTED (default)
// - TRANSACTION_REPEATABLE_READ
// - TRANSACTION_SERIALIZABLE

Batch Operations

String sql = "INSERT INTO users (name, email) VALUES (?, ?)";

try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
    // Add multiple batches
    for (User user : users) {
        pstmt.setString(1, user.getName());
        pstmt.setString(2, user.getEmail());
        pstmt.addBatch();
    }

    // Execute all at once
    int[] results = pstmt.executeBatch();
    System.out.println("Inserted " + results.length + " rows");
}

Database Metadata

DatabaseMetaData metaData = conn.getMetaData();

// Database information
System.out.println("Database: " + metaData.getDatabaseProductName());
System.out.println("Version: " + metaData.getDatabaseProductVersion());
System.out.println("Driver: " + metaData.getDriverName());

// List tables
ResultSet tables = metaData.getTables(null, "public", "%", new String[]{"TABLE"});
while (tables.next()) {
    System.out.println("Table: " + tables.getString("TABLE_NAME"));
}

// Get columns for a table
ResultSet columns = metaData.getColumns(null, "public", "users", "%");
while (columns.next()) {
    String columnName = columns.getString("COLUMN_NAME");
    String dataType = columns.getString("TYPE_NAME");
    System.out.println(columnName + " (" + dataType + ")");
}

Performance Tips

1. Use Connection Pooling

// Instead of creating new connections each time
HeliosDataSource dataSource = new HeliosDataSource(url, user, password);

2. Enable Prepared Statement Caching

HeliosDataSource dataSource = HeliosDataSource.builder()
    .jdbcUrl(url)
    .username(user)
    .password(password)
    .enablePreparedStatementCache()
    .build();

3. Use Batch Operations

// Batch multiple operations together
pstmt.addBatch();
int[] results = pstmt.executeBatch();

4. Set Appropriate Fetch Size

// For large result sets
Statement stmt = conn.createStatement();
stmt.setFetchSize(100);
ResultSet rs = stmt.executeQuery("SELECT * FROM large_table");

5. Reuse Prepared Statements

// Reuse within a loop
PreparedStatement pstmt = conn.prepareStatement(sql);
for (Data data : dataList) {
    pstmt.setString(1, data.getValue());
    pstmt.executeUpdate();
}
pstmt.close();

Error Handling

try {
    // Database operations
} catch (SQLException e) {
    System.err.println("SQL State: " + e.getSQLState());
    System.err.println("Error Code: " + e.getErrorCode());
    System.err.println("Message: " + e.getMessage());

    // Check for specific error conditions
    if (e.getSQLState().startsWith("23")) {
        System.err.println("Integrity constraint violation");
    }
}

Thread Safety

The HeliosDB JDBC driver is designed to be thread-safe:

Connection: Not thread-safe. Each thread should have its own connection or use a connection pool.
Statement: Not thread-safe. Create separate statements per thread.
ResultSet: Not thread-safe. Should not be shared between threads.
Connection Pool: Thread-safe. Multiple threads can safely request connections.

Examples

See the examples/ directory for complete working examples:

BasicUsageExample.java - Basic CRUD operations, transactions, and batch operations
VectorSearchExample.java - Vector storage and similarity search
ConnectionPoolExample.java - HikariCP connection pooling with concurrent access

Building from Source

# Clone the repository
git clone https://github.com/heliosdb/heliosdb.git
cd heliosdb/java-client

# Build with Maven
mvn clean install

# Run tests
mvn test

# Build without tests
mvn clean install -DskipTests

Requirements

Java 11 or higher
HeliosDB 2.0 or higher

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

Documentation: https://docs.heliosdb.com
Issues: https://github.com/heliosdb/heliosdb/issues
Discord: https://discord.gg/heliosdb
Email: support@heliosdb.com

Changelog

Version 2.0.0 (2024)

Initial release
JDBC 4.2+ compliance
PostgreSQL protocol support
HikariCP connection pooling
Vector data type support
Comprehensive metadata implementation
Transaction management with savepoints
Batch operations
Prepared statement caching

Acknowledgments

Built on top of the PostgreSQL JDBC driver for protocol compatibility
Uses HikariCP for high-performance connection pooling