Helios ORM 🌟

A modern, lightweight multi-database ORM for Java

Helios is a powerful Object-Relational Mapper supporting PostgreSQL, MariaDB, and MongoDB with a unified API. Connect to multiple databases simultaneously and route entities automatically based on annotations.

---

Features ✨

• 🎯 Multi-Database Support: PostgreSQL, MariaDB, and MongoDB
• 🔄 Unified API: Single interface for all database types
• 🚀 Simple Configuration: Connect to multiple databases with one fluent API
• 📍 Smart Routing: Entities automatically routed to the correct database
• 🔌 Easy Integration: Annotation-based entity mapping
• 🧑‍🤝‍🧑 Relations Support: OneToMany, ManyToOne, ManyToMany, OneToOne
• ⚡ High Performance: HikariCP connection pooling for SQL databases
• 🏗️ Repository Pattern: Optional repository abstraction

---

Quick Start 🛠️

Installation

Option 1: All-in-One (Recommended)

dependencies {
    implementation 'fr.nassime.helios:helios-all:2.0.0'
}

<dependency>
    <groupId>fr.nassime.helios</groupId>
    <artifactId>helios-all</artifactId>
    <version>2.0.0</version>
</dependency>

Option 2: Modular (Pick what you need)

dependencies {
    implementation 'fr.nassime.helios:helios-api:2.0.0'       // Required
    implementation 'fr.nassime.helios:helios-postgres:2.0.0'  // Optional
    implementation 'fr.nassime.helios:helios-mariadb:2.0.0'   // Optional
    implementation 'fr.nassime.helios:helios-mongo:2.0.0'     // Optional
}

See Installation Guide for detailed instructions and GitHub Packages setup.

---

Usage 📖

Single Database Configuration

// Simple PostgreSQL setup
Helios helios = Helios.configure()
    .postgres("main", "localhost:5432/mydb", "user", "password")
    .build();

try (HeliosSession session = helios.openSession()) {
    User user = new User("john", "john@example.com");
    user = session.save(user);

    Optional<User> found = session.findById(User.class, user.getId());
}

Multi-Database Configuration

Connect to PostgreSQL, MongoDB, and MariaDB simultaneously:

Helios helios = Helios.configure()
    .postgres("main", "localhost:5432/mydb", "user", "password")
    .mongo("analytics", "mongodb://localhost:27017/analytics")
    .mariadb("legacy", "localhost:3306/olddb", "user", "password")
    .defaultDatabase("main")
    .build();

try (HeliosSession session = helios.openSession()) {
    // Automatically routed to correct databases
    session.save(user);      // → PostgreSQL
    session.save(event);     // → MongoDB
    session.save(product);   // → MariaDB
}

---

Entity Definitions 🏗️

SQL Entity (PostgreSQL/MariaDB)

@Persistable(name = "users", type = PersistenceType.SQL, database = "main")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "username")
    private String username;

    @Column(name = "email")
    private String email;

    @OneToMany(mappedBy = "user")
    private List<Order> orders;

    // Getters and setters...
}

MongoDB Entity

@Persistable(name = "events", type = PersistenceType.DOCUMENT, database = "analytics")
public class AnalyticsEvent {

    @Id
    private String id;

    @Field(name = "event_type")
    private String eventType;

    @Field(name = "user_id")
    private Long userId;

    @Field(name = "metadata")
    private Map<String, Object> metadata;

    @Field(name = "timestamp")
    private LocalDateTime timestamp;

    // Getters and setters...
}

Relationships

@Persistable(name = "orders", type = PersistenceType.SQL)
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne
    @JoinColumn(name = "user_id")
    private User user;

    @ManyToMany
    @JoinTable(
        name = "order_products",
        joinColumn = "order_id",
        inverseJoinColumn = "product_id"
    )
    private List<Product> products;
}

---

CRUD Operations 🗂️

Save

User user = new User("jane", "jane@example.com");
user = session.save(user);

Find by ID

Optional<User> found = session.findById(User.class, 1L);
found.ifPresent(u -> System.out.println(u.getUsername()));

Find All

List<User> users = session.findAll(User.class);

Query API

List<User> activeUsers = session.createQuery(User.class)
    .where("active", QueryOperator.EQUALS, true)
    .where("age", QueryOperator.GREATER_THAN, 18)
    .orderBy("username", SortDirection.ASC)
    .limit(10)
    .execute();

Delete

session.delete(user);

Load Relations

User user = session.findById(User.class, 1L).orElseThrow();
session.loadRelation(user, "orders");  // Lazy load orders

---

Transactions 💼

