libsql-java

A pure-Java JDBC driver, client library, and protocol codec for libSQL and sqld databases over the Hrana protocol.

---

Features

• Standard JDBC Driver: Drop-in java.sql compliance (jdbc:libsql:...) for applications, connection pools (HikariCP), and ORMs.
• Pure Java: No JNI, C-bindings, or native dependencies required.
• Hrana 3 Protocol Support: High-performance binary and JSON protocol codecs for libSQL/sqld.
• Lightweight & Fast: Built for modern Java (LTS).
• Batteries Included: Multi-module architecture providing fine-grained dependencies.

Modules

Module	Description
libsql-jdbc	Standard JDBC 4.3 driver (jdbc:libsql:...)
libsql-client	High-level client API for libSQL queries and streaming
libsql-hrana-codec	Core codec implementation for the Hrana 3 protocol
libsql-itests	Integration tests against sqld running in Testcontainers

Getting Started

Maven Dependency

<dependency>
    <groupId>com.github.magnusp.libsql</groupId>
    <artifactId>libsql-jdbc</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

JDBC Usage Example

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

public class Example {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:libsql:http://localhost:8080";

        try (Connection conn = DriverManager.getConnection(url);
             PreparedStatement stmt = conn.prepareStatement("SELECT 1 AS col")) {

            try (ResultSet rs = stmt.executeQuery()) {
                if (rs.next()) {
                    System.out.println("Result: " + rs.getInt("col"));
                }
            }
        }
    }
}

Development & Building

Prerequisites

• Java: Java LTS
• Tooling: Managed via mise and Maven Wrapper (./mvnw)
• Docker: For running integration tests against sqld

Commands

# Compile and run unit tests
mise exec -- ./mvnw clean test

# Run full integration test suite (requires Docker)
mise exec -- ./mvnw clean verify

# Format code with Spotless (Google Java Format)
mise exec -- ./mvnw spotless:apply

Contributing

We welcome contributions! Please see CONTRIBUTING.md for contribution guidelines and development workflow, and CODE_OF_CONDUCT.md for community standards.

Security

Please report security issues according to our Security Policy.

License

This project is licensed under the MIT License.