From e34e08b918c6aac32d2559a6ddbbe2c7536735a1 Mon Sep 17 00:00:00 2001 From: Gavin Date: Sat, 20 May 2023 18:27:26 +0200 Subject: [PATCH] more info about caching (Caffeine) and logging --- .../asciidoc/introduction/Configuration.adoc | 66 ++++++++++++------- .../main/asciidoc/introduction/Tuning.adoc | 24 ++++++- 2 files changed, 65 insertions(+), 25 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index d1a3a48f62..e7395dfc76 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/documentation/src/main/asciidoc/introduction/Configuration.adoc @@ -57,7 +57,7 @@ You'll also need to add a dependency for the JDBC driver for your database. .JDBC driver dependencies -[cols="40,~"] +[cols="50,~"] |=== | Database | Driver dependency @@ -85,22 +85,34 @@ Where `{version}` is the latest version of the JDBC driver for your databse. :ehcache: https://www.ehcache.org :infinispan: https://infinispan.org :generator: https://hibernate.org/orm/tooling/ +:caffeine: https://github.com/ben-manes/caffeine/ Optionally, you might also add any of the following additional features: .Optional dependencies -[cols="40,~"] +[cols="50,~"] |=== | Optional feature | Dependencies -| An {slf4j}[SLF4J] logging implementation | `org.apache.logging.log4j:log4j-core` or `org.slf4j:slf4j-jdk14` -| A JDBC connection pool, for example, {agroal}[Agroal] | `org.hibernate.orm:hibernate-agroal` and `io.agroal:agroal-pool` +| An {slf4j}[SLF4J] logging implementation | +`org.apache.logging.log4j:log4j-core` + +or `org.slf4j:slf4j-jdk14` +| A JDBC connection pool, for example, {agroal}[Agroal] | +`org.hibernate.orm:hibernate-agroal` + +and `io.agroal:agroal-pool` | The {generator}[Hibernate Metamodel Generator], especially if you're using the JPA criteria query API | `org.hibernate.orm:hibernate-jpamodelgen` -| {validator}[Hibernate Validator] | `org.hibernate.validator:hibernate-validator` and `org.glassfish:jakarta.el` -| Local second-level cache support via JCache and {ehcache}[EHCache] | `org.hibernate.orm:hibernate-jcache` along with `org.ehcache:ehcache` +| {validator}[Hibernate Validator] | +`org.hibernate.validator:hibernate-validator` + +and `org.glassfish:jakarta.el` +| Local second-level cache support via JCache and {ehcache}[EHCache] | `org.hibernate.orm:hibernate-jcache` + +and `org.ehcache:ehcache` +| Local second-level cache support via JCache and {caffeine}[Caffeine]| `org.hibernate.orm:hibernate-jcache` + +and `com.github.ben-manes.caffeine:jcache` | Distributed second-level cache support via {infinispan}[Infinispan] | `org.infinispan:infinispan-hibernate-cache-v60` // | SCRAM authentication support for PostgreSQL | `com.ongres.scram:client:2.1` -| A JSON serialization library for working with JSON datatypes, for example, {jackson}[Jackson] or {yasson}[Yasson] | `com.fasterxml.jackson.core:jackson-databind` or `org.eclipse:yasson` +| A JSON serialization library for working with JSON datatypes, for example, {jackson}[Jackson] or {yasson}[Yasson] | +`com.fasterxml.jackson.core:jackson-databind` + +or `org.eclipse:yasson` | <> | `org.hibernate.orm:hibernate-spatial` |=== @@ -368,32 +380,42 @@ sessionFactory.getSchemaManager().exportMappedObjects(true); :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: +To see the generated SQL as it's sent to the database, you have two options. -- 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 <>), add these lines to your `log4j2.properties` file: - -[source,properties] ----- -logger.hibernate.name = org.hibernate.SQL -logger.hibernate.level = debug ----- - -You can make the SQL logged to the console more readable by enabling formatting or highlighting. +One way is to set the property `hibernate.show_sql` to `true`, and Hibernate will log SQL direct to the console. +You can make the output much more readable by enabling formatting or highlighting. +These settings really help when troubleshooting the generated SQL statements. .Settings for SQL logging to the console [cols="35,~"] |=== | Configuration property name | Purpose -| `hibernate.show_sql` | If `true`, log SQL directly to the console +| `hibernate.show_sql` | If `true`, log SQL directly to the console | `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 |=== -These settings can really help when troubleshooting SQL. +Alternatively, you can 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 <>), add these lines to your `log4j2.properties` file: + +[source,properties] +---- +# SQL execution +logger.hibernate.name = org.hibernate.SQL +logger.hibernate.level = debug + +# JDBC parameter binding +logger.jdbc-bind.name=org.hibernate.orm.jdbc.bind +logger.jdbc-bind.level=trace +# JDBC result set extraction +logger.jdbc-extract.name=org.hibernate.orm.jdbc.extract +logger.jdbc-extract.level=trace + +---- + +But with this approach we miss out on the pretty highlighting. [[minimizing]] === Minimizing repetitive mapping information diff --git a/documentation/src/main/asciidoc/introduction/Tuning.adoc b/documentation/src/main/asciidoc/introduction/Tuning.adoc index 0f2ab839e2..4e2eec51c6 100644 --- a/documentation/src/main/asciidoc/introduction/Tuning.adoc +++ b/documentation/src/main/asciidoc/introduction/Tuning.adoc @@ -329,13 +329,12 @@ But in case it helps, we often test Hibernate with the following configuration, :ehcache-config: https://www.ehcache.org/documentation/ -.EHCache provider configuration +.EHCache configuration [cols="35,~"] |=== | Configuration property name | Property value | `hibernate.cache.region.factory_class` | `jcache` -| `hibernate.javax.cache.provider` | `org.ehcache.jsr107.EhcacheCachingProvider` | `hibernate.javax.cache.uri` | `/ehcache.xml` |=== @@ -344,6 +343,25 @@ that explicitly configures the behavior of each cache region belonging to your entities and collections. You'll find more information about configuring EHCache {ehcache-config}[here]. +:caffeine: https://github.com/ben-manes/caffeine/ + +We may use any other implementation of JCache, such as {caffeine}[Caffeine]. +JCache automatically selects whichever implementation it finds on the classpath. +If there are multiple implementations on the classpath, we must disambiguate using: + +.Disambiguating the JCache implementation +[cols="35,~"] +|=== +| Configuration property name | Property value + +| `hibernate.javax.cache.provider` a| The implementation of `javax.cache.spiCachingProvider`, for example: +[cols="~,20"] +!=== +! `org.ehcache.jsr107.EhcacheCachingProvider` ! for EHCache +! `com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider` ! for Caffeine +!=== +|=== + Alternatively, to use Infinispan as the cache implementation, the following settings are required: :infinispan-hibernate: https://infinispan.org/docs/stable/titles/hibernate/hibernate.html @@ -365,7 +383,7 @@ Alternatively, to use Infinispan as the cache implementation, the following sett |=== Infinispan is usually used when distributed caching is required. -You'll find more information about using Infinispan with Hibernate {infinispan-hibernate}[here] . +There's more about using Infinispan with Hibernate {infinispan-hibernate}[here]. Finally, there's a way to globally disable the second-level cache: