Skip to content

Commit a99d37c

Browse files
yrodiereyrodiere
committed
HHH-19869 Regroup all dialect information under a single guide
1 parent c2adaaf commit a99d37c

File tree

7 files changed

+115
-130
lines changed

7 files changed

+115
-130
lines changed

‎dialects.adoc‎

Lines changed: 3 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,6 @@
11
= Dialects
22

3-
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/.
45

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

695-
dependsOn generateSettingsDocTask, generateDialectTableReport
695+
dependsOn generateSettingsDocTask
696696

697697
sourceDir = file( 'src/main/asciidoc/userguide' )
698698
sources {
@@ -807,6 +807,30 @@ def renderMigrationGuideTask = tasks.register( "renderMigrationGuide", Asciidoct
807807
}
808808
}
809809

810+
// Dialect Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
811+
812+
def renderDialectGuideTask = tasks.register( 'renderDialectGuide', AsciidoctorTask ) { task ->
813+
group = "Documentation"
814+
description = 'Renders the Dialect guide in HTML format using Asciidoctor.'
815+
inputs.property "hibernate-version", project.ormVersion
816+
dependsOn generateDialectTableReport
817+
818+
sourceDir = file( 'src/main/asciidoc/dialect' )
819+
sources 'dialect.adoc'
820+
outputDir = layout.buildDirectory.dir( 'asciidoc/dialect' )
821+
822+
attributes linkcss: true, stylesheet: "css/hibernate.css",
823+
'generated-report-dir': layout.buildDirectory.dir( 'orm/generated' ).get()
824+
825+
task.resources {
826+
from( 'src/main/style/asciidoctor' ) {
827+
include 'images/**'
828+
}
829+
from( 'src/main/style/asciidoctor' ) {
830+
include 'css/**'
831+
}
832+
}
833+
}
810834

811835
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
812836
// ORM Reports
@@ -836,34 +860,8 @@ def renderLoggingReportTask = tasks.register( 'renderLoggingReport', Asciidoctor
836860
}
837861
}
838862

839-
def renderDialectReportTask = tasks.register( 'renderDialectReport', AsciidoctorTask ) { task ->
840-
task.group = "hibernate-reports"
841-
task.description = 'Renders the supported Dialect report in HTML format using Asciidoctor.'
842-
task.dependsOn "generateDialectReport"
843-
task.dependsOn "generateDialectTableReport"
844-
845-
task.inputs.property "version", project.ormVersion
846-
847-
task.sourceDir = layout.buildDirectory.dir( 'orm/generated/dialect' )
848-
task.sources 'dialect.adoc'
849-
850-
task.outputDir = project.layout.buildDirectory.dir( 'asciidoc/dialect' )
851-
852-
task.attributes linkcss: true,
853-
stylesheet: "css/hibernate.css"
854-
855-
task.resources {
856-
from( 'src/main/style/asciidoctor' ) {
857-
include 'images/**'
858-
}
859-
from( 'src/main/style/asciidoctor' ) {
860-
include 'css/**'
861-
}
862-
}
863-
}
864-
865863
def generateReportsTask = tasks.named( "generateReports" ) {
866-
dependsOn renderLoggingReportTask, renderDialectReportTask
864+
dependsOn renderLoggingReportTask
867865
}
868866

869867

@@ -882,6 +880,7 @@ def buildDocsTask = tasks.register( 'buildDocs' ) { task ->
882880
task.dependsOn renderRepositoriesTask
883881
task.dependsOn renderIntegrationGuidesTask
884882
task.dependsOn renderTopicalGuidesTask
883+
task.dependsOn renderDialectGuideTask
885884
task.dependsOn generateReportsTask
886885
task.dependsOn renderMigrationGuideTask
887886
}

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

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

