Hibernate Foreign Reference Support

A Hibernate ORM extension that provides a convenient way to define foreign keys (Foreign Keys) through annotations on entity fields.

Description

А library that allows declarative definition of foreign key relationships between database tables through a simple @ForeignRef annotation. This extension works at the Hibernate metadata level, using the AdditionalMappingContributor mechanism, and automatically creates foreign key constraints during session initialization.

Features

• 🎯 Easy to Use — simply add the @ForeignRef annotation to an entity field
• 🔄 Automatic Naming — automatically generates constraint names according to Hibernate's naming strategy
• 🎨 Flexible — supports both explicit target column specification and automatic primary key detection
• 📝 Convention Respecting — respects Hibernate's column and table naming strategies
• ⚡ Minimal Dependencies — requires only Hibernate Core (in provided scope)

Requirements

• Java 21+
• Hibernate ORM 6.6.36+ — works with modern versions of Hibernate

Installation

Maven

Add the dependency to your pom.xml:

<dependency>
    <groupId>io.github.intellinside</groupId>
    <artifactId>hibernate-foreign-key-support</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'io.github.intellinside:hibernate-foreign-key-support:0.1.0'

Quick Start

Basic Example

@Entity
@Table(name = "orders")
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ForeignRef(entity = Customer.class)
    @Column(name = "customer_id")
    private Long customerId;

    private LocalDateTime createdAt;

    // Getters and Setters
}

@Entity
@Table(name = "customers")
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String email;

    // Getters and Setters
}

In this example, a foreign key constraint will be automatically created that links the customer_id column of the orders table to the primary key of the customers table.

Example with Explicit Target Column

@Entity
@Table(name = "products")
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @Column(name = "category_code")
    private String categoryCode;

    // Getters and Setters
}

@Entity
@Table(name = "categories")
public class Category {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "code", unique = true)
    private String code;

    private String name;

    // Getters and Setters
}

// In the Product class:
@ForeignRef(entity = Category.class, referencedColumn = "code")
@Column(name = "category_code")
private String categoryCode;

Example with Custom Constraint Name

@Entity
@Table(name = "order_items")
public class OrderItem {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ForeignRef(entity = Order.class, name = "fk_item_order")
    @Column(name = "order_id")
    private Long orderId;

    @ForeignRef(entity = Product.class, name = "fk_item_product")
    @Column(name = "product_id")
    private Long productId;

    private Integer quantity;
    private BigDecimal price;

    // Getters and Setters
}

License

The project is distributed under the MIT License. For details, see the LICENSE file.

Support and Issues

If you have questions, problems, or suggestions:

1. Check Issues
2. Create a new Issue with a detailed description
3. Attach a code example demonstrating the problem