From ef968dcc07fe92ab54f0a738c433ac6f7a2613f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Wed, 15 Oct 2025 10:39:12 +0200 Subject: [PATCH] Mention third-party dialects throughout the documentation --- dialects.adoc | 19 ++++++++++++++++- .../asciidoc/introduction/Configuration.adoc | 19 +++++++++++++---- .../asciidoc/quickstart/guides/obtaining.adoc | 21 +++++++++++++++++++ .../chapters/jdbc/Database_Access.adoc | 7 +++++-- .../chapters/portability/Portability.adoc | 6 +++++- 5 files changed, 64 insertions(+), 8 deletions(-) diff --git a/dialects.adoc b/dialects.adoc index ffbf79132468..cdf20b4952bc 100644 --- a/dialects.adoc +++ b/dialects.adoc @@ -4,7 +4,7 @@ A dialect is a class that provides information about the specifics of a database == Supported dialects -Hibernate supports a wide range of dialects out of the box. The following is list of officially supported databases: +Hibernate supports a wide range of dialects out of the box: * Apache Derby * Cockroach @@ -29,6 +29,23 @@ but the support for these versions is not guaranteed. Apart from the Hibernate team supported dialects, there are also community dialects. +== Third-party dialects + +Third-parties publish additional dialects for Hibernate ORM, providing their own support for more databases, or extended support beyond what is built in Hibernate ORM: + +* MongoDB: https://github.com/mongodb/mongo-hibernate/[MongoDB extension for Hibernate ORM] +* Google Spanner: https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Cloud Spanner Dialect for Hibernate ORM] + +[NOTE] +==== +Third-party dialects are tested by their own authors, +and may not be compatible with all versions of Hibernate ORM. + +1. Check the dialect's own documentation to know more about its compatibility constraints. +The https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix on the Hibernate website] may also be of help. +2. Submit any question or bug reports about these dialects to the dialect's authors: the Hibernate team cannot help. +==== + == Community dialects As of Hibernate 6.0, the Hibernate team decided to provide a clear way forward for community contributed dialects. diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index 9293cf6e0ce1..525a5917b5ad 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/documentation/src/main/asciidoc/introduction/Configuration.adoc @@ -68,10 +68,11 @@ driver for your database. | SQL Server | `com.microsoft.sqlserver:mssql-jdbc:${version}` | Oracle | `com.oracle.database.jdbc:ojdbc11:${version}` | H2 | `com.h2database:h2:{version}` -| HSQLDB | `org.hsqldb:hsqldb:{version}` +| MongoDB | The JDBC driver is bundled with the dialect mentioned in <> +| Google Spanner | `com.google.cloud:google-cloud-spanner-jdbc:{version}` |=== -Where `{version}` is the latest version of the JDBC driver for your databse. +Where `{version}` is the latest version of the JDBC driver for your database. [[optional-dependencies]] === Optional dependencies @@ -118,6 +119,15 @@ and `com.github.ben-manes.caffeine:jcache` or `org.eclipse:yasson` | <> | `org.hibernate.orm:hibernate-spatial` | <>, for auditing historical data | `org.hibernate.orm:hibernate-envers` +| Community dialects | `org.hibernate.orm:hibernate-community-dialects` +| Third-party dialects +// TODO link to the /dialects/ documentation explaining what third-party dialects are? +| +https://github.com/mongodb/mongo-hibernate/[MongoDB]: `org.mongodb:mongodb-hibernate:{version}` + +https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Spanner]: `com.google.cloud:google-cloud-spanner-hibernate-dialect:{version}` + +Where `{version}` is the version of the third-party dialect compatible with the version of Hibernate ORM you are using. See the dialect's own documentation for more information. The https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix on the Hibernate website] may also be of help. |=== You might also add the Hibernate {enhancer}[bytecode enhancer] to your @@ -289,9 +299,10 @@ The properties you really do need to get started are these three: [IMPORTANT] // .You don't need `hibernate.dialect` anymore! ==== -In Hibernate 6, you don't need to specify `hibernate.dialect`. +Starting with Hibernate 6, you don't need to specify `hibernate.dialect`. The correct Hibernate SQL `Dialect` will be determined for you automatically. -The only reason to specify this property is if you're using a custom user-written `Dialect` class. +// TODO link to the /dialects/ documentation explaining what community and third-party dialects are? +The only reason to specify this property is if you're using a custom user-written or third-party `Dialect` class. Similarly, neither `hibernate.connection.driver_class` nor `jakarta.persistence.jdbc.driver` is needed when working with one of the supported databases. ==== diff --git a/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc b/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc index 81a9a507dcdc..72e688dc329b 100644 --- a/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc +++ b/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc @@ -58,6 +58,7 @@ transitive dependencies based on the features being used or not. |hibernate-jcache| Integration with https://jcp.org/en/jsr/detail?id=107$$[JCache], allowing any compliant implementation as a second-level cache provider |hibernate-graalvm| Experimental extension to make it easier to compile applications as a https://www.graalvm.org/[GraalVM] native image |hibernate-micrometer| Integration with https://micrometer.io[Micrometer] metrics +// TODO link to the /dialects/ documentation explaining what community dialects are? |hibernate-community-dialects| Additional community-supported SQL dialects |=== @@ -67,6 +68,26 @@ transitive dependencies based on the features being used or not. |hibernate-testing| A series of JUnit extensions for testing Hibernate ORM functionality |=== +[cols="40m,~"] +.Third-party modules +|=== +// Yes, this is a full row containing asciidoc containing an admonition. I don't know have a better idea to add an admonition between a table's title and its content. +2+a| +[NOTE] +==== +Third-party modules are tested by their own authors, +and may not be compatible with all versions of Hibernate ORM. + +1. Check the module's own documentation to know more about its compatibility constraints. +The https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix on the Hibernate website] may also be of help. +2. Submit any question or bug reports about these dialects to the dialect's authors: the Hibernate team cannot help. + +// TODO link to the /dialects/ documentation explaining what third-party dialects are? +==== +|`org.mongodb:mongodb-hibernate:{version}`| https://github.com/mongodb/mongo-hibernate/[MongoDB Extension for Hibernate ORM] +|`com.google.cloud:google-cloud-spanner-hibernate-dialect:{version}`| https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Cloud Spanner Dialect for Hibernate ORM] +|=== + [[platform]] === Platform / BOM diff --git a/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc b/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc index b8fafb17eb7e..68501ef7bb8c 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc @@ -292,5 +292,8 @@ Hibernate abstracts over variations between dialects of SQL via the class `org.h - There's a subclass of `Dialect` for each supported relational database in the package `org.hibernate.dialect`. - Additional community-supported ``Dialect``s are available in the separate module `hibernate-community-dialects`. -In Hibernate 6, it's no longer necessary to explicitly specify a dialect using the configuration property `hibernate.dialect`, and so setting that property is now discouraged. -(An exception is the case of custom user-written ``Dialect``s.) \ No newline at end of file +Starting with Hibernate 6, it's no longer necessary to explicitly specify a dialect using the configuration property `hibernate.dialect`, and so setting that property is now discouraged. +(An exception is the case of custom user-written ``Dialect``s.) + +// TODO link to the /dialects/ documentation +// NOTE: For information about available dialects and compatible database versions, see << .... >>. \ No newline at end of file diff --git a/documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc b/documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc index 21feacb3964d..9136b868d593 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc @@ -14,8 +14,12 @@ Regardless of the exact scenario, the basic idea is that you want Hibernate to h The first line of portability for Hibernate is the dialect, which is a specialization of the `org.hibernate.dialect.Dialect` contract. A dialect encapsulates all the differences in how Hibernate must communicate with a particular database to accomplish some task like getting a sequence value or structuring a SELECT query. +// TODO link to the /dialects/ documentation Hibernate bundles a wide range of dialects for many of the most popular databases. -If you find that your particular database is not among them, it is not terribly difficult to write your own. +If you find that your particular database is not among them, +// TODO link to the /dialects/ documentation, "third-party" section +you can check dialects implemented by third parties, +and as a last resort it is not terribly difficult to write your own. [[portability-dialectresolver]] === Dialect resolution