Driver: Improve section about Java

[amotl]

About

• What the title says.
• Add information about Hibernate (JPA/Panache/Quarkus) and jOOQ.
• Provide minimal executable examples for JDBC.
• Refurbish landing page.

Preview

https://cratedb-guide--402.org.readthedocs.build/connect/java/

/cc @zolbatar, @kneth, @surister

[coderabbitai]

Walkthrough

Removes the legacy consolidated Java JDBC page, adds a reorganized Java connect section with multiple new pages (separate PostgreSQL and CrateDB JDBC guides, jOOQ, Hibernate/JPA, testing, and a JDBC example), updates connect navigation to java/index, and extends shared link and logo includes.

Changes

Cohort / File(s)	Summary
Shared includes (links & logos) docs/_include/links.md, docs/_include/logos.md	Adds public link entries for Hibernate (https://hibernate.org/), jOOQ (https://www.jooq.org/), and JPA (https://en.wikipedia.org/wiki/Jakarta_Persistence), and introduces logo reference links (Hibernate, jOOQ, JUnit, PostgreSQL) with markdownlint directives.
Removed legacy Java page docs/connect/java.md	Deletes the consolidated Java JDBC documentation file.
New Java connect pages docs/connect/java/index.md, docs/connect/java/cratedb-jdbc.md, docs/connect/java/postgresql-jdbc.md, docs/connect/java/jooq.md, docs/connect/java/hibernate.md, docs/connect/java/testing.md, docs/connect/java/_jdbc_example.md	Adds a Java index and separate pages covering driver selection, CrateDB JDBC usage, PostgreSQL JDBC usage, jOOQ, Hibernate/JPA (Quarkus Panache mention), testing pointers, and a JDBC example card linking to a demo repository.
Navigation update docs/connect/index.md	Updates Drivers-by-language to reference java/index instead of the old java entry to point to the new Java index page.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–30 minutes

Possibly related PRs

• Java: Modernize page #385 — Refactors/replaces the old docs/connect/java.md into multiple Java pages (strong overlap with this split-and-add change).
• Connect: Reorganize and clean up section #361 — Updates connect navigation and shared includes; overlaps with docs/connect/index.md edits.
• Navigation: Relocate reference links in learning path sections #379 — Edits docs/_include/links.md to add external link entries (overlapping changes to shared links).

Suggested reviewers

• kneth
• seut
• surister

Poem

I hop through docs and plant new seeds,
Hibernate, jOOQ, and JPA — my deeds.
Java pages split, examples in a row,
JDBC carrots for devs to sow.
A rabbit's cheer — the docs now grow! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title references improving the Java driver documentation section, which aligns with the PR’s main objective to enhance the Java section of the driver guides by adding Hibernate, jOOQ, and JDBC examples. Although it is slightly generic, it accurately reflects the primary change.
Description Check	✅ Passed	The description clearly outlines the changes to be made in the pull request, including adding Hibernate and jOOQ information, providing executable JDBC examples, and refurbishing the landing page, all of which directly relate to the modifications in the Java driver documentation.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch java-more

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5e4c848 and 9470483.

📒 Files selected for processing (1)

• docs/connect/java/index.md (1 hunks)

🧰 Additional context used

🧠 Learnings (3)

📚 Learning: 2025-09-25T19:31:54.320Z

Learnt from: bmunkholm
PR: crate/cratedb-guide#340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Applied to files:

• docs/connect/java/index.md

📚 Learning: 2025-10-08T01:34:18.867Z

Learnt from: amotl
PR: crate/cratedb-guide#385
File: docs/connect/java.md:48-51
Timestamp: 2025-10-08T01:34:18.867Z
Learning: CrateDB JDBC driver uses the `jdbc:crate://` protocol scheme but communicates via the PostgreSQL wire protocol on port 5432, just like the PostgreSQL JDBC driver (`jdbc:postgresql://`). Do not confuse the `jdbc:crate://` scheme with other protocol schemes like `crate://` (used by SQLAlchemy dialect for CrateDB) or assume it uses the HTTP endpoint on port 4200.

Applied to files:

• docs/connect/java/index.md

📚 Learning: 2025-08-05T07:14:57.416Z

Learnt from: hammerhead
PR: crate/cratedb-guide#221
File: docs/connect/configure.md:58-66
Timestamp: 2025-08-05T07:14:57.416Z
Learning: In CrateDB connection strings, the user:password@ syntax is valid for HTTP Basic authentication on port 4200, but PostgreSQL JDBC drivers do not support this format and require credentials as query parameters (?user=<user>&password=<password>) instead.

Applied to files:

• docs/connect/java/index.md

🪛 LanguageTool

docs/connect/java/index.md

[style] ~74-~74: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 2173 characters long)
Context: ...OOQ example. :::: ::::{grid-item-card} ![JUnit logo][JUnit logo]{height=40px} &n...

(EN_EXCESSIVE_EXCLAMATION)

🪛 markdownlint-cli2 (0.18.1)

docs/connect/java/index.md

46-46: Reference links and images should use a label that is defined
Missing link or image reference definition: "postgresql logo"

(MD052, reference-links-images)

---

53-53: Reference links and images should use a label that is defined
Missing link or image reference definition: "cratedb logo"

(MD052, reference-links-images)

---

60-60: Reference links and images should use a label that is defined
Missing link or image reference definition: "hibernate logo"

(MD052, reference-links-images)

---

67-67: Reference links and images should use a label that is defined
Missing link or image reference definition: "jooq logo"

(MD052, reference-links-images)

---

74-74: Reference links and images should use a label that is defined
Missing link or image reference definition: "junit logo"

(MD052, reference-links-images)

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Provide the promised HTTP example instead of a TODO block.

Line 86 promises “Below is a quick example using Apache Commons HTTP,” but the section only contains a todo directive. Readers will either see an empty promise or the literal TODO, which undercuts the usefulness of this page. Please add the example (or remove the teaser sentence until the example is ready) before merging.

[amotl]

Ack. If we can't add an example before review, we will remove the section before merging.

[seut]

Thx, left some suggestions.

[seut]

crate-jdbc requires >= 11 (https://github.com/crate/crate-jdbc/blob/master/build.gradle#L19). Also the given command does not required JEP 330 afaik.

Suggested change

	Invoke program. Needs Java >= 25 ([JEP 330]).
	Invoke program. Needs Java >= 11.

[seut]

Suggested change

	Prefer the PostgreSQL JDBC driver first—it’s often already on your classpath
	Prefer the PostgreSQL JDBC driver first, it’s often already on your classpath

[matriv]

also:

Suggested change

	Prefer the PostgreSQL JDBC driver first—it’s often already on your classpath
	Prefer the PostgreSQL JDBC driver first—it’s often already in your classpath

[seut]

PostgreSQL-JDBC works with Java >= 1.8, and the given command does not need JEP 330 afaik.

Suggested change

	Invoke program. Needs Java >= 25 ([JEP 330]).
	Invoke program. Needs Java >= 1.8.

[matriv]

Thx, Don't have more comments myself.