Get Started

This guide covers the basic steps to integrate Litebridge into a Java project, from setting up dependencies to performing your first database operations.

1. Requirements

  • Java 21+: Leveraging modern features like records and pattern matching.
  • Maven: For dependency management and build automation.

2. Add Litebridge

Add the core ORM dependency to your pom.xml:

Imports
pom.xml
<dependency>
    <groupId>org.litebridgedb</groupId>
    <artifactId>litebridge-orm</artifactId>
    <version>0.5.0</version>
</dependency>

3. Choose a Provider

Include the artifact for your target database. Litebridge supports the following providers:

Imports
pom.xml
<dependency>
    <groupId>org.litebridgedb</groupId>
    <artifactId>litebridge-db-h2</artifactId>
    <version>0.5.0</version>
</dependency>

4. Define an Entity

Map your Java classes to database tables using Litebridge annotations:

Person.java
import org.litebridge.orm.annotation.Column;
import org.litebridge.orm.annotation.Table;
import org.litebridge.orm.annotation.OneToMany;
@Table("LB.PERSON")
public class Person {

    @Column(value = "ID", generateUsingSequence = "PERSON_SEQ")
    private Long id;

    @Column("NAME")
    private String name;

    @Column("SURNAME")
    private String surname;
    
    @OneToMany(mappedByField = "owner")
    private List<Account> accounts;

    // Getters and setters
}

Note: The Litebridge Maven plugin can automatically generate these entities from your database schema.

Plain, unaltered DTOs can also be used; see the "Mapping tables to entities" guide for more details.

5. Initialise

Create a Litebridge instance and register your entities:

GetStarted.java
import javax.sql.DataSource;

import org.litebridge.orm.Litebridge;
import org.litebridge.db.h2.H2DatabaseProvider;

import org.example.entity.Person;
// Create a Litebridge instance
Litebridge litebridge = Litebridge
    .withDatabase(new H2DatabaseProvider(), dataSource)
    .build();

// Register your entities
litebridge.register(Person.class);

6. Persistence & Queries

You are now ready to save and retrieve data using Litebridge's fluent API:

GetStarted.java
import java.util.Optional;

import org.litebridge.orm.Litebridge;

import org.example.entity.Person;
// Save an entity
litebridge.save(person);

// Query data
Optional<Person> alice = litebridge.select(Person.class)
    .where("name").eq("Alice")
    .first();

Next Steps

Explore the full functionality of Litebridge: