copy configuration section from HR intro
This commit is contained in:
Gavin
Christian Beikov
parent
ce20e68c72
commit
b77d5bd3b8
|
|
@ -20,5 +20,319 @@ The fourth option is extremely popular, since every major Java application serve
|
||||||
Such container environments also typically feature facilities to automatically manage the lifecycle of an `EntityManager` or `Session` and its association with container-managed transactions.
|
Such container environments also typically feature facilities to automatically manage the lifecycle of an `EntityManager` or `Session` and its association with container-managed transactions.
|
||||||
To learn how to configure Hibernate in such a container environment, you'll need to refer to the documentation of your chosen container.
|
To learn how to configure Hibernate in such a container environment, you'll need to refer to the documentation of your chosen container.
|
||||||
|
|
||||||
|
[[required-dependencies]]
|
||||||
|
=== Including Hibernate in your project build
|
||||||
|
|
||||||
|
If you're using Hibernate outside of a container environment,
|
||||||
|
you'll need to:
|
||||||
|
|
||||||
|
- include Hibernate ORM itself, along with the appropriate JDBC driver, as dependencies of your project, and
|
||||||
|
- configure Hibernate with information about your database,
|
||||||
|
by specifying configuration properties.
|
||||||
|
|
||||||
|
First, add the following dependency to your project:
|
||||||
|
|
||||||
|
----
|
||||||
|
org.hibernate.orm:hibernate-core:{version}
|
||||||
|
----
|
||||||
|
|
||||||
|
Where `{version}` is the version of Hibernate you're using.
|
||||||
|
|
||||||
|
You'll also need to add a dependency for the JDBC
|
||||||
|
driver for your database.
|
||||||
|
|
||||||
|
|===
|
||||||
|
| Database | Driver dependency
|
||||||
|
|
||||||
|
| PostgreSQL or CockroachDB | `org.postgresql:postgresql:{version}`
|
||||||
|
| MySQL | `mysql:mysql-connector-java:{version}`
|
||||||
|
| MariaDB | `org.mariadb.jdbc:mariadb-java-client:{version}`
|
||||||
|
| DB2 | `com.ibm.db2:jcc:{version}`
|
||||||
|
| SQL Server | `com.microsoft.sqlserver:mssql-jdbc:${version}`
|
||||||
|
| Oracle | `com.oracle.database.jdbc:ojdbc8:${version}`
|
||||||
|
| h2 | `com.h2database:h2:{version}`
|
||||||
|
|===
|
||||||
|
|
||||||
|
Where `{version}` is the latest version of the JDBC driver for your databse.
|
||||||
|
|
||||||
|
[[optional-dependencies]]
|
||||||
|
=== Optional dependencies
|
||||||
|
|
||||||
|
:slf4j: http://www.slf4j.org/
|
||||||
|
:enhancer: https://docs.jboss.org/hibernate/orm/5.4/topical/html_single/bytecode/BytecodeEnhancement.html
|
||||||
|
|
||||||
|
Optionally, you might also add any of the following additional features:
|
||||||
|
|
||||||
|
|===
|
||||||
|
| Optional feature | Dependencies
|
||||||
|
|
||||||
|
| An {slf4j}[SLF4J] logging implementation | `org.apache.logging.log4j:log4j-core` or `org.slf4j:slf4j-jdk14`
|
||||||
|
| The Hibernate metamodel generator, if you're using the JPA criteria query API | `org.hibernate.orm:hibernate-jpamodelgen`
|
||||||
|
| Hibernate Validator | `org.hibernate.validator:hibernate-validator` and `org.glassfish:jakarta.el`
|
||||||
|
| Compile-time checking for your HQL queries | `org.hibernate:query-validator`
|
||||||
|
| Second-level cache support via JCache and EHCache | `org.hibernate.orm:hibernate-jcache` along with `org.ehcache:ehcache`
|
||||||
|
// | SCRAM authentication support for PostgreSQL | `com.ongres.scram:client:2.1`
|
||||||
|
|===
|
||||||
|
|
||||||
|
You might also add the Hibernate {enhancer}[bytecode enhancer] to your
|
||||||
|
Gradle build if you want to use field-level lazy fetching.
|
||||||
|
|
||||||
|
TIP: Field-level lazy fetching is an advanced feature that most programs
|
||||||
|
don't need. Stick to the basics for now.
|
||||||
|
|
||||||
[[configuration-jpa]]
|
[[configuration-jpa]]
|
||||||
=== Configuration using JPA
|
=== Configuration using JPA XML
|
||||||
|
|
||||||
|
Sticking to the JPA-standard approach, we would provide a file named `persistence.xml`, which we usually place in the `META-INF` directory of a _persistence archive_, that is, of the `.jar` file or directory which contains our entity classes.
|
||||||
|
|
||||||
|
[source,xml]
|
||||||
|
----
|
||||||
|
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
|
||||||
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd"
|
||||||
|
version="2.0">
|
||||||
|
|
||||||
|
<persistence-unit name="org.hibernate.example">
|
||||||
|
|
||||||
|
<class>org.hibernate.example.Book</class>
|
||||||
|
<class>org.hibernate.example.Author</class>
|
||||||
|
|
||||||
|
<properties>
|
||||||
|
<!-- PostgreSQL -->
|
||||||
|
<property name="jakarta.persistence.jdbc.url"
|
||||||
|
value="jdbc:postgresql://localhost/example"/>
|
||||||
|
|
||||||
|
<!-- Credentials -->
|
||||||
|
<property name="jakarta.persistence.jdbc.user"
|
||||||
|
value="gavin"/>
|
||||||
|
<property name="jakarta.persistence.jdbc.password"
|
||||||
|
value="hibernate"/>
|
||||||
|
|
||||||
|
<!-- Automatic schema export -->
|
||||||
|
<property name="jakarta.persistence.schema-generation.database.action"
|
||||||
|
value="drop-and-create"/>
|
||||||
|
|
||||||
|
<!-- SQL statement logging -->
|
||||||
|
<property name="hibernate.show_sql" value="true"/>
|
||||||
|
<property name="hibernate.format_sql" value="true"/>
|
||||||
|
<property name="hibernate.highlight_sql" value="true"/>
|
||||||
|
|
||||||
|
</properties>
|
||||||
|
|
||||||
|
</persistence-unit>
|
||||||
|
|
||||||
|
</persistence>
|
||||||
|
----
|
||||||
|
The `<persistence-unit>` element defines a named _persistence unit_, that is:
|
||||||
|
|
||||||
|
- a collection of associated entity types, along with
|
||||||
|
- a set of default configuration settings, which may be augmented or overridden at runtime.
|
||||||
|
|
||||||
|
Each `<class>` element specifies the fully-qualified name of an entity class.
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
.Scanning for entity classes
|
||||||
|
====
|
||||||
|
In some container environments, for example, in any EE container, the `<class>` elements are unnecessary, since the container will scan the archive for annotated classes, and automatically recognize any class annotated `@Entity`.
|
||||||
|
====
|
||||||
|
|
||||||
|
Each `<property>` element specifies a _configuration property_ and its value:
|
||||||
|
|
||||||
|
- the configuration properties in the `jakarta.persistence` namespace are standard properties defined by the JPA spec, and
|
||||||
|
- properties in the `hibernate` namespace are defined by Hibernate.
|
||||||
|
|
||||||
|
We may obtain an `EntityManagerFactory` by calling `Persistence.createEntityManagerFactory()`:
|
||||||
|
|
||||||
|
[source,java]
|
||||||
|
----
|
||||||
|
EntityManagerFactory emf =
|
||||||
|
Persistence.createEntityManagerFactory("org.hibernate.example");
|
||||||
|
----
|
||||||
|
|
||||||
|
If necessary, we may override configuration properties specified in `persistence.xml`:
|
||||||
|
|
||||||
|
[source,java]
|
||||||
|
----
|
||||||
|
EntityManagerFactory emf =
|
||||||
|
Persistence.createEntityManagerFactory("org.hibernate.example",
|
||||||
|
Map.of(AvailableSettings.JAKARTA_JDBC_PASSWORD, password));
|
||||||
|
----
|
||||||
|
|
||||||
|
[[configuration-api]]
|
||||||
|
=== Configuration using Hibernate API
|
||||||
|
|
||||||
|
Alternatively, the venerable class `org.hibernate.cfg.Configuration` allows an instance of Hibernate to be configured in Java code:
|
||||||
|
|
||||||
|
[source,java]
|
||||||
|
----
|
||||||
|
SessionFactory factory = new Configuration()
|
||||||
|
.addAnnotatedClass(Book.class)
|
||||||
|
.addAnnotatedClass(Author.class)
|
||||||
|
.setProperty(AvailableSettings.JAKARTA_JDBC_URL, "jdbc:postgresql://localhost/example")
|
||||||
|
.setProperty(AvailableSettings.JAKARTA_JDBC_USER, user)
|
||||||
|
.setProperty(AvailableSettings.JAKARTA_JDBC_PASSWORD, password)
|
||||||
|
.setProperty(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION, Action.CREATE)
|
||||||
|
.setProperty(AvailableSettings.SHOW_SQL, true)
|
||||||
|
.setProperty(AvailableSettings.FORMAT_SQL, true)
|
||||||
|
.setProperty(AvailableSettings.HIGHLIGHT_SQL, true)
|
||||||
|
.buildSessionFactory();
|
||||||
|
----
|
||||||
|
|
||||||
|
The `Configuration` class has survived almost unchanged since the very earliest (pre-1.0) versions of Hibernate, and so it doesn't look particularly modern.
|
||||||
|
On the other hand, it's very easy to use, and exposes some options that `persistence.xml` doesn't support.
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
.Advanced configuration options
|
||||||
|
====
|
||||||
|
Actually, the `Configuration` class is just a very simple facade for the more modern, much more powerful—but more complex—API defined in the package `org.hibernate.boot`.
|
||||||
|
This API is useful if you have very advanced requirements, for example, if you're writing a framework or implementing a container.
|
||||||
|
You'll find more information in the Hibernate ORM Integration Guide, and in the package-level documentation of `org.hibernate.boot`.
|
||||||
|
====
|
||||||
|
|
||||||
|
[[basic-configuration-settings]]
|
||||||
|
=== Basic configuration settings
|
||||||
|
|
||||||
|
The class `org.hibernate.cfg.AvailableSettings` enumerates all the configuration properties understood by Hibernate.
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
.You ain't gunna need 'em
|
||||||
|
====
|
||||||
|
Hibernate has many—too many—switches and toggles.
|
||||||
|
Please don't go crazy messing about with these settings; most of them are rarely needed, and many only exist to provide backward compatibility with older versions of Hibernate.
|
||||||
|
With rare exception, the default behavior of every one of these settings was carefully chosen to be _the behavior we recommend_.
|
||||||
|
====
|
||||||
|
|
||||||
|
The properties you do need to get started are these three:
|
||||||
|
|
||||||
|
|===
|
||||||
|
| Configuration property name | Purpose
|
||||||
|
|
||||||
|
| `jakarta.persistence.jdbc.url` | JDBC URL of your database
|
||||||
|
| `jakarta.persistence.jdbc.user` and `jakarta.persistence.jdbc.password` | Your database credentials
|
||||||
|
|===
|
||||||
|
|
||||||
|
[IMPORTANT]
|
||||||
|
.You don't need `hibernate.dialect` anymore!
|
||||||
|
====
|
||||||
|
In Hibernate 6, you don't need to specify `hibernate.dialect`.
|
||||||
|
The correct Hibernate SQL `Dialect` will be determined for you.
|
||||||
|
|
||||||
|
The only reason to specify this property is if you're using a custom user-written `Dialect` class.
|
||||||
|
====
|
||||||
|
|
||||||
|
[[automatic-schema-export]]
|
||||||
|
=== Automatic schema export
|
||||||
|
|
||||||
|
You can have Hibernate infer your database schema from the mapping
|
||||||
|
annotations you've specified in your Java code, and export the schema at
|
||||||
|
initialization time by specifying one or more of the following configuration
|
||||||
|
properties:
|
||||||
|
|
||||||
|
[cols="1,1"]
|
||||||
|
|===
|
||||||
|
| Configuration property name | Purpose
|
||||||
|
|
||||||
|
| `jakarta.persistence.schema-generation.database.action`
|
||||||
|
a| * If `drop-and-create`, first drop the schema and then export tables, sequences, and constraints.
|
||||||
|
* If `create`, export tables, sequences, and constraints, without attempting to drop them first.
|
||||||
|
* If `create-drop`, drop the schema and recreate it on `SessionFactory` startup.
|
||||||
|
Additionally, drop the schema on `SessionFactory` shutdown.
|
||||||
|
* If `drop`, drop the schema on `SessionFactory` shutdown.
|
||||||
|
* If `validate`, validate the database schema without changing it.
|
||||||
|
* If `update`, only export what's missing in the schema.
|
||||||
|
|
||||||
|
| `jakarta.persistence.create-database-schemas`
|
||||||
|
| (Optional) If `true`, automatically create schemas and catalogs
|
||||||
|
|
||||||
|
| `jakarta.persistence.schema-generation.create-source`
|
||||||
|
| (Optional) If `metadata-then-script` or `script-then-metadata`, execute an additional SQL script when exported tables and sequences
|
||||||
|
|
||||||
|
| `jakarta.persistence.schema-generation.create-script-source`
|
||||||
|
| (Optional) The name of the SQL script to be executed
|
||||||
|
|===
|
||||||
|
|
||||||
|
This feature is extremely useful for testing.
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
.Importing test or reference data
|
||||||
|
====
|
||||||
|
The easiest way to pre-initialize a database with test or "reference" data is to place a list of SQL `insert` statements in a file named, for example, `import.sql`, and specify the path to this file using the property `jakarta.persistence.schema-generation.create-script-source`.
|
||||||
|
|
||||||
|
This approach is cleaner than writing Java code to instantiate entity instances and calling `persist()` on each of them.
|
||||||
|
====
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
.Programmatic schema export
|
||||||
|
====
|
||||||
|
The `SchemaManager` API allow you to control schema export programmatically.
|
||||||
|
====
|
||||||
|
|
||||||
|
|
||||||
|
=== Logging the generated SQL
|
||||||
|
|
||||||
|
:log4j: https://github.com/hibernate/hibernate-reactive/blob/main/examples/session-example/src/main/resources/log4j2.properties
|
||||||
|
|
||||||
|
To see the generated SQL as it's sent to the database, either:
|
||||||
|
|
||||||
|
- set the property `hibernate.show_sql` to `true`, or
|
||||||
|
- enable debug-level logging for the category `org.hibernate.SQL`
|
||||||
|
using your preferred SLF4J logging implementation.
|
||||||
|
|
||||||
|
For example, if you're using Log4J 2 (as above in <<optional-dependencies>>),
|
||||||
|
add these lines to your `log4j2.properties` file:
|
||||||
|
|
||||||
|
[source,properties]
|
||||||
|
----
|
||||||
|
logger.hibernate.name = org.hibernate.SQL
|
||||||
|
logger.hibernate.level = debug
|
||||||
|
----
|
||||||
|
|
||||||
|
You can make the logged SQL more readable by enabling one or both of
|
||||||
|
the following settings:
|
||||||
|
|
||||||
|
|===
|
||||||
|
| Configuration property name | Purpose
|
||||||
|
|
||||||
|
| `hibernate.format_sql` | If `true`, log SQL in a multiline, indented format
|
||||||
|
| `hibernate.highlight_sql` | If `true`, log SQL with syntax highlighting via ANSI escape codes
|
||||||
|
|===
|
||||||
|
|
||||||
|
=== Minimizing repetitive mapping information
|
||||||
|
|
||||||
|
The following properties are very useful for minimizing the amount of
|
||||||
|
information you'll need to explicitly specify in `@Table` and `@Column`
|
||||||
|
annotations which we'll discuss below in <<mapping-entity-classes>>:
|
||||||
|
|
||||||
|
|===
|
||||||
|
| Configuration property name | Purpose
|
||||||
|
|
||||||
|
| `hibernate.default_schema` | A default schema name for entities which do not explicitly declare one
|
||||||
|
| `hibernate.default_catalog` | A default catalog name for entities which do not explicitly declare one
|
||||||
|
| `hibernate.physical_naming_strategy` | A `PhysicalNamingStrategy` implementing your database naming standards
|
||||||
|
|===
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
.Implement your naming standards as a `PhysicalNamingStrategy`
|
||||||
|
====
|
||||||
|
Writing your own `PhysicalNamingStrategy` is an especially good
|
||||||
|
way to reduce the clutter of annotations on your entity classes, and
|
||||||
|
we think you should do it for any nontrivial data model.
|
||||||
|
====
|
||||||
|
|
||||||
|
=== Nationalized character data in SQL Server
|
||||||
|
|
||||||
|
_By default,_ SQL Server's `char` and `varchar` types don't accommodate
|
||||||
|
Unicode data. So, if you're working with SQL Server, you might need to
|
||||||
|
force Hibernate to use the `nchar` and `nvarchar` types.
|
||||||
|
|
||||||
|
|===
|
||||||
|
| Configuration property name | Purpose
|
||||||
|
|
||||||
|
| `hibernate.use_nationalized_character_data` | Use `nchar` and `nvarchar` instead of `char` and `varchar`
|
||||||
|
|===
|
||||||
|
|
||||||
|
[TIP]
|
||||||
|
.Configuring SQL Server to use UTF-8 by default
|
||||||
|
====
|
||||||
|
Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`.
|
||||||
|
====
|
||||||
Loading…
Reference in New Issue