From fbee828c3d8cf136996fe48e8000b6ede9e2af51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Wed, 15 Oct 2025 19:08:24 +0200 Subject: [PATCH] Mention third-party dialects throughout the documentation --- .../src/main/asciidoc/dialect/index.adoc | 27 +++++++++++++++++++ .../asciidoc/introduction/Configuration.adoc | 11 +++++++- .../asciidoc/quickstart/guides/obtaining.adoc | 19 +++++++++++++ .../chapters/jdbc/Database_Access.adoc | 2 +- .../chapters/portability/Portability.adoc | 4 ++- 5 files changed, 60 insertions(+), 3 deletions(-) diff --git a/documentation/src/main/asciidoc/dialect/index.adoc b/documentation/src/main/asciidoc/dialect/index.adoc index 896542cadf69..0881f667ef2e 100644 --- a/documentation/src/main/asciidoc/dialect/index.adoc +++ b/documentation/src/main/asciidoc/dialect/index.adoc @@ -25,6 +25,33 @@ Below is a list of supported dialects and the minimum required version of the da include::{generated-report-dir}/dialect/dialect-table.adoc[] +[[third-party-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. + +These dialects are not directly supported by the Hibernate team: + +* The Hibernate ORM CI does not run any test against these dialects, the dialect's authors have their own test suite. +* The Hibernate team will not address issues reported against these dialect, but the dialect's authors have their own issue tracker. + +[NOTE] +==== +Third-party dialects may not be compatible with all versions of Hibernate ORM. + +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. +==== + +Below is a list of third-party dialects with links to relevant websites. + +[cols="a,a", options="header"] +|=== +|Dialect |Website +|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] +|=== + [[community-dialects]] == Community dialects diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index ce44868401aa..26af305533cd 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/documentation/src/main/asciidoc/introduction/Configuration.adoc @@ -72,6 +72,8 @@ driver for your database. | Oracle | `com.oracle.database.jdbc:ojdbc17:{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 database. @@ -122,6 +124,13 @@ or `org.eclipse:yasson` | <>, for monitoring via Java Flight Recorder | `org.hibernate.orm:hibernate-jfr` | Hibernate Jandex integration, for <> | `org.hibernate.orm:hibernate-scan-jandex` | link:{doc-dialect-url}#community-dialects[Community dialects] | `org.hibernate.orm:hibernate-community-dialects` +| link:{doc-dialect-url}#third-party-dialects[Third-party dialects] +| +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 @@ -345,7 +354,7 @@ The properties you really do need to get started are these three: ==== Since 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. +The only reason to specify this property is if you're using a custom user-written or link:{doc-dialect-url}#third-party-dialects[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 0d7ad1793c40..4892aebec2e6 100644 --- a/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc +++ b/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc @@ -64,6 +64,25 @@ 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, and in particular link:{doc-dialect-url}#third-party-dialects[third-party dialects], 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. + +==== +|`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 25b505143493..772f3cdc8844 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc @@ -206,6 +206,6 @@ Hibernate abstracts over variations between dialects of SQL via the class `org.h - Additional community-supported ``Dialect``s are available in the separate module `hibernate-community-dialects`. 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.) +An exception is the case of custom or link:{doc-dialect-url}#third-party-dialects[third-party] ``Dialect``s. NOTE: For information about available dialects and compatible database versions, see the link:{doc-dialect-url}[dialect guide]. \ 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 07ba060c16b4..f83352d0e858 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc @@ -16,7 +16,9 @@ The first line of portability for Hibernate is the dialect, which is a specializ 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. Hibernate bundles a wide range of dialects for many of the most popular databases: see the link:{doc-dialect-url}[dialect guide] for details. -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, +you can check link:{doc-dialect-url}#third-party-dialects[dialects implemented by third parties], +and as a last resort it is not terribly difficult to write your own. [[portability-dialectresolver]] === Dialect resolution