Driver: Improve section about Java #402
Conversation
amotl
added
the
cross linking
WalkthroughRemoves the legacy consolidated Java JDBC page, adds a reorganized Java connect section split into multiple new pages (PostgreSQL/CrateDB JDBC, jOOQ, Hibernate/JPA, testing, example), updates connect navigation to Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20–30 minutes Areas to pay extra attention:
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
amotl
changed the title
amotl
changed the title
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
amotl
force-pushed
the
java-more
branch
3 times, most recently
from
494a5ae to
5e4c848
Compare
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
amotl
added
guidance
docs/connect/java/cratedb-jdbc.md
Outdated
| Invoke-WebRequest https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar -OutFile crate-jdbc-standalone-2.7.0.jar | ||
| ``` | ||
| ::: | ||
| Invoke program. Needs Java >= 25 ([JEP 330]). |
There was a problem hiding this comment.
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.
| Invoke program. Needs Java >= 25 ([JEP 330]). | |
| Invoke program. Needs Java >= 11. |
There was a problem hiding this comment.
JEP 330
Hi. We see that JEP 330 landed with Java 11 already, so this comment is certainly misguided; thanks for spotting it.
Apparently, the fourth mode for the Java launcher to launch a class declared in a source file has been added a long time ago already.
java HelloWorld.java
We may have been confused about it, because we don't launch Java programs so often, so we didn't know about this option before, expecting that launching a program requires an incantation of javac beforehand.
JEP 445
However, the example above uses this feature already:
Java 21 introduces unnamed classes to make the
classdeclaration implicit. Alsopublic static void main(String args[])is no longer required, to reduce boilerplate for single-class programs.
So, this effectively needs JEP 445 which landed with Java 21. Comparing those snippets, it saves a few bytes, class noise, a whole indentation level, and any "naming things" obstacles regarding Java specifics in file name vs. class name discrepancies.
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}void main() {
System.out.println("Hello, World!");
}There was a problem hiding this comment.
Thoughts / Evaluation
So, is it worth to sacrifice backward compatibility for the canonical poster example?
My thoughts were we indeed could do it, because the other spot where canonical code examples are presented, in this case cratedb-examples:by-language/java-jdbc, displays a full Java program BasicPostgresCrateDB.java anyway.
In this spirit, we wanted to reduce boilerplate to the max here, yet retaining the idea of presenting an executable example. It's a narrow path which sometimes needs modern language features, or utility programs like uv for elegantly launching Python code snippets, where the user/reader mostly needed to whip up a whole programming environment (Python virtualenv) before even getting started.
Following this idea and the modernization efforts of upstream software authors who work on such ergonomic enhancements, we have been aiming to present "modern" variants of how to minimally invoke arbitrary code snippets on our documentation as well.
Evaluation / Next steps
We can collectively decide if it's okay to present the modern variants while sacrificing backwards compatibility with previous programming language versions, but sure we should present information which accompanies older versions as well.
Let me come up with another iteration on this document to accomodate a better balance for Java < 21, so you can evaluate and decide if you like it.
There was a problem hiding this comment.
crate-jdbc requires >= 11
We will certainly add this remark about the effective runtime dependency separately and more prominently, thank you.
There was a problem hiding this comment.
Addressed with 0fff874 and dcce170, then ba1ed79, thank you.
At the top, the page now says:
CrateDB JDBC needs Java >= 11.
Only at the bottom when it's about invoking the code snippet at hand, which is primarily thought to be a descriptive example 1, it says:
Invoke program. Needs Java >= 21 (JEP 445), alternatively see Full example.
Footnotes
-
[...] with an optional benefit that it's actually also executable. ↩
There was a problem hiding this comment.
Is it worth to sacrifice backward compatibility for the canonical poster example?
My thoughts were we indeed could do it, because the other spot where canonical code examples are presented, in this case cratedb-examples:by-language/java-jdbc, displays a full Java program BasicPostgresCrateDB.java anyway, [and it is referenced right at the bottom of the page].
The adjustment 5d5de24 further makes this less of an issue, by bringing both spots much closer together now.
docs/connect/java/index.md
Outdated
| - {ref}`postgresql-jdbc` — `jdbc:postgresql://` | ||
| - {ref}`cratedb-jdbc` — `jdbc:crate://` | ||
|
|
||
| Prefer the PostgreSQL JDBC driver first—it’s often already on your classpath |
There was a problem hiding this comment.
| 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 |
There was a problem hiding this comment.
also:
| 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 |
There was a problem hiding this comment.
Improved with 59b8ea3, thanks.
docs/connect/java/postgresql-jdbc.md
Outdated
| Invoke-WebRequest https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.8/postgresql-42.7.8.jar -OutFile postgresql-42.7.8.jar | ||
| ``` | ||
| ::: | ||
| Invoke program. Needs Java >= 25 ([JEP 330]). |
There was a problem hiding this comment.
PostgreSQL-JDBC works with Java >= 1.8, and the given command does not need JEP 330 afaik.
| Invoke program. Needs Java >= 25 ([JEP 330]). | |
| Invoke program. Needs Java >= 1.8. |
There was a problem hiding this comment.
Thanks, this is important information for some. We will highlight runtime version compatibility more prominently.
There was a problem hiding this comment.
Addressed inside 0fff874, thank you.
Previously, the docs stated Java 25 would be required, which isn't true.
docs/connect/java/cratedb-jdbc.md
Outdated
| Invoke-WebRequest https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar -OutFile crate-jdbc-standalone-2.7.0.jar | ||
| ``` | ||
| ::: | ||
| Invoke program. Needs Java >= 25 ([JEP 330]). |
There was a problem hiding this comment.
JEP 330
Hi. We see that JEP 330 landed with Java 11 already, so this comment is certainly misguided; thanks for spotting it.
Apparently, the fourth mode for the Java launcher to launch a class declared in a source file has been added a long time ago already.
java HelloWorld.java
We may have been confused about it, because we don't launch Java programs so often, so we didn't know about this option before, expecting that launching a program requires an incantation of javac beforehand.
JEP 445
However, the example above uses this feature already:
Java 21 introduces unnamed classes to make the
classdeclaration implicit. Alsopublic static void main(String args[])is no longer required, to reduce boilerplate for single-class programs.
So, this effectively needs JEP 445 which landed with Java 21. Comparing those snippets, it saves a few bytes, class noise, a whole indentation level, and any "naming things" obstacles regarding Java specifics in file name vs. class name discrepancies.
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}void main() {
System.out.println("Hello, World!");
}
docs/connect/java/cratedb-jdbc.md
Outdated
| Invoke-WebRequest https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar -OutFile crate-jdbc-standalone-2.7.0.jar | ||
| ``` | ||
| ::: | ||
| Invoke program. Needs Java >= 25 ([JEP 330]). |
There was a problem hiding this comment.
Thoughts / Evaluation
So, is it worth to sacrifice backward compatibility for the canonical poster example?
My thoughts were we indeed could do it, because the other spot where canonical code examples are presented, in this case cratedb-examples:by-language/java-jdbc, displays a full Java program BasicPostgresCrateDB.java anyway.
In this spirit, we wanted to reduce boilerplate to the max here, yet retaining the idea of presenting an executable example. It's a narrow path which sometimes needs modern language features, or utility programs like uv for elegantly launching Python code snippets, where the user/reader mostly needed to whip up a whole programming environment (Python virtualenv) before even getting started.
Following this idea and the modernization efforts of upstream software authors who work on such ergonomic enhancements, we have been aiming to present "modern" variants of how to minimally invoke arbitrary code snippets on our documentation as well.
Evaluation / Next steps
We can collectively decide if it's okay to present the modern variants while sacrificing backwards compatibility with previous programming language versions, but sure we should present information which accompanies older versions as well.
Let me come up with another iteration on this document to accomodate a better balance for Java < 21, so you can evaluate and decide if you like it.
docs/connect/java/cratedb-jdbc.md
Outdated
| Invoke-WebRequest https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar -OutFile crate-jdbc-standalone-2.7.0.jar | ||
| ``` | ||
| ::: | ||
| Invoke program. Needs Java >= 25 ([JEP 330]). |
There was a problem hiding this comment.
crate-jdbc requires >= 11
We will certainly add this remark about the effective runtime dependency separately and more prominently, thank you.
docs/connect/java/postgresql-jdbc.md
Outdated
| Invoke-WebRequest https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.8/postgresql-42.7.8.jar -OutFile postgresql-42.7.8.jar | ||
| ``` | ||
| ::: | ||
| Invoke program. Needs Java >= 25 ([JEP 330]). |
There was a problem hiding this comment.
Thanks, this is important information for some. We will highlight runtime version compatibility more prominently.
docs/connect/java/testing.md
Outdated
| (java-testing)= | ||
|
|
||
| # Software testing | ||
|
|
||
| For testing Java applications against CrateDB, see also documentation | ||
| about {ref}`java-junit` and {ref}`testcontainers`. |
There was a problem hiding this comment.
While being at it, let's unflatten this page a bit more, like others are doing it, probably by using information cards.
Secondly, another possibility is to go further and also relocate the content currently slotted into the topics section, which is bound to be dissolved anyway. Here, closer to its primary topic domain Java, the content would be located much better.
There was a problem hiding this comment.
Excellent. Implemented per ff18c5b.
-- https://cratedb-guide--402.org.readthedocs.build/connect/java/testing.html
docs/connect/java/cratedb-jdbc.md
Outdated
| :::{include} ../_cratedb.md | ||
| ::: | ||
| Download JAR file. | ||
| ```shell | ||
| wget https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar | ||
| ``` | ||
| :::{dropdown} Instructions for Windows users | ||
| If you don't have the `wget` program installed, for example on Windows, just | ||
| download the JAR file using your web browser of choice. | ||
| If you want to use PowerShell, invoke the `Invoke-WebRequest` command instead | ||
| of `wget`. | ||
| ```powershell | ||
| Invoke-WebRequest https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar -OutFile crate-jdbc-standalone-2.7.0.jar | ||
| ``` | ||
| ::: |
There was a problem hiding this comment.
The dropdown reduces clutter/noise significantly already, still it obstructs the reading flow. Consider three things for the next iteration:
a) Provide the download link also per HTML link anchor <a href=""></a>, to better support browser users as already mentioned, freeing them from needing to copy/paste the URL.
b) Relocate all special considerations (wget or Invoke-WebRequest) to the bottom of the page.
c) Alternatively to b), add instructions for both operation system variants (wget and Invoke-WebRequest) to the dropdown, but keep it in this section without relocation.
There was a problem hiding this comment.
I've relocated all the instruction noise to the bottom of the pages per dcce170 now, so the synopsis is more in the focus, followed by (typical) installation instructions, with the quickstart example only at the bottom of the page. I think the pages are much more approachable now, and convey their information in the right order.
-- https://cratedb-guide--402.org.readthedocs.build/connect/java/postgresql-jdbc.html
-- https://cratedb-guide--402.org.readthedocs.build/connect/java/cratedb-jdbc.html
There was a problem hiding this comment.
More command noise reduction per 5d5de24, it's pretty swift now.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/connect/java/testing.md (2)
20-25: Consider minor language refinement.Line 25 uses "afterwards" which is more common in British English; "afterward" aligns better with US English documentation style (though both are acceptable).
Apply this diff if you prefer US English consistency:
-test execution, and stop CrateDB afterwards. +test execution, and stop CrateDB afterward.
46-50: Consider hyphenating compound adjective.Line 46 could be refined by hyphenating "open source" when used as a compound adjective before the noun "framework."
Apply this diff for stylistic consistency:
-[Testcontainers] is an open source framework for providing throwaway, +[Testcontainers] is an open-source framework for providing throwaway,docs/connect/java/postgresql-jdbc.md (2)
25-29: Clarify Java version requirements for the driver vs. the code example.The PostgreSQL JDBC driver is compatible with Java 8 and above. However, the synopsis code example uses Java 21 preview syntax. Consider adding a note explaining that the driver works with Java 8+, but this specific example requires Java 21+ with preview features enabled. The referenced "Full example" section should provide guidance on running with older Java versions if that's a goal.
85-85: Wrap bare URLs in proper Markdown link syntax.Lines 85 and 92 contain bare URLs, which violates Markdown best practices (MD034). Rewrite them as proper reference links or use
<URL>syntax.Apply this diff:
:::{card} -:link: https://jdbc.postgresql.org/download/ +:link: <https://jdbc.postgresql.org/download/> :link-type: url {material-regular}`download;2em` Navigate to the PostgreSQL JDBC Driver installation page. ::: :::{card} -:link: https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.8/postgresql-42.7.8.jar +:link: <https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.8/postgresql-42.7.8.jar> :link-type: url {material-regular}`download;2em` Directly download the recommended `postgresql-42.7.8.jar`. :::Also applies to: 92-92
docs/topic/testing/index.md (1)
2-2: Heading capitalization is consistently lowercase.The heading changed from "# Software Testing" to "# Software testing" (line 2). This is a minor style matter, but ensure it aligns with documentation conventions for consistency across similar section headings.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (13)
docs/_include/links.md(2 hunks)docs/_include/logos.md(1 hunks)docs/connect/index.md(1 hunks)docs/connect/java.md(0 hunks)docs/connect/java/_jdbc_example.md(1 hunks)docs/connect/java/cratedb-jdbc.md(1 hunks)docs/connect/java/hibernate.md(1 hunks)docs/connect/java/index.md(1 hunks)docs/connect/java/jooq.md(1 hunks)docs/connect/java/postgresql-jdbc.md(1 hunks)docs/connect/java/testing.md(1 hunks)docs/install/container/index.md(1 hunks)docs/topic/testing/index.md(1 hunks)
💤 Files with no reviewable changes (1)
- docs/connect/java.md
✅ Files skipped from review due to trivial changes (1)
- docs/install/container/index.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/connect/java/hibernate.md
🧰 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.mddocs/connect/java/cratedb-jdbc.mddocs/connect/java/_jdbc_example.mddocs/connect/java/postgresql-jdbc.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] ~67-~67: Using many exclamation marks might seem excessive (in this case: 4 exclamation marks for a text that’s 2036 characters long)
Context: ...kus/Panache. :::: ::::{grid-item-card} ![jOOQ logo][jOOQ logo]{height=40px} &nbs...
(EN_EXCESSIVE_EXCLAMATION)
docs/connect/java/testing.md
[locale-violation] ~25-~25: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...before test execution, and stop CrateDB afterwards. :::::{grid} ::::{grid-item} :Package...
(AFTERWARDS_US)
[grammar] ~46-~46: Use a hyphen to join words.
Context: ...tcontainers [Testcontainers] is an open source framework for providing throwaway...
(QB_NEW_EN_HYPHEN)
docs/_include/logos.md
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: [CrateDB home]: https://cratedb.com/ [CrateDB logo]: https://avatars.githubusercontent.com/u/4048232?s=200&v=4 [Hibernate logo]: https://logo.svgcdn.com/devicon/hibernate-original.svg [jOOQ logo]: https://www.jooq.org/img/jooq-logo-black.png [JUnit home]: https://junit.org/ [JUnit logo]: https://avatars.githubusercontent.com/u/874086?s=200&v=4 [PostgreSQL home]: https://www.postgresql.org/ [PostgreSQL logo]: https://jdbc.postgresql.org/icons/postgreslogo.svg [Testcontainers for Java]: https://testcontainers.com/guides/getting-started-with-testcontainers-for-java/ [Testcontainers logo]: https://avatars.githubusercontent.com/u/13393021?s=200&v=4
(QB_NEW_DE)
🪛 markdownlint-cli2 (0.18.1)
docs/topic/testing/index.md
18-18: Reference links and images should use a label that is defined
Missing link or image reference definition: "junit logo"
(MD052, reference-links-images)
25-25: Reference links and images should use a label that is defined
Missing link or image reference definition: "testcontainers logo"
(MD052, reference-links-images)
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)
docs/connect/java/testing.md
36-36: Bare URL used
(MD034, no-bare-urls)
62-62: Bare URL used
(MD034, no-bare-urls)
docs/connect/java/_jdbc_example.md
5-5: Bare URL used
(MD034, no-bare-urls)
docs/connect/java/jooq.md
30-30: Bare URL used
(MD034, no-bare-urls)
docs/connect/java/postgresql-jdbc.md
85-85: Bare URL used
(MD034, no-bare-urls)
92-92: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (13)
docs/connect/java/_jdbc_example.md (1)
1-13: Documentation structure looks good.The card layout is clean and properly references the external example repository. The
orphan: truefront matter is appropriate for this supplementary content.docs/connect/java/cratedb-jdbc.md (2)
22-38: Clear runtime and example requirements.The distinction between driver requirements (Java ≥11) and example syntax requirements (Java ≥21 for JEP 445) is well documented and matches prior discussions about balancing boilerplate reduction with backward compatibility.
140-143: Example invocation command is clear.The command correctly specifies the minimum Java version needed for the modern syntax example, with a reference to the full example fallback for older Java versions.
docs/_include/logos.md (1)
1-13: Logo references properly centralized.The markdownlint disable directives are appropriate for this reference-only include file. Logo URLs are valid and point to reliable sources.
docs/_include/links.md (1)
38-38: New Java framework links are well-sourced.Hibernate, jOOQ, and JPA references point to authoritative sources and maintain alphabetical ordering in the reference file.
Also applies to: 49-50
docs/connect/index.md (1)
179-179: Navigation correctly points to new Java documentation hub.The change from
-javato+java/indexproperly reflects the restructured Java connectivity documentation moving from a single file to a dedicated directory with an index page.docs/connect/java/jooq.md (1)
1-40: jOOQ introduction is concise and example-driven.The code example clearly demonstrates jOOQ DSL for filtering and iteration. The material card and GitHub Actions badge appropriately link to example implementations. The static analysis bare URL warnings are false positives, as they occur in MyST component property values (
:link:) rather than bare markdown text.docs/connect/java/testing.md (1)
1-78: Testing documentation hub is well-structured and accessible.The grid-based layout with JUnit and Testcontainers sections, paired logos, example project cards, and reference links provides clear navigation for Java developers. The content addresses both traditional testing (CrateTestServer/CrateTestCluster) and containerized approaches (Testcontainers), meeting the documentation goals.
docs/connect/java/index.md (3)
15-37: Driver guidance accurately reflects JDBC protocol specifics.The section clearly explains JDBC driver options with correct protocol schemes (
jdbc:postgresql://andjdbc:crate://) and actionable guidance to prefer PostgreSQL JDBC first while noting when to switch to CrateDB JDBC. This aligns with the learnings about protocol scheme confusion. The reference to CrateDB JDBC internals documentation provides deeper context.
39-81: Adapters grid is comprehensive and well-organized.The five-card layout (PostgreSQL JDBC, CrateDB JDBC, Hibernate, jOOQ, Testing) efficiently presents Java connectivity options with consistent logo styling and descriptive text. Each card correctly links to its corresponding documentation page via the hidden toctree.
46-46: Logo reference warnings are false positives.Markdownlint flags missing logo definitions (MD052) at these lines, but the logos are properly defined in
docs/_include/logos.md, which is included at line 8. The ![logo name][logo name] syntax is correct; the warnings reflect a limitation in markdownlint's handling of cross-file reference resolution when logos.md is included via MyST directives.If these warnings persist in the build pipeline, you may need to add a markdownlint configuration to ignore MD052 for this file, or verify that the include directive resolves the references at build time.
Also applies to: 53-53, 60-60, 67-67
docs/topic/testing/index.md (2)
12-32: Grid-based card layout for Java testing is a good improvement.The refactored grid layout with cards for JUnit and Testcontainers provides better visual organization and navigability compared to narrative text. This aligns well with the broader PR objective to improve Java documentation presentation.
4-5: Logo references are properly defined.The verification confirms that both
[JUnit logo]and[Testcontainers logo]are correctly defined in/_include/logos.mdand will resolve properly when the include file is processed.
Previously, the docs stated Java 21 would be okay, which isn't true.
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
docs/connect/java/cratedb-jdbc.md(1 hunks)docs/connect/java/postgresql-jdbc.md(1 hunks)docs/connect/java/testing.md(1 hunks)docs/topic/testing/index.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/connect/java/testing.md
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-10-06T16:40:16.322Z
Learnt from: amotl
PR: crate/cratedb-guide#0
File: :0-0
Timestamp: 2025-10-06T16:40:16.322Z
Learning: In the crate/cratedb-guide repository, documentation is organized by content type: files in `docs/feature/`, `docs/integrate/`, and `docs/ingest/` are reference material designed for quick access, while `docs/start/` contains learning path content. Reference material sections use top-right reference layouts for efficient navigation.
Applied to files:
docs/connect/java/cratedb-jdbc.md
📚 Learning: 2025-10-19T19:21:49.864Z
Learnt from: amotl
PR: crate/cratedb-guide#420
File: docs/connect/erlang.md:100-113
Timestamp: 2025-10-19T19:21:49.864Z
Learning: In the cratedb-guide repository, when documenting cloud or alternative connection methods, show only the differences from the canonical example (e.g., SSL configuration) rather than repeating the entire workflow (query execution, cleanup, etc.). This pattern is used consistently across pages to avoid repetition.
Applied to files:
docs/connect/java/cratedb-jdbc.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/cratedb-jdbc.mddocs/connect/java/postgresql-jdbc.md
🪛 markdownlint-cli2 (0.18.1)
docs/connect/java/cratedb-jdbc.md
85-85: Bare URL used
(MD034, no-bare-urls)
92-92: Bare URL used
(MD034, no-bare-urls)
docs/connect/java/postgresql-jdbc.md
36-36: Bare URL used
(MD034, no-bare-urls)
62-62: Bare URL used
(MD034, no-bare-urls)
docs/topic/testing/index.md
18-18: Reference links and images should use a label that is defined
Missing link or image reference definition: "junit logo"
(MD052, reference-links-images)
25-25: Reference links and images should use a label that is defined
Missing link or image reference definition: "testcontainers logo"
(MD052, reference-links-images)
🔇 Additional comments (2)
docs/topic/testing/index.md (2)
12-32: Improved layout structure for Java testing frameworks.The transition from narrative text to a responsive grid card layout enhances visual hierarchy and user navigation. The grid configuration with 2 columns at different breakpoints and the link references to cross-documented pages follow good documentation structure practices.
4-5: No action required — logo references are properly defined.The verification confirms that
/_include/logos.mdcontains the required definitions for both[JUnit logo]and[Testcontainers logo], and the reference syntax on lines 18 and 25 matches exactly. The markdownlint MD052 warnings are false positives that occur because static linters validate before include directives are processed at build time. The grid card layout restructuring is valid and will render correctly.Likely an incorrect or invalid review comment.
| ```java | ||
| import java.sql.*; | ||
|
|
||
| void main() throws SQLException { | ||
|
|
||
| // Connect to database. | ||
| Properties properties = new Properties(); | ||
| properties.put("user", "crate"); | ||
| properties.put("password", "crate"); | ||
| Connection conn = DriverManager.getConnection( | ||
| "jdbc:crate://localhost:5432/doc?sslmode=disable", | ||
| properties | ||
| ); | ||
| conn.setAutoCommit(true); | ||
|
|
||
| // Invoke query. | ||
| Statement st = conn.createStatement(); | ||
| st.execute("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5;"); | ||
|
|
||
| // Display results. | ||
| ResultSet rs = st.getResultSet(); | ||
| while (rs.next()) { | ||
| System.out.printf(Locale.ENGLISH, "%s: %d\n", rs.getString(1), rs.getInt(2)); | ||
| } | ||
| conn.close(); | ||
|
|
||
| } | ||
| ``` |
There was a problem hiding this comment.
Missing imports for Properties and Locale classes (same issue as postgresql-jdbc.md).
The code example uses Properties and Locale classes, but the import statement only includes java.sql.*. The import java.util.*; package is needed, otherwise the code will fail to compile with "Cannot find symbol" errors.
This is the same import issue present in the postgresql-jdbc.md file and blocks the goal of providing executable examples.
Apply this diff to fix the imports:
import java.sql.*;
+import java.util.*;
void main() throws SQLException {Alternatively, if you prefer explicit imports:
import java.sql.*;
+import java.util.Locale;
+import java.util.Properties;
void main() throws SQLException {🤖 Prompt for AI Agents
In docs/connect/java/cratedb-jdbc.md around lines 35 to 62, the example uses
java.util.Properties and java.util.Locale but only imports java.sql.*, causing
compile errors; fix by adding the missing imports (either import java.util.*; or
explicit import java.util.Properties; import java.util.Locale;) at the top of
the snippet so the example compiles and runs.
There was a problem hiding this comment.
@coderabbitai: Why does it work for me? Is it something special with Java 25?
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Java 25 implicit imports automatic imports JEP
💡 Result:
Short summary — Java 25 (JDK 25) finalizes JEP 511: "Module Import Declarations".
- New syntax: import module M; — imports on-demand all public top-level types from the packages exported by module M and the modules it reads. [1]
- Compact source files (the new "compact" / simple compilation-unit form) implicitly import the java.base module, so common APIs from java.base are available without explicit imports. [1][3]
- The previously-proposed automatic static-import of IO methods was dropped; the IO helper was moved to java.lang to ease the on‑ramp without hidden static imports. [2][3]
- Risks: possible name clashes / ambiguity from broad module imports; ambiguity errors surface at compile time and can require single-type imports to resolve. [1]
Sources: JEP 511 (OpenJDK). [1] IntelliJ blog post on Java 25. [2] JVM Weekly summary of JDK 25 features. [3]
🌐 Web query:
JEP 511 java.base implicit imports compact source files Properties Locale
💡 Result:
Short answer: JEP 511 adds a new import form "import module M;" that imports, on-demand, all public top-level types exported by module M. When used together with compact source files (JEP 512), every compact source file implicitly behaves as if it begins with "import module java.base;", so types in java.base (for example java.util.Properties and java.util.Locale) are available by simple name without an explicit import in a compact source file. [1][2][3]
Sources:
- JEP 511 (Module Import Declarations). [1]
- JEP 512 / Compact Source Files (implicit import of java.base in compact compilation units). [2]
- Java SE API pages for java.util.Properties and java.util.Locale (both in java.base). [3]
@amotl, you're absolutely right! In Java 25, compact source files (indicated by the void main() syntax) implicitly import the java.base module via JEP 512. This means all public types from java.base—including java.util.Properties and java.util.Locale—are automatically available without explicit import statements.
My original comment was based on traditional Java compilation requirements, where those imports would be necessary. However, with the compact source file format you're using, the imports are indeed implicit.
Considerations:
-
Java version requirement: JEP 512 compact source files implicitly behave as if they begin with "import module java.base;", but this only works with Java 25+ (or Java 23+ with preview features enabled).
-
Documentation clarity: You might want to add a note mentioning that these examples use Java 25's compact source file format, so users on older Java versions know why it works for you but might not compile for them without adding explicit imports.
-
The doc already mentions "CrateDB JDBC needs Java >= 11": You might want to update this to note that the examples leverage Java 25 features, or provide both versions (traditional vs. compact).
Would you like me to help update the documentation to clarify the Java version requirements for these examples?
(\_(\
(•ㅅ•) *lightbulb moment!*
/ づ💡
✏️ Learnings added
Learnt from: amotl
PR: crate/cratedb-guide#402
File: docs/connect/java/cratedb-jdbc.md:35-62
Timestamp: 2025-10-25T22:54:24.865Z
Learning: Java 25 compact source files (indicated by `void main()` syntax per JEP 512) implicitly import the `java.base` module, making types like `java.util.Properties` and `java.util.Locale` available without explicit import statements. This only works with Java 25+ or Java 23+ with preview features enabled.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
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.
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.
There was a problem hiding this comment.
You might want to add a note mentioning that these examples use Java 25's compact source file format.
Thanks. We had added this information already.
You might want to update this to note that the examples leverage Java 25 features, or provide both versions (traditional vs. compact).
We are referring to the full example at this spot, which will work with previous versions of Java.
/cc @coderabbitai
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check the full content of the cratedb-jdbc.md file to see if Java 25 / compact source file information is already documented
cat docs/connect/java/cratedb-jdbc.md
Length of output: 3350
@amotl, you're absolutely right! I can see it now in the "Run" section at lines 142-143:
"This example needs Java >= 25 ([JEP 512]), with earlier versions please use the full example."
Perfect! The documentation clearly states the Java 25 requirement, references JEP 512, and provides guidance for users on earlier versions to use the full example instead. This addresses the version requirement concern completely.
Thank you for the clarification - the documentation is well covered! 👍
(\(\
(•ㅅ•) *confirmed!*
/>📝
🧠 Learnings used
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.
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.
Learnt from: amotl
PR: crate/cratedb-guide#402
File: docs/connect/java/cratedb-jdbc.md:35-62
Timestamp: 2025-10-25T22:54:24.865Z
Learning: Java 25 compact source files (indicated by `void main()` syntax per JEP 512) implicitly import the `java.base` module, making types like `java.util.Properties` and `java.util.Locale` available without explicit import statements. This only works with Java 25+ or Java 23+ with preview features enabled.
| ```java | ||
| import java.sql.*; | ||
|
|
||
| void main() throws SQLException { | ||
|
|
||
| // Connect to database. | ||
| Properties properties = new Properties(); | ||
| properties.put("user", "crate"); | ||
| properties.put("password", "crate"); | ||
| Connection conn = DriverManager.getConnection( | ||
| "jdbc:postgresql://localhost:5432/doc?sslmode=disable", | ||
| properties | ||
| ); | ||
| conn.setAutoCommit(true); | ||
|
|
||
| // Invoke query. | ||
| Statement st = conn.createStatement(); | ||
| st.execute("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5;"); | ||
|
|
||
| // Display results. | ||
| ResultSet rs = st.getResultSet(); | ||
| while (rs.next()) { | ||
| System.out.printf(Locale.ENGLISH, "%s: %d\n", rs.getString(1), rs.getInt(2)); | ||
| } | ||
| conn.close(); | ||
|
|
||
| } | ||
| ``` |
There was a problem hiding this comment.
Missing imports for Properties and Locale classes.
The code example uses Properties and Locale classes, but the import statement only includes java.sql.*. The import java.util.*; package is needed, otherwise the code will fail to compile with "Cannot find symbol" errors.
This blocks the stated goal of providing "minimal executable examples" as the code is shown but will not run as-is.
Apply this diff to fix the imports:
import java.sql.*;
+import java.util.*;
void main() throws SQLException {Alternatively, if you prefer to be more explicit with imports:
import java.sql.*;
+import java.util.Locale;
+import java.util.Properties;
void main() throws SQLException {📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```java | |
| import java.sql.*; | |
| void main() throws SQLException { | |
| // Connect to database. | |
| Properties properties = new Properties(); | |
| properties.put("user", "crate"); | |
| properties.put("password", "crate"); | |
| Connection conn = DriverManager.getConnection( | |
| "jdbc:postgresql://localhost:5432/doc?sslmode=disable", | |
| properties | |
| ); | |
| conn.setAutoCommit(true); | |
| // Invoke query. | |
| Statement st = conn.createStatement(); | |
| st.execute("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5;"); | |
| // Display results. | |
| ResultSet rs = st.getResultSet(); | |
| while (rs.next()) { | |
| System.out.printf(Locale.ENGLISH, "%s: %d\n", rs.getString(1), rs.getInt(2)); | |
| } | |
| conn.close(); | |
| } | |
| ``` | |
| import java.sql.*; | |
| import java.util.*; | |
| void main() throws SQLException { | |
| // Connect to database. | |
| Properties properties = new Properties(); | |
| properties.put("user", "crate"); | |
| properties.put("password", "crate"); | |
| Connection conn = DriverManager.getConnection( | |
| "jdbc:postgresql://localhost:5432/doc?sslmode=disable", | |
| properties | |
| ); | |
| conn.setAutoCommit(true); | |
| // Invoke query. | |
| Statement st = conn.createStatement(); | |
| st.execute("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5;"); | |
| // Display results. | |
| ResultSet rs = st.getResultSet(); | |
| while (rs.next()) { | |
| System.out.printf(Locale.ENGLISH, "%s: %d\n", rs.getString(1), rs.getInt(2)); | |
| } | |
| conn.close(); | |
| } |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
36-36: Bare URL used
(MD034, no-bare-urls)
62-62: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In docs/connect/java/postgresql-jdbc.md around lines 35 to 62, the example uses
Properties and Locale but only imports java.sql.*, causing compilation errors;
add the missing imports (either import java.util.*; or the explicit import
java.util.Properties; and import java.util.Locale;) at the top of the file so
the example compiles and runs as a minimal executable snippet.
3 participants
About
Preview
https://cratedb-guide--402.org.readthedocs.build/connect/java/
/cc @zolbatar, @kneth, @surister