session.executeInTransaction(s -> {
    User user = new User("bob", "bob@example.com");
    user = s.save(user);

    Order order = new Order(user.getId(), 100.0);
    s.save(order);

    // Auto-commit on success, rollback on exception
});

---

Advanced Features 🚀

Database-Specific Sessions

// Open session for specific database
try (HeliosSession pgSession = helios.openSession("main")) {
    pgSession.executeInTransaction(s -> {
        // All operations use PostgreSQL
    });
}

Repository Pattern

public interface UserRepository extends Repository<User, Long> {
    List<User> findByEmail(String email);
}

// Implementation auto-generated by Helios
UserRepository repo = RepositoryFactory.create(UserRepository.class, session);
List<User> users = repo.findByEmail("john@example.com");

Native Queries

List<User> users = session.executeNativeQuery(
    "SELECT * FROM users WHERE age > ?",
    User.class,
    18
);

---

Configuration Options ⚙️

Simple Configuration

// Basic connection with defaults
Helios.configure()
    .postgres("main", "localhost:5432/mydb", "user", "pass")
    .build();

// Custom pool size
Helios.configure()
    .postgres("main", "localhost:5432/mydb", "user", "pass", 20)
    .build();

Advanced Configuration

Helios helios = Helios.configure()
    .database("main")
        .postgres("localhost:5432/mydb", "user", "pass")
        .poolSize(50, 10)              // Max: 50, Min idle: 10
        .timeout(30000, 600000, 1800000) // Connection, Idle, Max lifetime (ms)
        .ssl(true)                      // Enable SSL/TLS
        .leakDetection(true)            // Detect connection leaks
        .schema("public")               // Set schema
        .property("cachePrepStmts", true) // Custom property
    .and()
    .build();

Connection Pooling Options

Option	Description	Default
poolSize(max)	Maximum connections	10
poolSize(max, min)	Max and min idle connections	10, 2
connectionTimeout(ms)	Wait time for connection	30000 (30s)
timeout(conn, idle, max)	All timeout values	30s, 10m, 30m

Performance & Monitoring

.database("production")
    .postgres("prod-db:5432/app", "user", "pass")
    .poolSize(100, 20)                    // Large pool for high traffic
    .leakDetectionThreshold(120000)       // Alert after 2 minutes
    .property("preparedStatementCacheSize", 250)
    .property("applicationName", "MyApp")
.and()

SSL/TLS Configuration

.database("secure")
    .postgres("secure.example.com:5432/db", "user", "pass")
    .ssl(true)
    .property("sslmode", "require")
    .property("sslcert", "/path/to/cert.pem")
.and()

URL Formats

PostgreSQL:

• Simple: "localhost:5432/mydb"
• JDBC: "jdbc:postgresql://localhost:5432/mydb"
• With options: "localhost:5432/mydb?ssl=true"

MariaDB:

• Simple: "localhost:3306/mydb"
• JDBC: "jdbc:mariadb://localhost:3306/mydb"

MongoDB:

• Simple: "localhost:27017/mydb"
• Full: "mongodb://localhost:27017/mydb"
• Cluster: "mongodb://host1:27017,host2:27017/mydb?replicaSet=rs0"

---

Documentation 📚

• Installation Guide - Installation options and setup
• Configuration Guide - Complete configuration reference with all options
• Multi-Database Guide - Multi-database setup and best practices
• Examples - Full code examples

---

Architecture 🏛️

Helios follows a modular architecture:

helios/
├── api/          - Core interfaces and annotations
├── sql/          - Common SQL functionality
├── postgres/     - PostgreSQL implementation
├── mariadb/      - MariaDB implementation
└── mongo/        - MongoDB implementation

Each database provider is independent and can be included as needed.

---

Requirements 📋

• Java 17 or higher
• One or more of:
  • PostgreSQL 12+ (optional)
  • MariaDB 10.6+ (optional)
  • MongoDB 4.4+ (optional)

---

Contributing 🤝

We welcome contributions! See CONTRIBUTING.md for detailed guidelines.

Quick start:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Create a Pull Request to main
5. CI will run automatically on your PR

---

Roadmap 🗺️

v2.1 (Planned)

• Hybrid entities (data spanning SQL + NoSQL)
• Cross-storage relations
• Advanced caching layer
• Query result streaming

v2.2 (Future)

• Reactive/async support
• Schema migration tools
• Advanced monitoring and metrics

---

License 📜

Helios is released under the MIT License.

---

Authors ✍️

• Nassime - GitHub
• Contributors - See CONTRIBUTORS.md

---

Support 💬

• 🐛 Issues: GitHub Issues
• 💡 Discussions: GitHub Discussions

---

Made with ❤️ by NA2SIME