Java: Modernize page #385

amotl · 2025-10-08T01:25:44Z

About

An attempt to modernize the page about Java/JDBC.

Preview

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

References

coderabbitai · 2025-10-08T01:26:10Z

Walkthrough

Replaced the Java connection docs with a structured page that includes link includes, separate PostgreSQL JDBC and CrateDB JDBC sections (Synopsis, Maven, Gradle, Download), examples and a full CrateDB JDBC runnable example, plus updated testing references. Documentation-only changes; no code/API edits. (≈ thirty words)

Changes

Cohort / File(s)	Summary of changes
Java connection docs `docs/connect/java.md`	Rewrote and restructured the Java connection doc: added include for links, introduced PostgreSQL JDBC and CrateDB JDBC sections (Synopsis, Maven, Gradle, Download cards), added properties-based and JDBC-URL examples, a full runnable CrateDB JDBC example, example/play cards, testing links (java-junit, testcontainers), and formatting/indentation tweaks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

maintenance

I twitch my whiskers, hop and write,
JDBC pages snug tonight.
Crate and Postgres side by side,
Maven notes and examples tied. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title “Java: Modernize page” directly references the core update of the pull request, which is to modernize the Java/JDBC documentation page, and does so in a concise, clear manner without unnecessary detail or ambiguity. It succinctly conveys the primary intent of the changeset, making it easy for teammates to understand the focus at a glance. The phrasing avoids generic terms like “misc” or “updates” and aligns with the documented modifications.
Description Check	✅ Passed	The description clearly states the intent to modernize the Java/JDBC page, provides a preview link to review the changes, and includes relevant issue references, all of which align with the actual modifications in the pull request. It stays on topic by summarizing what was updated and where to see it, without introducing unrelated information.
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

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3a3cbc4 and bb36551.

📒 Files selected for processing (1)

