<commit_before>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////

include::./attributes.adoc[]
= {project-name} - Using Hibernate ORM and JPA
:config-file: application.properties

Hibernate ORM is the de facto JPA implementation and offers you the full breath of an Object Relational Mapper.
It works beautifully in {project-name}.

== Setting up and configuring Hibernate ORM without `persistence.xml` (recommended)

More often than not, you need one _persistence unit_ with few configuration options.
In {project-name}, you just need to:

* add your settings in `{config-file}`
* annotate your entities with `@Entity` and friends

and we make some opinionated choices and educated guesses.

In your `pom.xml`, add the following dependencies:

* the Hibernate ORM extension
* your JDBC driver extension (`quarkus-jdbc-postgresql`, `quarkus-jdbc-h2`, `quarkus-jdbc-mariadb`, ...)

[source,xml]
--
<dependencies>
    <!-- Hibernate ORM specific dependencies -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-hibernate-orm</artifactId>
    </dependency>

    <!-- JDBC driver dependencies -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-jdbc-postgresql</artifactId>
    </dependency>
</dependencies>
--

Annotate your persistent objects with `@Entity`,
then add the relevant configuration properties in `{config-file}`.

[source,properties]
--
# configure your datasource
quarkus.datasource.url: jdbc:postgresql://localhost:5432/mydatabase
quarkus.datasource.driver: org.postgresql.Driver
quarkus.datasource.username: sarah
quarkus.datasource.password: <PASSWORD>

# drop and create the database at startup (use `update` to only update the schema)
quarkus.hibernate-orm.database.generation=drop-and-create
--

Note that these configuration properties are not the same ones as made available in `{config-file}`: they might differ in names, casing and don't necessarily map 1:1 to each other.

An `EntityManagerFactory` will be created based on {project-name} `datasource` configuration as long as the Hibernate ORM extension is declared in your `pom.xml`.
The dialect will be selected based on the JDBC driver.

You can then happily inject your `EntityManager`:

[source,java]
--
@ApplicationScoped
public class SantaClausService {
    @Inject
    EntityManager em; <1>

    @Transactional <2>
    public void createGift(String giftDescription) {
        Gift gift = new Gift();
        gift.setName(giftDescription);
        em.persist(gift);
    }
}

//and of course our entity
@Entity
public class Gift {
    private Long id;
    private String name;

    @Id @GeneratedValue(strategy = GenerationType.SEQUENCE, generator="giftSeq")
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}
--

<1> Inject your entity manager and have fun
<2> Mark your CDI bean method as `@Transactional` and the `EntityManager` will enlist and flush at commit.

To load some SQL statements when Hibernate ORM starts, add a `import.sql` in the root of your resources directory.
It contains SQL DML statements (one by line).
This is useful to have a data set ready for your tests or demos.

=== Properties to refine your Hibernate ORM configuration

There are optional properties useful to refine your `EntityManagerFactory` or guide guesses of {project-name}.

==== Dialect

`quarkus.hibernate-orm.dialect`:: (e.g. `org.hibernate.dialect.PostgreSQL95Dialect`).
Class name of the Hibernate ORM dialect.

`quarkus.hibernate-orm.dialect.storage-engine`:: (e.g. `MyISAM` or `InnoDB`).
The storage engine to use when the dialect supports multiple storage engines.

==== Miscellaneous

`quarkus.hibernate-orm.sql-load-script`::
(defaults to `/import.sql`) Name of the file containing the SQL statements to execute when Hibernate ORM starts.
By default, simply add `import.sql` in the root of your resources directory and it will be picked up without having to set this property.

`quarkus.hibernate-orm.batch-fetch-size`:: (defaults to `-1` i.e. batch fetching is disabled).
The size of the batches used when loading entities and collections.

==== Query

`quarkus.hibernate-orm.query.query-plan-cache-max-size`::
The maximum size of the query plan cache.

`quarkus.hibernate-orm.query.default-null-ordering`:: (defaults to `none`).
Default precedence of null values in `ORDER BY` clauses.
Options are `none`, `first`, `last`.

==== Database

`quarkus.hibernate-orm.database.generation`::
(e.g. `drop-and-create` which is awesome in development mode). Select whether the database schema is generated or not.
Options are `none`, `create`, `drop-and-create`, `drop`

`quarkus.hibernate-orm.database.generation.halt-on-error`:: (defaults to `false`)
Whether we should stop on the first error when applying the schema.

`quarkus.hibernate-orm.database.default-catalog`::
The default catalog to use for the database objects.

`quarkus.hibernate-orm.database.default-schema`::
The default schema to use for the database objects.

`quarkus.hibernate-orm.database.charset`::
The charset of the database.

==== JDBC

`quarkus.hibernate-orm.jdbc.timezone`::
The time zone pushed to the JDBC driver.

`quarkus.hibernate-orm.jdbc.statement-fetch-size`::
How many rows are fetched at a time by the JDBC driver.
<commit_msg>Mention the update option for Hibernate ORM's schema generation<commit_after>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////

include::./attributes.adoc[]
= {project-name} - Using Hibernate ORM and JPA
:config-file: application.properties

