Skip to content

Commit aed2967

Browse files
pchapman-nuodbpchapman-nuodb
committed
Updated REAdME files
1 parent 247e7ab commit aed2967

File tree

2 files changed

+323
-1
lines changed

2 files changed

+323
-1
lines changed

‎README-NUODB.adoc‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
image::https://static.jboss.org/hibernate/images/hibernate_logo_whitebkg_200px.png[]
2+
3+
:jarversion: 23.1.0-hib6
4+
:bslash: \
5+
6+
= Hibernate and NuoDB     image:https://d33wubrfki0l68.cloudfront.net/571989f106f60bced5326825bd63918a55bdf0aa/dd52a/_/img/nuodb-bird-only-green.png[width=60]
7+
8+
== 6.6 Branch
9+
10+
This is a fork of Hibernate ORM (http://github.com/hibernate/hibernate-orm).
11+
We have modified branches 6.1, 6.2 and 6.6 to allow testing of NuoDB's Hibernate 6 dialect.
12+
The tests of interest are the profile tests in hibernate-core sub-project (which allow testing against multiple databases).
13+
Unfortunately the section on Matrix testing (in the original README) is yet to be written (since at least 2019) and presumably never will be.
14+
Hence we use _profiles_.
15+
16+
IMPORTANT: If the NuoDB Hibernate JAR version changes, edit this README and change `:jarversion:` at the top.
17+
18+
== Running Tests
19+
20+
To run the tests for NuoDB:
21+
22+
. Checkout branch 6.1, 6.2 or 6.6 as needed.
23+
24+
. Windows users are recommended to use `git bash` or WSL rather than `CMD` or _PowerShell_.
25+
26+
. You must have Java JDK 11, 17 or 21 installed. Java 8 isn't supported by Hibernate 6.x, it requires Java 11 or later.
27+
28+
* _Option 1:_ Install `jenv` from https://github.com/jenv/jenv to manage your JVMs.
29+
** You may need to tell it which JDKs (if any) you already have installed.
30+
** There is a `.java-version` file in this project, telling `jenv` to use Java 11.
31+
** If necessary, use `jenv` to switch to Java 11.
32+
For example, to use 11.0.26, run `jenv local 11.0.26`.
33+
* _Option 2:_ use `sdkman`: https://sdkman.io
34+
** `skdman` requires `git bash` or WSL on Windows.
35+
** To set the same java version: `sdk use java 11.0.26`
36+
37+
. Next, make sure you have our Hibernate 6 dialect jar available:
38+
39+
* Clone https://github.com/nuodb/HibernateDialect6
40+
* Checkout the branch to match the branch of this project that you are using.
41+
** 6.1 and 6.2 require _HibernateDialect6_ branch `hib-6.2`
42+
** 6.6 requires _HibernateDialect6_ branch `hib-6.6`
43+
* Run `mvn -Dgpg.skip install` - see https://github.com/nuodb/HibernateDialect6#readme[project README].
44+
* Check the version in the POM - it will be of the form `nuodb-hibernate.NN.x.x-hib6`
45+
* You will need to set `DIALECT_VERSION` to `NN.x.x-hib6` to match - see below.
46+
47+
. This project's gradle build file assumes you have your maven repository in
48+
the default location (`.m2` in your home directory).
49+
If so, skip this step.
50+
51+
* Otherwise you must tell gradle where this dependency can be found.
52+
For example, suppose you use `m2` instead of `.m2`:
53+
+
54+
[source%autofit,sh,subs="verbatim,attributes"]
55+
----
56+
# Linux/MacOS
57+
export ADDITIONAL_REPO=~/m2/repository/com/nuodb/hibernate/nuodb-hibernate/{jarversion}
58+
59+
# Windows
60+
set ADDITIONAL_REPO=c:\Users\<your-login>\.m2\repository\com\nuodb\hibernate\nuodb-hibernate{bslash}{jarversion}
61+
----
62+
63+
[start=6]
64+
. Set the Hibernate dialect - this must match the Hibernate 6 dialect you installed earlier.
65+
66+
* **Note:** the value you set _should_ have `-hib6` in the end, but that's optional:
67+
+
68+
[source%autofit,sh,subs="verbatim,attributes"]
69+
----
70+
export DIALECT_VERSION={jarversion} (Linux/MacOS)
71+
set DIALECT_VERSION={jarversion} (Windows)
72+
----
73+
74+
* Alternatively, MacOS and Linux users may prepend it to any command:
75+
** `DIALECT_VERSION={jarversion} ./gradlew ...`
76+
77+
. You _must_ be running at _least_ NuoDB V5.1.2 because tests that used to fail now pass due to enhancements in NuoDB SQL.
78+
79+
. You need a database called `hibernate_orm_test` running locally on your machine with username and password also `hibernate_orm_test`.
80+
If you do not have NuoDB installed locally, here are some options using Docker:
81+
82+
* To use `docker compose`:
83+
** clone http://github.com/nuodb/nuodb-compose and (per the README):
84+
** `cd nuodb` and copy `env_default` to `.env`.
85+
** Edit `.env` and set `DB_NAME`, `DB_USER` and `DB_PASSWORD` to `hibernate_orm_test`.
86+
** Also (last line) uncomment and set `EXTERNAL_ADDRESS=127.0.0.1`.
87+
** Run: `docker compose -p hib -f monolith.yaml up -d`
88+
** Run: `docker exec -it hib-monolith-1 nuocmd show domain`
89+
90+
* Or, setup a local database by running `setup.sh` inside `env` folder.
91+
** This script will create a NuoDB env with an admin service, a Storage Manager (SM) and a Transaction Engine (TE) to run the tests against.
92+
93+
. For information on `gradle` refer to the original `README` content xref:README.adoc#gradle-primer[gradle-primer].
94+
95+
. Some tests, in particular the `ASTParserLoadingTest`, do not clean up properly and leak connections.
96+
To avoid this, use `SET` or `export` to set the environment variable `HIBERNATE_CONNECTION_LEAK_DETECTION` to `TRUE`.
97+
98+
. Running the Tests
99+
100+
* **WARNING:** You _must_ use the `--rerun-tasks` option after the first run, otherwise Gradle may not run any tests at all (it only runs tests it thinks have changed and typically we only change our JAR).
101+
Tests can take 20-40 minutes to run.
102+
103+
* Run the tests using a database _Profile_ (the `-Pdb` option):
104+
** This obeys the exclusions in `hibernate-core.gradle` so a `green-list` is no longer needed (or supported).
105+
106+
** Windows (using `gradlew.bat`):
107+
+
108+
[source%autofit,sh,subs="verbatim,attributes"]
109+
----
110+
set DIALECT_VERSION={jarversion}
111+
gradlew --rerun-tasks -Pdb=nuodb clean hibernate-core:test
112+
----
113+
114+
** MacOS/Linux
115+
+
116+
[source%autofit,sh,subs="verbatim,attributes"]
117+
----
118+
DIALECT_VERSION={jarversion} ./gradlew --rerun-tasks -Pdb=nuodb clean hibernate-core:test
119+
----
120+
121+
* After running tests:
122+
** _14838 tests completed, 0 failed, 2297 skipped_ (NuoDB V6.0.2)
123+
** _15062 tests completed, 0 failed, 2302 skipped_ (NuoDB V7.0.0)
124+
125+
. Full details of all failing and ignored tests can be found at link:hibernate-core/target/reports/tests/test/index.html[].
126+
** This directory is not populated until _after_ the test-run has finished and will be deleted by the next test run (take a copy if necessary).
127+
128+
. To run individual tests, use `--tests <pattern>` on the command line.
129+
* Examples (note the use of quotes when using wildcards):
130+
+
131+
```bash
132+
... hibernate-core:test --tests '*SomeTest.someSpecificFeature'
133+
... hibernate-core:test --tests '*SomeSpecificTest'
134+
... hibernate-core:test --tests 'all.in.specific.package*'
135+
... hibernate-core:test --tests '*IntegTest'
136+
... hibernate-core:test --tests '*IntegTest*ui*'
137+
... hibernate-core:test --tests '*IntegTest.singleMethod'
138+
```
139+
140+
* Note that the old _green-list_ option is not supported by the Hibernate tests from version 6.
141+
142+
* Instead, edit `hibernate-core/hibernate-core.gradle` and find the `test.filter` section.
143+
You can use the same patterns as above.
144+
For example:
145+
+
146+
```groovy
147+
test {
148+
filter {
149+
// ---------------------------------------------------------------------
150+
// Failing tests that need fixing
151+
// ---------------------------------------------------------------------
152+
153+
// Run this test
154+
includeTestsMatching 'org.hibernate.orm.test.hql.ASTParserLoadingTest'
155+
156+
// Don't run any tests from this class
157+
excludeTestsMatching 'org.hibernate.orm.test.type.LocalDateTest.*'
158+
...
159+
}
160+
}
161+
```
162+
** Adding an `includeTestsMatching` will cause gradle to only run the included tests, and overrides any excludes for the same tests
163+
(this is like the old _green-list_).
164+
165+
* Many tests that will never pass, typically due to syntax and features NuoDB does not support, are already listed in this section (the equivalent of a _black-list_).
166+
167+
== Notes and Warnings
168+
169+
* The run will fail with an error (and run no tests) if the required database cannot be connected to.
170+
171+
* These tests are intended for testing Hibernate as well as the underlying database.
172+
Many tests will be skipped if they use features our dialect does not support, and that is normal.
173+
We are just piggybacking on these tests for convenience.
174+
175+
* Many tests fail due to known limitations in NuoDB SQL and are marked for exclusion in (see comments in the file).
176+
177+
* Two connection properties are used:
178+
** `isolation=read_committed` - this is the default for most RDBMs and tests fai using our default.
179+
** `lock-wait-timeout=10` - the default is 30s which slows the tests down.
180+
181+
* Not all tests clean up after themselves.
182+
If using the local database you may need to reset the environment.
183+
** Either by using `docker compose` to destroy the container and then recreate it.
184+
** Or by rerunning the script `env/setup.sh`.
185+
186+
* Test execution takes ~30 mins on average with a live database (depending on the power of your machine).
187+
188+
* When running the matrix tests `hibernate-core/target/matrix/nuodb` is the working directory.
189+
190+
[#using-an-ide]
191+
== Running Tests in an IDE
192+
193+
It is possible to run the tests in IntelliJ (but not currently Eclipse - it fails to load the gradle project).
194+
195+
Open `hibernate-core` as a _gradle_ project in IntelliJ in the usual way.
196+
197+
An IDE is most useful for running individual tests that have failed and debugging them.
198+
199+
* Or use the `--tests` and `includeTestsMatching` options for running a single test.
200+
201+
// == Testing JAR from Sonatype
202+
203+
// This involves pulling the NuoDB Hibernate JAR from Sonatype insted of your local Maven repository.
204+
205+
// WARNING: This not yet implemented.
206+
207+
// * Once our jar is put up at Sonatype, its URL is something like https://oss.sonatype.org/content/repositories/comnuodb-YYYY/com/nuodb/hibernate/nuodb-hibernate/{jarversion}/nuodb-hibernate-{jarversion}.jar.
208+
// ** Note the build number - YYYY (a 4 digit number such as 1050). To use this dependency run as follows:
209+
// +
210+
// ```sh
211+
// SONATYPE_VERSION=YYYY gradle clean ... (Linux)
212+
213+
// set SONATYPE_VERSION=YYYY (Windows)
214+
// gradle clean ...
215+
// ```
216+
217+
== Configure the Database
218+
219+
Modify properties in `databases/nuodb/resources/hibernate.properties` and in `gradle/databases.gradle`.
220+
Make sure they match.
221+
222+
We have added two connection properties to the URL:
223+
224+
* `isolation=read_committed` - this is the default for most other RDBMs and Hibernate assumes it.
225+
Many of the locking tests fail otherwise.
226+
* `lock-wait-timeout=10` - No need to wait for locks and a long timeout slows the run when there are failing tests due to contention (hence defining the `HIBERNATE_CONNECTION_LEAK_DETECTION` property).
227+
228+
229+
// * If using an IDE, you may need to modify `hibernate-core/src/test/resources/hibernate-nuodb.properties` to match;
230+
231+
* _DO NOT_ change the database name or credentials as they are used by our build system.
232+
233+
== Upgrade Hibernate Dialect
234+
235+
If the Hibernate dialect has a new version number:
236+
237+
* Make sure to install it into your local Maven repository
238+
* Simply update the environment variable: `SET DIALECT_VERSION=<new-version>`
239+
240+
The JAR version is required in several places and will pick up the version from the environment variable (therefore no other changes should be necessary).
241+
242+
For the record, our Hibernate jar is referred to in:
243+
244+
* `databases/nuodb/matrix.gradle`
245+
** Contains a "smart" class `NuodbHibernateVersion` which uses `DIALECT_VERSION` and checks the JAR exists.
246+
** If you have just built and installed a new version of the JAR, it should find it - provided `DIALECT_VERSION` is set accordingly.
247+
** If valid, it sets `nuodbHibernateJarVersion` to the value.
248+
249+
* `hibernate-core/hibernate-testing.gradle`
250+
** References `${nuodbHibernateJarVersion}`, no change needed.
251+
252+
== Upgrade NuoDB JDBC Driver
253+
254+
This must be changed manually in `databases/nuodb/matrix.gradle` as there is currently no environment variable for it.JdbcJar
255+
256+
* `databases/nuodb/matrix.gradle`
257+
* As with `nuodbHibernateJarVersion`, the variable `nuodbHibernateJdbcVersion` is set to the version of our JDBC JAR to use.
258+
259+
* `hibernate-core/hibernate-testing.gradle`
260+
** References `${nuodbHibernateJarVersion}`, no change needed.
261+
262+
To check the current version, run:
263+
264+
```sh
265+
grep JDBC databases/nuodb/matrix.gradle
266+
```
267+
268+
== Changes Made to Project
269+
270+
If you need to checkout a new branch for a new version of Hibernate, you will need to make the same changes again.
271+
Hence, we have tried to keep changes to a minimum.
272+
273+
To use NuoDB:
274+
275+
. Added this `README-NUODB.adoc` and a reference to it in `README.adoc`.
276+
277+
. Added `databases/nuodb` to define dependencies and configuration required to use NuoDB.
278+
* Added `jdbcDependency "com.nuodb.jdbc:nuodb-jdbc:<version>"` (normally the only thing in this file).
279+
* Extensive additions to `databases/nuodb/matrix.gradle` (compared to the other databases) to check that our JARs are on the class path and the database is available for testing.
280+
The tests will still run, even if the database is not available - the checks avoid wasting time.
281+
282+
. Modified `build.gradle` in two places to look in the local maven repository (`.m2` in your home directory) for our dialect.
283+
284+
// . Modified `gradle/java-module.gradle` to add `testRuntimeOnly dbLibs.nuodb` with all the other databases listed.
285+
286+
[start=4]
287+
. Modified `gradle/databases.gradle` to add NuoDB and its connection properties to the `dbBundle` array.
288+
The properties must match those in `databases/nuodb/resources/hibernate.properties`.
289+
290+
. Modified `hibernate-testing/hibernate-testing.gradle`:
291+
* To look in the local maven repository for our dialect.
292+
* To add dependencies for our JDBC and Hibernate JARs.
293+
+
294+
This sub-project runs its own tests and `hibernate-core` is dependent on it.
295+
296+
. Modified `hibernate-core/hibernate-core.gradle`:
297+
* To look in the local maven repository for our dialect.
298+
* To filter (exclude) tests that we know do not run.
299+
Mostly this is due to generating syntax or using features NuoDB SQL does not support.
300+
* You can annotate a class with `@SkipTest` to skip it for a given dialect, but this would involve changing far too many classes.
301+
302+
. Copied `BaseUnitTestCase.java` from the `hibernate-testing` project.
303+
* Modified the test timeout rule, reducing it from 30 to 3 mins (otherwise the tests take ages to run when timeout tests are failing).
304+
* It's in `hibernate-core/src/test/java/org/hibernate/testing/junit4`.
305+
306+
. Modified classes that use `Containing`, `String` or `Ver` as class or data-member names (they are reserved words in NuoDB).
307+
* To find them, run
308+
+
309+
```bash
310+
grep -iRl "// NuoDB" hibernate-core/src/test/java/org/hibernate
311+
```
312+
313+
* If you need to change any other files, please mark the change like this so it can be found using `grep`:
314+
+
315+
```java
316+
// NUODB: START ...
317+
...
318+
// NUODB: END
319+
```

‎README.adoc‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
== Hibernate ORM
1+
== Hibernate ORM 7.0
2+
3+
NOTE: This is a fork of the `hibernate-orm` project and we use it to test NuoDB's Hibernate Dialects.
4+
For more information see xref:README-NUODB.adoc[].
25

36
image:https://img.shields.io/maven-central/v/org.hibernate.orm/hibernate-core.svg?label=Maven%20Central&style=for-the-badge[Maven Central,link=https://central.sonatype.com/search?namespace=org.hibernate.orm&sort=name]
47
image:https://img.shields.io/jenkins/build?jobUrl=https%3A%2F%2Fci.hibernate.org%2Fjob%2Fhibernate-orm-pipeline%2Fjob%2Fmain%2F&style=for-the-badge[Build Status,link=https://ci.hibernate.org/job/hibernate-orm-pipeline/job/main/]

0 commit comments

Comments
 (0)