Configuración Hibernate con Gradle

Arquitectura de un proyecto Hibernate con Gradle

Hibernate es el ORM de referencia en el ecosistema Java. Se apoya en JPA (Jakarta Persistence API) como estándar y añade extensiones propias para rendimiento, caché y consultas nativas. Un proyecto Gradle bien organizado declara Hibernate como dependencia, incluye el driver JDBC apropiado y define la configuración de conexión en un archivo centralizado.

La instalación limpia tiene cuatro piezas: el build.gradle con dependencias, el hibernate.cfg.xml con la conexión, al menos una entidad @Entity y una clase que abre la SessionFactory. A partir de esa base se pueden añadir repositorios, DAOs, transacciones y pruebas con una base de datos embebida como H2 o Testcontainers.

En proyectos Spring Boot conviene no declarar hibernate.cfg.xml manualmente; el autoconfigurador de Spring inyecta las propiedades desde application.yml. Esta lección cubre Hibernate puro para entender qué hace Spring bajo el capó.

Dependencias en build.gradle

El archivo build.gradle declara el plugin de Java, los repositorios y las dependencias. Para un proyecto moderno con Hibernate 6 sobre MySQL 8 se incluyen tanto hibernate-core como mysql-connector-j.

plugins {
    id 'java'
}

group = 'com.certidevs'
version = '1.0-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.hibernate.orm:hibernate-core:6.6.0.Final'
    implementation 'com.mysql:mysql-connector-j:9.0.0'
    implementation 'org.slf4j:slf4j-simple:2.0.13'

    testImplementation platform('org.junit:junit-bom:5.10.2')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    testImplementation 'org.testcontainers:mysql:1.19.7'
}

test {
    useJUnitPlatform()
}

El plugin java compila las fuentes, mavenCentral() resuelve dependencias del repositorio central y la toolchain fija Java 21 LTS. SLF4J redirige los logs internos de Hibernate a la consola; sin esta dependencia, Hibernate solo muestra avisos de que no encuentra un backend de logs.

Archivo hibernate.cfg.xml

Hibernate lee su configuración desde src/main/resources/hibernate.cfg.xml. El archivo define driver, URL de conexión, credenciales, dialecto SQL y las entidades que participan en el mapeo.

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>
        <property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property>
        <property name="hibernate.connection.url">
            jdbc:mysql://localhost:3306/pedidos?createDatabaseIfNotExist=true&amp;useSSL=false
        </property>
        <property name="hibernate.connection.username">root</property>
        <property name="hibernate.connection.password">admin</property>
        <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="hibernate.hbm2ddl.auto">update</property>
        <property name="hibernate.show_sql">true</property>
        <property name="hibernate.format_sql">true</property>
        <property name="hibernate.connection.pool_size">20</property>
        <mapping class="com.certidevs.ecommerce.Pedido" />
    </session-factory>
</hibernate-configuration>

hibernate.hbm2ddl.auto=update es cómodo en desarrollo pero peligroso en producción, donde conviene usar validate y aplicar migraciones con Flyway o Liquibase. Cambiar este valor sin revisión genera incidentes reales en equipos grandes.

Primera entidad JPA

Una entidad es una clase Java anotada con @Entity que Hibernate mapea a una tabla. La clave primaria se declara con @Id y puede generarse automáticamente con @GeneratedValue.

package com.certidevs.ecommerce;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.math.BigDecimal;
import java.time.LocalDateTime;

@Entity
@Table(name = "pedidos")
public class Pedido {

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

    @Column(nullable = false, length = 60)
    private String referencia;

    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal total;

    @Column(name = "fecha_creacion", nullable = false)
    private LocalDateTime fechaCreacion = LocalDateTime.now();

    public Pedido() {}

    public Pedido(String referencia, BigDecimal total) {
        this.referencia = referencia;
        this.total = total;
    }

    // getters y setters
}

Las anotaciones pertenecen al paquete jakarta.persistence.*, nombre actual del estándar JPA tras la migración desde javax. Hibernate 6 solo soporta este paquete; el antiguo javax.persistence queda reservado para versiones 5.x.

Arranque y primera inserción

La clase Main crea la SessionFactory, abre una sesión, inicia una transacción, persiste un objeto y cierra recursos. Este patrón es el núcleo de cualquier operación con Hibernate puro.

package com.certidevs.ecommerce;

import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
import java.math.BigDecimal;

public class Main {
    public static void main(String[] args) {
        SessionFactory sessionFactory = new Configuration()
            .configure()
            .buildSessionFactory();

        try (Session session = sessionFactory.openSession()) {
            session.beginTransaction();
            Pedido pedido = new Pedido("REF-2026-0042", new BigDecimal("149.90"));
            session.persist(pedido);
            session.getTransaction().commit();
            System.out.println("Pedido persistido con id " + pedido.getId());
        } finally {
            sessionFactory.close();
        }
    }
}

Caso real en un mayorista de retail

Un mayorista de retail con catálogos estacionales usa Hibernate 6 con Gradle para su backend de pedidos. El proyecto separa la configuración en tres hibernate.cfg.xml por entorno: desarrollo (MySQL local), staging (RDS de AWS con réplica) y produccion (Aurora MySQL multi-AZ). Gradle selecciona el archivo adecuado con una propiedad del sistema:

test {
    systemProperty 'hibernate.cfg', System.getProperty('hibernate.cfg', 'hibernate-test.cfg.xml')
    useJUnitPlatform()
}

En el código, la configuración se carga con new Configuration().configure(System.getProperty("hibernate.cfg")), lo que permite probar localmente contra MySQL real o contra Testcontainers sin tocar el código fuente.

Flujo de arranque

flowchart LR
    A[build.gradle] --> B["Dependencias Hibernate + JDBC"]
    B --> C[hibernate.cfg.xml]
    C --> D[Configuration.configure]
    D --> E[buildSessionFactory]
    E --> F[openSessión]
    F --> G["Transacción + persist"]
    G --> H[commit]

Con esta estructura el proyecto queda listo para crecer hacia asociaciones entre entidades, consultas JPQL y optimización de fetchs. El siguiente paso típico es reemplazar hibernate.cfg.xml por un persistence.xml de JPA o migrar directamente a Spring Boot Data JPA, que aporta repositorios autogestionados y transacciones declarativas.