Skip to content

Commit 7dca07a

Browse files
yrodiereyrodiere
committed
HHH-19869 Regroup all dialect information under a single guide
1 parent ef36b12 commit 7dca07a

File tree

7 files changed

+112
-128
lines changed

7 files changed

+112
-128
lines changed

‎dialects.adoc‎

Lines changed: 3 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,6 @@
11
= Dialects
2-
:toc2:
3-
:toclevels: 1
4-
:sectanchors:
52

6-
A dialect is a class that provides information about the specifics of a database and translators for the SQL dialect of the database.
3+
The content of this file has moved to link:./documentation/src/main/asciidoc/dialect/index.adoc.
4+
Going forward, it will be published in rendered form at https://docs.hibernate.org/stable/orm/dialect/.
75

8-
== Supported dialects
9-
10-
Hibernate supports a wide range of dialects out of the box. The following is list of officially supported databases:
11-
12-
* Apache Derby
13-
* Cockroach
14-
* Google Spanner
15-
* H2
16-
* HSQLDB
17-
* IBM DB2 LUW
18-
* IBM DB2 iSeries
19-
* IBM DB2 z/OS
20-
* MariaDB
21-
* MySQL
22-
* Oracle
23-
* PostgreSQL
24-
* Postgres Plus
25-
* SAP HANA
26-
* SQL Server
27-
* Sybase ASE
28-
29-
Usually, Hibernate supports at least the database version that is also still supported by the respective vendor.
30-
In many cases though, Hibernate supports even older versions of the databases,
31-
but the support for these versions is not guaranteed.
32-
33-
Apart from the Hibernate team supported dialects, there are also community dialects.
34-
35-
== Community dialects
36-
37-
As of Hibernate 6.0, the Hibernate team decided to provide a clear way forward for community contributed dialects.
38-
The `hibernate-core` artifact had many legacy dialects before 6.0 that were only tested and maintained on a best effort basis.
39-
40-
More and more database vendors requested to integrate a dialect for their database and even provided a PR with a dialect,
41-
but the Hibernate team didn't want to add new dialects for databases that might not have a wide adoption
42-
or any automated testing into the `hibernate-core` artifact. Even though the dialect was supposedly maintained by the vendor,
43-
the Hibernate team was burdened with reviewing questions, issues and PRs that relate to these dialects.
44-
45-
To give database vendors and the community a clear way forward, the Hibernate team decided to introduce a new artifact,
46-
called `hibernate-community-dialects` which is the new home for dialects that are maintained by vendors or individuals.
47-
Starting with Hibernate 6.0 the `hibernate-core` artifact will only contain dialects that are supported and tested by the Hibernate team.
48-
All the legacy dialects are moved to the `hibernate-community-dialects` artifact to have a clear separation based on the quality of the dialect.
49-
50-
Issues with dialects in the `hibernate-community-dialects` are usually not considered by the Hibernate team,
51-
as the community is responsible for providing fixes and improving the dialects for newer database versions or ORM capabilities.
52-
53-
== Requirements for moving to hibernate-core
54-
55-
If a database vendor wants their database dialect to be included in the `hibernate-core` artifact,
56-
several requirements have to be fulfilled:
57-
58-
* The vendor must provide access to a dedicated database server that can be used for testing
59-
* The vendor must provide contact details to at least one employee who is mainly responsible for the maintenance of the dialect
60-
* The responsible employee of the vendor must actively monitor and react to failures of the testsuite against the respective database
61-
* The responsible employee of the vendor must ensure the testsuite is configured correctly in order for it to succeed on the respective database
62-
* If the responsible employee of the vendor leaves the company, the vendor must provide contact details to a new responsible employee
63-
64-
In case the responsible employee is unreachable for a longer period or issues with the dialect are not attended to in a timely manner,
65-
the Hibernate team will move the dialect back to the `hibernate-community-dialects` artifact.
66-
67-
The requirements for the database server are:
68-
69-
* JDK 8 installed through e.g. `sudo yum install -y java-1.8.0-openjdk-devel`
70-
* JDK 11 installed through e.g. `sudo yum install -y java-11-openjdk-devel`
71-
* Git installed through e.g. `sudo yum install -y git`
72-
* Access to the database through non-confidential credentials
73-
* Access via SSH through confidential credentials
74-
75-
Get in touch with the Hibernate team on https://hibernate.zulipchat.com/#narrow/stream/132096-hibernate-user[Zulip]
76-
if you want to request the move of your dialect to hibernate-core.
6+
If you ended up here following a link, please ask whoever published that link to update it.

