Love SQL, hate XML? A fresh choice for Java developers.
LumenORM is a lightweight SQL-First ORM for Java with three query entry points:
- Interface-based SQL - Define SQL in interfaces with
@SqlTemplate, validated at compile-time - Fluent DSL - Type-safe query builder with lambda references
- Text Block Templates - Native SQL with dynamic directives
No external ORM dependencies. Just JDBC.
// Define SQL in your interface - validated at compile-time!
public interface PetRepository extends SqlTemplate {
@SqlTemplate("""
SELECT id, name, price
FROM pets
WHERE available = true
@if(#{species}) {
AND species = #{species}
}
@if(#{minPrice}) {
AND price >= #{minPrice}
}
@if(#{maxPrice}) {
AND price <= #{maxPrice}
}
ORDER BY price DESC
""")
List<Pet> search(PetSearchCriteria criteria);
// Built-in functions like #{now()}, #{uuid()} supported
@SqlTemplate("""
INSERT INTO pets (name, species, price, created_at)
VALUES (#{name}, #{species}, #{price}, #{now()})
""")
void insert(Pet pet);
}
// Usage - just call the method!
List<Pet> pets = petRepository.search(new PetSearchCriteria("cat", 10.0, 100.0));No XML. No string concatenation. Pure SQL in Java with dynamic directives.
@SqlTemplate("""
SELECT * FROM pets WHERE 1=1
@if(#{name}) {
AND name = #{name}
}
@if(#{tags} && #{tags.length} > 0) {
AND id IN (
@for((tag, index) in #{tags}) {
#{tag.id}@{if(index < tags.length - 1)}, @end{}
}
)
}
""")
List<Pet> findByCondition(PetCondition condition);| Directive | Description |
|---|---|
@if(cond) { ... } |
Conditional SQL blocks |
@for((item, index) in list) { ... } |
Loop over collections |
@where { ... } |
Auto WHERE/AND handling |
@in(list) { ... } |
IN clause generation |
@orderBy(field) { ... } |
Safe ORDER BY |
@page(page, size) { ... } |
Pagination |
| Function | Description |
|---|---|
#{now()} |
Current timestamp |
#{uuid()} |
UUID generation |
#{random()} |
Random value |
#{like(value)} |
LIKE pattern |
#{upper(value)} |
UPPER case |
#{lower(value)} |
Lower case |
- Interface-based SQL with
@SqlTemplateand compile-time validation - Dynamic SQL directives (
@if,@for,@where,@in,@page,@orderBy) - Built-in template functions (
#{now()},#{uuid()}, etc.) - Custom template functions via
TemplateFunction - Type-safe Fluent DSL with lambda references
- Entity metadata (Reflection or APT-generated)
- Logical deletion, Active Record, Batch operations
- Spring Boot 3/4 & Solon integration
- Minimal dependencies
mvn clean install -DskipTestsRun examples:
mvn -pl example/todo-example spring-boot:run # http://localhost:8080
mvn -pl example/pet-store spring-boot:run # http://localhost:8081public interface PetRepository extends SqlTemplate {
@SqlTemplate("""
SELECT id, name, price
FROM pets
WHERE species = #{species}
AND available = true
ORDER BY price DESC
""")
List<Pet> findAvailableBySpecies(String species);
}
// Spring injection - just use it!
@Autowired
PetRepository petRepository;
List<Pet> pets = petRepository.findAvailableBySpecies("cat");var t = dsl.table(Pet.class).as("p");
SelectStmt stmt = dsl.select(
Dsl.item(t.col(Pet::getId).expr()),
Dsl.item(t.col(Pet::getName).expr()),
Dsl.item(t.col(Pet::getPrice).expr())
)
.from(t)
.where(w -> w.and(t.col(Pet::getAvailable).eq(true)))
.orderBy(o -> o.desc(t.col(Pet::getPrice).expr()))
.page(1, 10)
.build();
List<Pet> pets = db.fetch(Query.of(stmt, Bindings.empty()), Pet.class);String sql = """
SELECT id, name, price
FROM pets
WHERE available = true
ORDER BY price DESC
""";
List<Pet> pets = db.run(sql, Bindings.empty(), Pet.class);@SqlTemplate("""
SELECT * FROM pets WHERE 1=1
@if(#{name}) {
AND name = #{name}
}
@if(#{species}) {
AND species = #{species}
}
@if(#{minPrice}) {
AND price >= #{minPrice}
}
""")
List<Pet> search(String name, String species, BigDecimal minPrice);@SqlTemplate("""
SELECT * FROM pets WHERE id IN (
@for((id, index) in #{ids}) {
#{id}@{if(index < ids.length - 1)}, @end{}
}
)
""")
List<Pet> findByIds(List<Long> ids);@SqlTemplate("""
SELECT * FROM pets
@orderBy(#{sortBy}) {
ORDER BY #{sortBy} #{sortDir}
}
""")
List<Pet> findAll(String sortBy, String sortDir);- Quick Start - Get started in 5 minutes
- APT Guide - Interface-based SQL with @SqlTemplate
- DSL Guide - Type-safe query building
- Template Guide - SQL text block patterns
- Entity Definition - Annotations reference
- Logical Delete - Soft delete support
- Transactions - Transaction management
- Batch Operations - Bulk inserts/updates
- Active Record - Active Record pattern
- Spring Boot - Spring Boot integration
- Solon - Solon framework integration
- Examples - Example projects
LumenORM/
├── lumen-core/ # Core ORM engine
├── lumen-spring-boot-starter/ # Spring Boot 3 integration
├── lumen-spring-boot-4-starter/ # Spring Boot 4 integration
├── lumen-solon-plugin/ # Solon framework integration
├── docs/ # Documentation
└── example/
├── core-example/ # Core API examples
├── todo-example/ # Todo REST API demo
└── pet-store/ # Pet store demo
Spring Boot 3:
<dependency>
<groupId>pub.lighting</groupId>
<artifactId>lumen-spring-boot-starter</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>Core Only:
<dependency>
<groupId>pub.lighting</groupId>
<artifactId>lumen-core</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>MIT