Hibernate ORM is the de facto JPA implementation and offers you the full breath of an Object Relational Mapper.
It works beautifully in {project-name}.

== Setting up and configuring Hibernate ORM without `persistence.xml` (recommended)

More often than not, you need one _persistence unit_ with few configuration options.
In {project-name}, you just need to:

* add your settings in `{config-file}`
* annotate your entities with `@Entity` and friends

and we make some opinionated choices and educated guesses.

In your `pom.xml`, add the following dependencies:

* the Hibernate ORM extension
* your JDBC driver extension (`quarkus-jdbc-postgresql`, `quarkus-jdbc-h2`, `quarkus-jdbc-mariadb`, ...)

[source,xml]
--
<dependencies>
    <!-- Hibernate ORM specific dependencies -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-hibernate-orm</artifactId>
    </dependency>

    <!-- JDBC driver dependencies -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-jdbc-postgresql</artifactId>
    </dependency>
</dependencies>
--

Annotate your persistent objects with `@Entity`,
then add the relevant configuration properties in `{config-file}`.

[source,properties]
--
# configure your datasource
quarkus.datasource.url: jdbc:postgresql://localhost:5432/mydatabase
quarkus.datasource.driver: org.postgresql.Driver
quarkus.datasource.username: sarah
quarkus.datasource.password: <PASSWORD>

# drop and create the database at startup (use `update` to only update the schema)
quarkus.hibernate-orm.database.generation=drop-and-create
--

Note that these configuration properties are not the same ones as made available in `{config-file}`: they might differ in names, casing and don't necessarily map 1:1 to each other.

An `EntityManagerFactory` will be created based on {project-name} `datasource` configuration as long as the Hibernate ORM extension is declared in your `pom.xml`.
The dialect will be selected based on the JDBC driver.

You can then happily inject your `EntityManager`:

[source,java]
--
@ApplicationScoped
public class SantaClausService {
    @Inject
    EntityManager em; <1>

    @Transactional <2>
    public void createGift(String giftDescription) {
        Gift gift = new Gift();
        gift.setName(giftDescription);
        em.persist(gift);
    }
}

//and of course our entity
@Entity
public class Gift {
    private Long id;
    private String name;

    @Id @GeneratedValue(strategy = GenerationType.SEQUENCE, generator="giftSeq")
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}
--

<1> Inject your entity manager and have fun
<2> Mark your CDI bean method as `@Transactional` and the `EntityManager` will enlist and flush at commit.

To load some SQL statements when Hibernate ORM starts, add a `import.sql` in the root of your resources directory.
It contains SQL DML statements (one by line).
This is useful to have a data set ready for your tests or demos.

=== Properties to refine your Hibernate ORM configuration

There are optional properties useful to refine your `EntityManagerFactory` or guide guesses of {project-name}.

==== Dialect

`quarkus.hibernate-orm.dialect`:: (e.g. `org.hibernate.dialect.PostgreSQL95Dialect`).
Class name of the Hibernate ORM dialect.

`quarkus.hibernate-orm.dialect.storage-engine`:: (e.g. `MyISAM` or `InnoDB`).
The storage engine to use when the dialect supports multiple storage engines.

==== Miscellaneous

`quarkus.hibernate-orm.sql-load-script`::
(defaults to `/import.sql`) Name of the file containing the SQL statements to execute when Hibernate ORM starts.
By default, simply add `import.sql` in the root of your resources directory and it will be picked up without having to set this property.

`quarkus.hibernate-orm.batch-fetch-size`:: (defaults to `-1` i.e. batch fetching is disabled).
The size of the batches used when loading entities and collections.

==== Query

`quarkus.hibernate-orm.query.query-plan-cache-max-size`::
The maximum size of the query plan cache.

`quarkus.hibernate-orm.query.default-null-ordering`:: (defaults to `none`).
Default precedence of null values in `ORDER BY` clauses.
Options are `none`, `first`, `last`.

==== Database

`quarkus.hibernate-orm.database.generation`::
(e.g. `drop-and-create` which is awesome in development mode). Select whether the database schema is generated or not.
Options are `none`, `create`, `drop-and-create`, `drop`, `update`. The default is `none`.

`quarkus.hibernate-orm.database.generation.halt-on-error`:: (defaults to `false`)
Whether we should stop on the first error when applying the schema.

`quarkus.hibernate-orm.database.default-catalog`::
The default catalog to use for the database objects.

`quarkus.hibernate-orm.database.default-schema`::
The default schema to use for the database objects.

`quarkus.hibernate-orm.database.charset`::
The charset of the database.

==== JDBC

`quarkus.hibernate-orm.jdbc.timezone`::
The time zone pushed to the JDBC driver.

`quarkus.hibernate-orm.jdbc.statement-fetch-size`::
How many rows are fetched at a time by the JDBC driver.

{'fraction_non_alphanumeric': 0.10202630643441166, 'fraction_numerical': 0.002488446498400284, 'mean_word_length': 4.110354223433243, 'pattern_counts': {'":': 0, '<': 45, '<?xml version=': 0, '>': 45, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2132830', 'n_tokens_mistral': 3474, 'n_tokens_neox': 3201, 'n_words': 1219}