1920
:report-deprecation-url: {doc-version-base-url}/deprecated/deprecating.txt
20-
:report-dialect-url: {doc-version-base-url}/dialect/dialect.html
2121
:report-incubating-url: {doc-version-base-url}/incubating/incubating.txt
2222
:report-internals-url: {doc-version-base-url}/internals/internal.txt
2323
: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 & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,11 @@
2222
import org.gradle.api.file.RegularFile;
2323
import org.gradle.api.provider.Property;
2424
import org.gradle.api.provider.Provider;
25-
import org.gradle.api.tasks.Input;
2625
import org.gradle.api.tasks.OutputFile;
2726
import org.gradle.api.tasks.SourceSet;
2827
import org.gradle.api.tasks.SourceSetContainer;
2928
import org.gradle.api.tasks.TaskAction;
3029

31-
import org.hibernate.orm.env.HibernateVersion;
32-
3330
import org.jboss.jandex.ClassInfo;
3431
import org.jboss.jandex.Index;
3532

@@ -40,25 +37,17 @@
4037
*/
4138
public abstract class DialectReportTask extends AbstractJandexAwareTask {
4239
private final Property<RegularFile> reportFile;
43-
private final Property<Boolean> generateHeading;
4440

4541
public DialectReportTask() {
4642
setDescription( "Generates a report of the supported Dialects" );
4743
reportFile = getProject().getObjects().fileProperty();
48-
reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/generated/dialect/dialect.adoc" ) );
49-
generateHeading = getProject().getObjects().property( Boolean.class ).convention( true );
5044
}
5145

5246
@OutputFile
5347
public Property<RegularFile> getReportFile() {
5448
return reportFile;
5549
}
5650

57-
@Input
58-
public Property<Boolean> getGenerateHeading() {
59-
return generateHeading;
60-
}
61-
6251
@Override
6352
protected Provider<RegularFile> getTaskReportFileReference() {
6453
return reportFile;
@@ -128,15 +117,6 @@ private void writeDialectReport(
128117

129118
private void writeDialectReportHeader(OutputStreamWriter fileWriter) {
130119
try {
131-
if ( this.generateHeading.get() ) {
132-
fileWriter.write( "= Supported Dialects\n\n" );
133-
fileWriter.write(
134-
"Supported Dialects along with the minimum supported version of the underlying database.\n\n\n" );
135-
136-
HibernateVersion ormVersion = (HibernateVersion) getProject().getRootProject().getExtensions().getByName( "ormVersion" );
137-
fileWriter.write( "NOTE: Hibernate version " + ormVersion.getFamily() + "\n\n" );
138-
}
139-
140120
fileWriter.write( "[cols=\"a,a\", options=\"header\"]\n" );
141121
fileWriter.write( "|===\n" );
142122
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
@@ -57,18 +57,11 @@ public void apply(Project project) {
5757
(task) -> task.dependsOn( indexerTask )
5858
);
5959

60-
final TaskProvider<DialectReportTask> dialectTask = project.getTasks().register(
61-
"generateDialectReport",
62-
DialectReportTask.class,
63-
(task) -> task.dependsOn( indexerTask )
64-
);
65-
6660
final TaskProvider<DialectReportTask> dialectTableTask = project.getTasks().register(
6761
"generateDialectTableReport",
6862
DialectReportTask.class,
6963
(task) -> {
7064
task.dependsOn( indexerTask );
71-
task.setProperty( "generateHeading", false );
7265
task.setProperty( "reportFile", project.getLayout().getBuildDirectory().file( "orm/generated/dialect/dialect-table.adoc" ) );
7366
}
7467
);
@@ -80,7 +73,6 @@ public void apply(Project project) {
8073
groupingTask.dependsOn( deprecationTask );
8174
groupingTask.dependsOn( internalsTask );
8275
groupingTask.dependsOn( loggingTask );
83-
groupingTask.dependsOn( dialectTask );
8476
groupingTask.dependsOn( dialectTableTask );
8577
}
8678
}

0 commit comments

Comments
 (0)