‎documentation/documentation.gradle‎

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -728,7 +728,7 @@ def renderUserGuideHtmlTask = tasks.register( 'renderUserGuideHtml', Asciidoctor
728728
inputs.property "hibernate-version", hibernateVersion
729729
inputs.file( generateSettingsDocTask.get().outputFile )
730730

731-
dependsOn generateSettingsDocTask, generateDialectTableReport
731+
dependsOn generateSettingsDocTask
732732

733733
sourceDir = file( 'src/main/asciidoc/userguide' )
734734
sources {
@@ -881,44 +881,44 @@ def renderMigrationGuideTask = tasks.register( "renderMigrationGuide", Asciidoct
881881
}
882882
}
883883

884+
// Dialect Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
884885

885-
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
886-
// ORM Reports
887-
888-
def renderLoggingReportTask = tasks.register( 'renderLoggingReport', AsciidoctorTask ) { task ->
889-
task.group = "hibernate-reports"
890-
task.description = 'Renders the logging report (generated LoggingReportTask) by in HTML format using Asciidoctor.'
891-
task.dependsOn "generateLoggingReport"
886+
def renderDialectGuideTask = tasks.register( 'renderDialectGuide', AsciidoctorTask ) { task ->
887+
group = "Documentation"
888+
description = 'Renders the Dialect guide in HTML format using Asciidoctor.'
889+
inputs.property "hibernate-version", hibernateVersion
890+
dependsOn generateDialectTableReport
892891

893-
task.inputs.property "version", hibernateVersion
892+
sourceDir = file( 'src/main/asciidoc/dialect' )
893+
sources 'index.adoc'
894+
outputDir = layout.buildDirectory.dir( 'asciidoc/dialect' )
894895

895-
task.sourceDir = layout.buildDirectory.dir( 'orm/generated/logging' )
896-
task.sources 'index.adoc'
896+
attributes 'generated-report-dir': layout.buildDirectory.dir( 'orm/generated' ).get()
897897

898-
task.outputDir = project.layout.buildDirectory.dir( 'asciidoc/logging' )
899-
900-
task.resources {
898+
resources {
901899
from(rootProject.layout.buildDirectory.dir("unpacked-theme").get()
902900
.dir("hibernate-asciidoctor-theme").dir("asciidoc")) {
903901
include 'css/**'
904902
include 'images/**'
905903
include 'script/**'
906904
}
907-
}
905+
}
908906
}
909907

910-
def renderDialectReportTask = tasks.register( 'renderDialectReport', AsciidoctorTask ) { task ->
908+
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
909+
// ORM Reports
910+
911+
def renderLoggingReportTask = tasks.register( 'renderLoggingReport', AsciidoctorTask ) { task ->
911912
task.group = "hibernate-reports"
912-
task.description = 'Renders the supported Dialect report in HTML format using Asciidoctor.'
913-
task.dependsOn "generateDialectReport"
914-
task.dependsOn "generateDialectTableReport"
913+
task.description = 'Renders the logging report (generated LoggingReportTask) by in HTML format using Asciidoctor.'
914+
task.dependsOn "generateLoggingReport"
915915

916916
task.inputs.property "version", hibernateVersion
917917

918-
task.sourceDir = layout.buildDirectory.dir( 'orm/generated/dialect' )
918+
task.sourceDir = layout.buildDirectory.dir( 'orm/generated/logging' )
919919
task.sources 'index.adoc'
920920

921-
task.outputDir = project.layout.buildDirectory.dir( 'asciidoc/dialect' )
921+
task.outputDir = project.layout.buildDirectory.dir( 'asciidoc/logging' )
922922

923923
task.resources {
924924
from(rootProject.layout.buildDirectory.dir("unpacked-theme").get()
@@ -931,7 +931,7 @@ def renderDialectReportTask = tasks.register( 'renderDialectReport', Asciidoctor
931931
}
932932

933933
def generateReportsTask = tasks.named( "generateReports" ) {
934-
dependsOn renderLoggingReportTask, renderDialectReportTask
934+
dependsOn renderLoggingReportTask
935935
}
936936

937937

@@ -950,6 +950,7 @@ def buildDocsTask = tasks.register( 'buildDocs' ) { task ->
950950
task.dependsOn renderRepositoriesTask
951951
task.dependsOn renderIntegrationGuidesTask
952952
task.dependsOn renderTopicalGuidesTask
953+
task.dependsOn renderDialectGuideTask
953954
task.dependsOn generateReportsTask
954955
task.dependsOn renderMigrationGuideTask
955956
task.dependsOn renderWhatsNewTask

‎documentation/src/main/asciidoc/dialect/index.adoc‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
:shared-attributes-dir: {doc-main-dir}/asciidoc/shared
2+
:html-meta-canonical-link: https://docs.hibernate.org/stable/orm/dialect/
3+
4+
include::{shared-attributes-dir}/common-attributes.adoc[]
5+
include::{shared-attributes-dir}/url-attributes.adoc[]
6+
include::{shared-attributes-dir}/filesystem-attributes.adoc[]
7+
include::{shared-attributes-dir}/renderer-attributes.adoc[]
8+
9+
= Dialects
10+
:toc2:
11+
:toclevels: 1
12+
:sectanchors:
13+
14+
A dialect is a class that provides information about the specifics of a database and translators for the SQL dialect of the database.
15+
16+
== Supported dialects
17+
18+
Hibernate ORM supports a wide range of dialects out of the box.
19+
20+
Usually, Hibernate supports at least the database version that is also still supported by the respective vendor.
21+
In many cases though, Hibernate supports even older versions of the databases,
22+
but the support for these versions is not guaranteed.
23+
24+
Below is a list of supported dialects and the minimum required version of the database.
25+
26+
include::{generated-report-dir}/dialect/dialect-table.adoc[]
27+
28+
== Community dialects
29+
30+
Community dialects are not included in `org.hibernate.orm:hibernate-core` and require an additional dependency to `org.hibernate.orm:hibernate-community-dialects`.
31+
32+
These dialects are not directly supported by the Hibernate team:
33+
34+
* The Hibernate ORM CI does not run any test against these dialects.
35+
* The Hibernate team will not address issues reported against these dialect.
36+
37+
Instead, the dialects are maintained on a best-effort basis by vendors or individuals.
38+
39+
// TODO:
40+
// Below is a list of community dialects and the minimum required version of the database.
41+
// include::{generated-report-dir}/dialect/dialect-table-community.adoc[]
42+
43+
[NOTE]
44+
====
45+
Community dialects were introduced in Hibernate ORM 6.0.
46+
47+
The `hibernate-core` artifact had many legacy dialects before 6.0 that were only tested and maintained on a best effort basis.
48+
More and more database vendors requested to integrate a dialect for their database and even provided a PR with a dialect,
49+
but the Hibernate team didn't want to add new dialects for databases that might not have a wide adoption
50+
or any automated testing into the `hibernate-core` artifact. Even though the dialect was supposedly maintained by the vendor,
51+
the Hibernate team was burdened with reviewing questions, issues and PRs that relate to these dialects.
52+
53+
To give database vendors and the community a clear way forward, the Hibernate team decided to introduce a new artifact,
54+
called `hibernate-community-dialects` which is the new home for dialects that are maintained by vendors or individuals.
55+
56+
Moving forward, the `hibernate-core` artifact will only contain dialects that are supported and tested by the Hibernate team.
57+
All the legacy dialects were moved to the `hibernate-community-dialects` artifact to have a clear separation based on the quality of the dialect.
58+
====
59+
60+
== Requirements for moving from `hibernate-community-dialects` to `hibernate-core`
61+
62+
If a database vendor wants their database dialect to be included in the `hibernate-core` artifact,
63+
several requirements have to be fulfilled:
64+
65+
* The vendor must provide access to a dedicated database server that can be used for testing
66+
* The vendor must provide contact details to at least one employee who is mainly responsible for the maintenance of the dialect
67+
* The responsible employee of the vendor must actively monitor and react to failures of the testsuite against the respective database
68+
* The responsible employee of the vendor must ensure the testsuite is configured correctly in order for it to succeed on the respective database
69+
* If the responsible employee of the vendor leaves the company, the vendor must provide contact details to a new responsible employee
70+
71+
In case the responsible employee is unreachable for a longer period or issues with the dialect are not attended to in a timely manner,
72+
the Hibernate team will move the dialect back to the `hibernate-community-dialects` artifact.
73+
74+
The requirements for the database server are:
75+
76+
* JDK 17 installed
77+
* Git installed
78+
* Access to the database through non-confidential credentials
79+
* Access via SSH through confidential credentials
80+
81+
Get in touch with the Hibernate team on https://hibernate.zulipchat.com/#narrow/stream/132096-hibernate-user[Zulip]
82+
if you want to request the move of your dialect to hibernate-core.

‎documentation/src/main/asciidoc/shared/url-attributes.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ include::./common-attributes.adoc[]
1414
:doc-user-guide-url: {doc-version-base-url}/userguide/html_single/Hibernate_User_Guide.html
1515
:doc-javadoc-url: {doc-version-base-url}/javadocs/
1616
:doc-topical-url: {doc-version-base-url}/topical/html_single/
17+
:doc-dialect-url: {doc-version-base-url}/dialect/
1718

1819
:report-deprecation-url: {doc-version-base-url}/deprecated/deprecating.txt
19-
:report-dialect-url: {doc-version-base-url}/dialect/dialect.html
2020
:report-incubating-url: {doc-version-base-url}/incubating/incubating.txt
2121
:report-internals-url: {doc-version-base-url}/internals/internal.txt
2222
:report-logging-url: {doc-version-base-url}/logging/logging.html

‎documentation/src/main/asciidoc/userguide/chapters/compatibility/Compatibility.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ Maven::
7070
[[compatibility-database]]
7171
=== Database
7272

73-
Hibernate {fullVersion} is compatible with the following database versions,
74-
provided you use the corresponding <<database-dialect,dialects>>:
73+
Hibernate {fullVersion}'s compatibility with a given database and version
74+
depends on the dialect being used.
7575

76-
include::{generated-report-dir}/dialect/dialect-table.adoc[]
76+
Refer to the link:{doc-dialect-url}[Dialects] guide for details about both dialects and supported databases.

‎local-build-plugins/src/main/java/org/hibernate/orm/post/DialectReportTask.java‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,11 @@
2020
import org.gradle.api.file.RegularFile;
2121
import org.gradle.api.provider.Property;
2222
import org.gradle.api.provider.Provider;
23-
import org.gradle.api.tasks.Input;
2423
import org.gradle.api.tasks.OutputFile;
2524
import org.gradle.api.tasks.SourceSet;
2625
import org.gradle.api.tasks.SourceSetContainer;
2726
import org.gradle.api.tasks.TaskAction;
2827

29-
import org.hibernate.build.HibernateVersion;
30-
import org.hibernate.build.OrmBuildDetails;
31-
3228
import org.jboss.jandex.ClassInfo;
3329
import org.jboss.jandex.Index;
3430

@@ -39,25 +35,17 @@
3935
*/
4036
public abstract class DialectReportTask extends AbstractJandexAwareTask {
4137
private final Property<RegularFile> reportFile;
42-
private final Property<Boolean> generateHeading;
4338

4439
public DialectReportTask() {
4540
setDescription( "Generates a report of the supported Dialects" );
4641
reportFile = getProject().getObjects().fileProperty();
47-
reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/generated/dialect/index.adoc" ) );
48-
generateHeading = getProject().getObjects().property( Boolean.class ).convention( true );
4942
}
5043

5144
@OutputFile
5245
public Property<RegularFile> getReportFile() {
5346
return reportFile;
5447
}
5548

56-
@Input
57-
public Property<Boolean> getGenerateHeading() {
58-
return generateHeading;
59-
}
60-
6149
@Override
6250
protected Provider<RegularFile> getTaskReportFileReference() {
6351
return reportFile;
@@ -127,15 +115,6 @@ private void writeDialectReport(
127115

128116
private void writeDialectReportHeader(OutputStreamWriter fileWriter) {
129117
try {
130-
if ( this.generateHeading.get() ) {
131-
fileWriter.write( "= Supported Dialects\n\n" );
132-
fileWriter.write(
133-
"Supported Dialects along with the minimum supported version of the underlying database.\n\n\n" );
134-
135-
HibernateVersion ormVersion = getProject().getExtensions().getByType( OrmBuildDetails.class ).getHibernateVersion();
136-
fileWriter.write( "NOTE: Hibernate version " + ormVersion.getFamily() + "\n\n" );
137-
}
138-
139118
fileWriter.write( "[cols=\"a,a\", options=\"header\"]\n" );
140119
fileWriter.write( "|===\n" );
141120
fileWriter.write( "|Dialect |Minimum Database Version\n" );

‎local-build-plugins/src/main/java/org/hibernate/orm/post/ReportGenerationPlugin.java‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -55,18 +55,11 @@ public void apply(Project project) {
5555
(task) -> task.dependsOn( indexerTask )
5656
);
5757

58-
final TaskProvider<DialectReportTask> dialectTask = project.getTasks().register(
59-
"generateDialectReport",
60-
DialectReportTask.class,
61-
(task) -> task.dependsOn( indexerTask )
62-
);
63-
6458
final TaskProvider<DialectReportTask> dialectTableTask = project.getTasks().register(
6559
"generateDialectTableReport",
6660
DialectReportTask.class,
6761
(task) -> {
6862
task.dependsOn( indexerTask );
69-
task.setProperty( "generateHeading", false );
7063
task.setProperty( "reportFile", project.getLayout().getBuildDirectory().file( "orm/generated/dialect/dialect-table.adoc" ) );
7164
}
7265
);
@@ -78,7 +71,6 @@ public void apply(Project project) {
7871
groupingTask.dependsOn( deprecationTask );
7972
groupingTask.dependsOn( internalsTask );
8073
groupingTask.dependsOn( loggingTask );
81-
groupingTask.dependsOn( dialectTask );
8274
groupingTask.dependsOn( dialectTableTask );
8375
}
8476
}

0 commit comments

Comments
 (0)