A type-safe SQL builder for Java with multi-dialect support through a plugin system. Build SQL statements programmatically using a fluent DSL with compile-time validation.

Features

• ✅ Type-safe SQL building with compile-time validation
• ✅ Multi-dialect support (MySQL, PostgreSQL, Standard SQL)
• ✅ Plugin architecture for custom dialects
• ✅ Fluent DSL API
• ✅ PreparedStatement support with automatic parameter binding and SQL injection prevention
• ✅ Complex queries: JOINs, subqueries, window functions, aggregates
• ✅ DDL operations: CREATE TABLE, ALTER, DROP
• ✅ DML operations: SELECT, INSERT, UPDATE, DELETE, MERGE, TRUNCATE

Quick Start

Basic SELECT Query

import io.github.auspis.fluentsql4j.dsl.DSL;
import io.github.auspis.fluentsql4j.dsl.DSLRegistry;

// Get a DSL instance for your database
DSLRegistry registry = DSLRegistry.createWithServiceLoader();
DSL dsl = registry.dslFor("mysql", "8.0.35").orElseThrow();

// Build and execute a query
PreparedStatement ps = dsl.select("name", "email")
    .from("users")
    .where()
    .column("age").gt(18)
    .build(connection);

INSERT Statement

PreparedStatement ps = dsl.insertInto("users")
    .set("name", "John Doe")
    .set("email", "john@example.com")
    .set("age", 25)
    .build(connection);

Multi-Table Query with JOIN

// Query with explicit cross-table column references
PreparedStatement ps = dsl.select("*")
    .from("users").as("u")
    .innerJoin("orders").as("o")
    .on("u", "id", "o", "user_id")
    .where()
    .column("u", "age").gt(18)           // Column from users table
    .and()
    .column("o", "status").eq("COMPLETED")  // Column from orders table
    .build(connection);

Note: All builders use .build(connection) which automatically handles parameter binding, preventing SQL injection attacks. The Connection object must be managed by the caller (not closed automatically by the builder).

For more examples, see the DSL Usage Guide.

Project Structure

The project is organized as a multi-module Maven project with two main artifacts for users:

Published Artifacts

• api/: Public API for DSL users

  • Use this dependency in your application to build SQL queries

  • Provides DSL, builders (SELECT, INSERT, UPDATE, DELETE, MERGE, TRUNCATE, CREATE TABLE), and PreparedStatement support

  • Maven dependency:

    <dependency>
      <groupId>io.github.auspis.fluentsql4j</groupId>
      <artifactId>api</artifactId>
      <version>1.3.4</version>
    </dependency>

• spi/: Service Provider Interface for plugin developers

  • Use this dependency to develop custom SQL dialect plugins

  • Provides AST interfaces, Visitor pattern, rendering strategies, and plugin registry

  • Maven dependency:

    <dependency>
      <groupId>io.github.auspis.fluentsql4j</groupId>
      <artifactId>spi</artifactId>
      <version>1.3.4</version>
    </dependency>

Internal Modules

• core/: Internal implementation (AST, DSL builders, plugin system)
  • Not intended for direct use - access via api or spi
  • Contains all implementation code
• plugins/: Dialect-specific plugins
  • plugins/plugin-mysql/: MySQL dialect plugin
  • plugins/plugin-postgresql/: PostgreSQL dialect plugin
• test-support/: Shared test utilities and helpers
• test-real-deps/: Test-only module for tests that require concrete runtime dependencies we do not want in the production module graph or published artifacts

Use test-real-deps only for tests whose realism requires concrete runtime dependencies intentionally excluded from production modules.

Usage Patterns

For Application Developers (using the DSL):

<dependency>
  <groupId>io.github.auspis.fluentsql4j</groupId>
  <artifactId>api</artifactId>
  <version>1.3.4</version>
</dependency>
<!-- Add dialect plugins as needed -->
<dependency>
  <groupId>io.github.auspis.fluentsql4j</groupId>
  <artifactId>plugin-mysql</artifactId>
  <version>1.3.4</version>
</dependency>

For Plugin Developers (creating custom dialects):

<dependency>
  <groupId>io.github.auspis.fluentsql4j</groupId>
  <artifactId>spi</artifactId>
  <version>1.3.4</version>
</dependency>

Building the Project

To build all modules locally:

./mvnw clean install

To build without running tests:

./mvnw clean install -DskipTests

To run only unit and component tests (fast):

./mvnw clean test

To run all tests including integration and E2E tests:

./mvnw clean verify

Documentation

• DSL Usage Guide: Comprehensive examples for all DSL operations (SELECT, INSERT, UPDATE, DELETE, MERGE, TRUNCATE, CREATE TABLE)
• Developer Guide: Testing strategies, code coverage, formatting guidelines
• Plugin Development Guide: How to create custom dialect plugins
• Build Hook Guide: How to enable build logging (property-based or programmatic), compose hook factories, and create custom BuildHook providers