docs/connect/java.md (3 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 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.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.md

🪛 markdownlint-cli2 (0.18.1)

docs/connect/java.md

84-84: Bare URL used

(MD034, no-bare-urls)

135-135: Bare URL used

(MD034, no-bare-urls)

178-178: Bare URL used

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Build docs

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

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

coderabbitai

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 94dfc73 and ff3709c.

📒 Files selected for processing (1)

docs/connect/java.md (3 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 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.md

🪛 markdownlint-cli2 (0.18.1)

docs/connect/java.md

83-83: Bare URL used

(MD034, no-bare-urls)

167-167: Bare URL used

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Build docs

coderabbitai · 2025-10-08T01:28:24Z

docs/connect/java.md

+properties.put("password", "<PASSWORD>");
+properties.put("ssl", true);


⚠️ Potential issue | 🔴 Critical

Store JDBC properties as strings

Properties.getProperty(...) returns only String values. By writing a Boolean (true) for ssl, the driver sees null, so SSL stays off. Use setProperty("ssl", "true") (and consider doing the same for the other keys for consistency).

-properties.put("ssl", true); +properties.setProperty("ssl", "true");

Apply this in both JDBC snippets and the full example.

Also applies to: 102-104, 132-134

🤖 Prompt for AI Agents

In docs/connect/java.md around lines 46-47 (and also apply the same change at lines 102-104 and 132-134), JDBC Properties are being set with a boolean value for "ssl" which causes Properties.getProperty(...) to return null; change these to use string values via Properties.setProperty("ssl", "true") (and similarly setProperty for other keys like "user" and "password" to keep consistency) in both small JDBC snippets and the full example so the driver reads the values correctly.

@matriv: Do you agree with this evaluation, or is it nonsense?

https://jdbc.postgresql.org/documentation/use

ssl (boolean) Default false Connect using SSL. The server must have been compiled with SSL support. This property does not need a value associated with it. The mere presence of it specifies an SSL connection. However, for compatibility with future versions, the value “true” is preferred. For more information see [Using SSL](https://jdbc.postgresql.org/documentation/ssl/). Setting up the certificates and keys for ssl connection can be tricky see [The test documentation](https://github.com/pgjdbc/pgjdbc/blob/master/certdir/README.md) for detailed examples.

but in their example above:

props.setProperty("ssl", "true");

So I guess both work

Thanks. So, we'll keep this unmodified, right?

docs/connect/java.md

amotl · 2025-10-08T02:03:38Z

docs/connect/java.md

Is it applicable to refer to other Java-related topics at the bottom of the page?

Software testing:

https://cratedb.com/docs/guide/topic/testing/

Integrations:

https://cratedb.com/docs/guide/integrate/databricks/

https://cratedb.com/docs/guide/integrate/debezium/

https://cratedb.com/docs/guide/integrate/flink/

https://cratedb.com/docs/guide/integrate/hop/

https://cratedb.com/docs/guide/integrate/jmeter/

https://cratedb.com/docs/guide/integrate/kafka/

https://cratedb.com/docs/guide/integrate/spark/

https://cratedb.com/docs/guide/integrate/trino/

I tend not to, I think maybe only the testing fits here.

I've added a note per c2a090d, thanks.

matriv

looks good, thx, just one comment.

matriv · 2025-10-08T07:33:11Z

docs/connect/java.md

+while CrateDB JDBC uses `jdbc:crate://`.
+:::
+
+Applications using the PostgreSQL JDBC Driver may emit PostgreSQL-specific


imho we should rephrase to encourage using the postgres jdbc and only if they encounter problems turn to our crate one.

I am still not convinced we should really encourage people to use the vanilla driver, because the CrateDB driver offers so many excellent usability features?

I think the shortcomings of the vanilla driver are quickly present, so all serious Java applications are using the CrateDB driver, if I am not mistaken, like our Flink demo code is also doing it? Could you provide feedback here, @zolbatar and @mackerl?

Of course I might not be up-to-date about the situation, so please correct me if I am wrong. Nevertheless, I've added 9f757e3 at your disposal; please suggest any wording improvements. 🙇

AFAIK Postgres driver is the first option, this is the one we use in our java integration tests in crate/crate repo.
This is the one that we use for crate-qa client tests. CrateDB is to be used only when hiccups are encountered with the stock jdbc driver.

So I think we should also interchange the sections and mention first the PostgreSQL jdbc and then ours.

Thanks. I've swapped the sections, know about your rationale, but I am still challenging it strongly. I think we are doing a bad service to CrateDB if we keep it like this, because subtle differences in databases should actively be balanced within the driver layer, to not let application developers stranded. All the competitors are doing it excellently for both JDBC and ODBC, and I would like to see that CrateDB will start doing the same.

For example, if we don't modernize and maintain the CrateDB JDBC Driver, we will never be able to conceive a Hibernate dialect on top of it, and only then any database will start getting interesting for many.

I don't argue against that, but the situation currently is that stock JDBC is in favor.

It's not about this PR, so let's merge it. Still I am interested how this situation came into existence. As long as we keep it that way, including the thinking perspective, I fear not much will change here. Maybe there will be another discussion about this topic at a better spot soon. Please provide relevant guidance when possible.

The decision back in the past is that we don't have the manpower to keep track of psql jdbc changes and incorporate them to our own version of the driver and to rather try to make our CrateDB (server side) compatible with the new changes in postgres jdbc, which also makes sense to make it more and more compatible with PostgreSQL tooling in general.

I agree with @matriv that the Postgres driver is the first option.

matriv · 2025-10-08T07:35:39Z

docs/connect/java.md

I tend not to, I think maybe only the testing fits here.

matriv

LGTM, thx!
Added one more comment though about the ordering: #385 (comment)

amotl marked this pull request as ready for review October 8, 2025 01:25

amotl added sanding-1200 Fine sanding. cross linking Linking to different locations of the documentation. new content New content being added. labels Oct 8, 2025

coderabbitai bot reviewed Oct 8, 2025

View reviewed changes

amotl requested review from matriv and seut and removed request for matriv and seut October 8, 2025 01:36

amotl commented Oct 8, 2025

View reviewed changes

docs/connect/java.md Show resolved Hide resolved

docs/connect/java.md Show resolved Hide resolved

docs/connect/java.md Outdated Show resolved Hide resolved

amotl commented Oct 8, 2025

View reviewed changes

amotl requested review from matriv and seut October 8, 2025 02:21

matriv reviewed Oct 8, 2025

View reviewed changes

amotl requested a review from matriv October 8, 2025 21:48

amotl force-pushed the java branch from c2a090d to b2a5517 Compare October 8, 2025 21:56

This comment was marked as resolved.

Sign in to view

amotl force-pushed the java branch from b2a5517 to 3a3cbc4 Compare October 8, 2025 22:24

matriv approved these changes Oct 9, 2025

View reviewed changes

amotl added 6 commits October 9, 2025 13:44

Java: Modernize page

f5d4c21

Java: Add reference to full executable code example

cbacb10

Java: Implement suggestions by CodeRabbit

a7d6202

Java: Encourage using the PostgreSQL JDBC Driver

493389b

Java: Add note about software testing with Java and CrateDB

1c0f94c

Java: List PostgreSQL JDBC driver first

bb36551

amotl force-pushed the java branch from 3a3cbc4 to bb36551 Compare October 9, 2025 11:45

amotl merged commit 79cbb6e into main Oct 9, 2025
3 checks passed

amotl deleted the java branch October 9, 2025 12:21

		properties.put("password", "<PASSWORD>");
		properties.put("ssl", true);

Java: Modernize page #385

Java: Modernize page #385

Conversation

amotl commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

About

Preview

References

Uh oh!

coderabbitai bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as off-topic.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matriv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

matriv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

amotl commented Oct 8, 2025 •

edited

Loading

coderabbitai bot commented Oct 8, 2025 •

edited

Loading

amotl Oct 8, 2025 •

edited

Loading

amotl Oct 9, 2025 •

edited

Loading