Java/jOOQ: Improve documentation

[amotl]

Hi again,

the documentation improvements for the jOOQ example have been split off from GH-11, and are submitted hereby instead.

There has been another round of edits, and a few of them may have some annotations from my side. On others, you may want to have a second look, or also add some comments or questions.

You can directly view the rendered variants of the documents, it is probably more pleasant to read ¹².

With kind regards,
Andreas.

Footnotes

1. https://github.com/crate/cratedb-examples/blob/amo/jooq/improve-docs/by-language/java-jooq/README.rst ↩

2. https://github.com/crate/cratedb-examples/blob/amo/jooq/improve-docs/by-language/java-jooq/backlog.rst ↩

[amotl]

Do you think this observation should be carried over to the CrateDB repository by creating an issue?

[amotl]

@seut: Coming from #11 (comment), I've added this backlog item.

[amotl]

When thinking about it a second time, it is probably only applicable when connecting to a real database for the code generation step (GH-10).

I think configuring unqualifiedSchema=none confuses a bit as in the examples, no schema is used. I think this works as the testdrive is passed into the connection string as the database parameter which CrateDB then uses as the default schema name. Maybe rather use testdrive here and not inside the connection string and/or use the schema also in the application?

In this scenario, the corresponding setting is probably jooq.configurations.main.generationTool.generator.database.inputSchema, where I configured to use testdrive the other day.

cratedb-examples/by-language/java-jooq/jooq.gradle

Lines 70 to 73 in f88eda5

	database {
	name = 'org.jooq.meta.postgres.PostgresDatabase'
	inputSchema = 'testdrive'
	}

[amotl]

Now also documented at CrateDB/jOOQ backlog » Q & A.

[mkleen]

Minor: Is there any chance we could use a more up-to-date dialect ? Seems like the most recent on is https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/dialect/PostgreSQLDialect.java

[amotl]

As of jOOQ version 3.17.7, it uses org.hibernate.dialect.PostgreSQL94Dialect ¹, and I think there is no way to change that at runtime. I've reflected this detail within the documentation, thanks for asking!

Footnotes

1. See org.jooq.SQLDialect#L1367-L1368 ↩

[amotl]

Now also documented at CrateDB/jOOQ backlog » Q & A.

[mkleen]

Looks good, left a minor comment