BlinkHouse - a ClickHouse-native persistence library for Java, v1.0.0

[u/Monopole007]

Just shipped BlinkHouse v1.0.0 — a ClickHouse-native persistence library for Java that eliminates the boilerplate of working with ClickHouse while giving you the same annotate-and-go experience you know from Hibernate and Spring Data.

Annotate a record, get a fully mapped entity with schema generation, typed queries, and buffered ingest — no manual SQL, no hand-rolled HTTP clients, no serialisation code.

@ChTable(name = "page_views", orderBy = {"tenant_id", "ts"})
@ChEngine(value = Engine.REPLACING_MERGE_TREE, versionColumn = "ingested_at")
public record PageView(
    @ChColumn(type = "UInt32")                 int     tenantId,
    @ChColumn(type = "DateTime64(3,'UTC')")    Instant ts,
    @ChColumn(type = "LowCardinality(String)") String  country,
                                               String  url
) {}

That's your entity. BlinkHouse generates the DDL, maps the types, and handles the wire format.

No boilerplate ingest:

try (BatchWriter<PageView> writer = template.batchWriter(PageView.class, cfg)) {
    events.forEach(writer::add);
}

BatchWriter<T> handles buffering, flush triggers (row count / byte size / elapsed time), backpressure, retry with exponential backoff, and dead-letter callbacks. You add rows — it handles the rest.

No boilerplate queries:

// Spring Data repository — derived methods, @Query, keyset pagination
public interface PageViewRepository extends ClickHouseRepository<PageView, UUID> {
    Slice<PageView> findByTenantIdAndTsBetween(int tenantId, Instant from, Instant to, Cursor c);
}

// Or the typed DSL
List<PageView> views = ChQuery.select("*")
    .from(TableRef.of("page_views"))
    .where(col("tenant_id").eq(tenantId))
    .fetch(template, PageView.class);

No boilerplate Spring config:

Add one dependency, set three YAML properties, get a fully wired ChTemplate, schema manager, type registry, Micrometer metrics, and OTel tracing. Zero @Bean methods required.

Where it differs from Hibernate:

ClickHouse has no transactions, no row identity, and no foreign keys — and BlinkHouse doesn't emulate them. What you get instead is a library that fits ClickHouse's actual model: columnar storage, high-throughput ingest, and analytics-first queries. There's a "Coming from JPA" guide in the repo.

Stats: Java 17 + 21, Spring Boot 3.2–3.4, ClickHouse 24.3+, 132 unit tests, 29 integration tests, Apache HttpClient 5 connection pooling, GraalVM native-image hints.

<dependency>
    <groupId>io.github.muneeb-i-khan</groupId>
    <artifactId>blinkhouse-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Repo: https://github.com/muneeb-i-khan/BlinkHouse

[u/Additional-Road3924]

Why are you targeting a spring boot version that's been out of support for a year now

[u/Monopole007 → u/Additional-Road3924]

Thanks for your feedback. I am currently using springboot 3.5.16 and will soon upgrade to 4.x. This is just the initial release and I am planning on improving and maintaining this project going forward.

[u/Decent-Decision-9028]

Another one bites the dust

[u/paul_h]

For the uninitiated: ClickHouse is a fast, open-source, column-oriented database management system designed for real-time online analytical processing (OLAP).

[u/AnyPhotograph7804]

*hums the XKCD 927 melody*

I see no real differences or benefits to JPA. And i see a potential drawback: the dependence on string constants like table names etc. in domain code.

[u/noodlesSa]

No manual SQL is actually deal breaker for me. I am perfectly happy with JDBC, and also I think trading SQL engine specific features and idioms for DB-universal least common denominator is really bad trade for 99% of applications.