From f5d4c21a4b55eb809f31d35acdd1696e96b61757 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 8 Oct 2025 03:24:01 +0200 Subject: [PATCH 1/6] Java: Modernize page --- docs/connect/java.md | 139 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 133 insertions(+), 6 deletions(-) diff --git a/docs/connect/java.md b/docs/connect/java.md index b6ec94f8..5224b625 100644 --- a/docs/connect/java.md +++ b/docs/connect/java.md @@ -2,15 +2,93 @@ # Java +:::{include} /_include/links.md +::: + :::{div} sd-text-muted -Connect to CrateDB using JDBC. +Java applications mostly use JDBC to connect to CrateDB. ::: -JDBC is a standard Java API that provides a common interface for accessing +[JDBC] is a standard Java API that provides a common interface for accessing databases in Java. +::: + +:::{rubric} Driver options +::: + +:::{div} +You have two JDBC driver options: The [PostgreSQL +JDBC Driver] and the {ref}`crate-jdbc:index`. +PostgreSQL JDBC uses the `jdbc:postgresql://` protocol identifier, +while CrateDB JDBC uses `jdbc:crate://`. +::: -Example method used in implementation: +When applications or frameworks select the vanilla PostgreSQL JDBC +Driver, they might emit SQL statements very specific to PostgreSQL +that CrateDB does not understand. In this case, you are advised to +select the CrateDB JDBC Driver, so downstream layers can assume +"roughly compatible to PostgreSQL", or supply a dialect +implementation specific to CrateDB. + +The {ref}`crate-jdbc:internals` page includes more information +about compatibility and differences between the two driver variants, +and more details about the CrateDB JDBC Driver. + +## CrateDB JDBC + +:::{rubric} Synopsis +::: +```java +Properties properties = new Properties(); +properties.put("user", "admin"); +properties.put("password", ""); +properties.put("ssl", true); +Connection conn = DriverManager.getConnection( + "jdbc:crate://.cratedb.net:5432/", + properties +); +``` + +:::{rubric} Maven +::: + +```xml + + + io.crate + crate-jdbc + 2.7.0 + + +``` + +:::{rubric} Gradle +::: + +```groovy +repositories { + mavenCentral() +} +dependencies { + implementation 'io.crate:crate-jdbc:2.7.0' +} +``` + +:::{rubric} Download +::: + +:::{card} +:link: https://cratedb.com/docs/jdbc/en/latest/getting-started.html#installation +:link-type: url +{material-outlined}`download;2em` +Download and install the CrateDB JDBC Driver. +::: + +:::{rubric} Full example +::: + +:::{dropdown} `main.java` ```java import java.sql.*; import java.util.Properties; @@ -23,8 +101,8 @@ public class Main { properties.put("password", ""); properties.put("ssl", true); Connection conn = DriverManager.getConnection( - "jdbc:crate://.cratedb.net:5432/", - properties + "jdbc:crate://.cratedb.net:5432/", + properties ); Statement statement = conn.createStatement(); @@ -39,5 +117,54 @@ public class Main { } } ``` +::: + + +## PostgreSQL JDBC -See full documentation {ref}`here `. +:::{rubric} Synopsis +::: + +```java +Properties properties = new Properties(); +properties.put("user", "admin"); +properties.put("password", ""); +properties.put("ssl", true); +Connection conn = DriverManager.getConnection( + "jdbc:postgresql://.cratedb.net:5432/", + properties +); +``` + +:::{rubric} Maven +::: + +```xml + + org.postgresql + postgresql + 42.7.8 + +``` + +:::{rubric} Gradle +::: + +```groovy +repositories { + mavenCentral() +} +dependencies { + implementation 'org.postgresql:postgresql:42.7.8' +} +``` + +:::{rubric} Download +::: + +:::{card} +:link: https://jdbc.postgresql.org/download/ +:link-type: url +{material-outlined}`download;2em` +Download and install the PostgreSQL JDBC Driver. +::: From cbacb1030570bc63779e22216e388149cf1446b0 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 8 Oct 2025 04:12:28 +0200 Subject: [PATCH 2/6] Java: Add reference to full executable code example --- docs/connect/java.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/connect/java.md b/docs/connect/java.md index 5224b625..7a43de6f 100644 --- a/docs/connect/java.md +++ b/docs/connect/java.md @@ -168,3 +168,16 @@ dependencies { {material-outlined}`download;2em` Download and install the PostgreSQL JDBC Driver. ::: + + +## Example + +:::{card} +:link: https://github.com/crate/cratedb-examples/tree/main/by-language/java-jdbc +:link-type: url +{material-outlined}`play_arrow;2em` +Connect to CrateDB and CrateDB Cloud using JDBC. ++++ +Demonstrates a basic example using both the vanilla PostgreSQL JDBC Driver +and the CrateDB JDBC Driver. +::: From a7d620281b0a964366f6dabbb98f6e06992ea35c Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 8 Oct 2025 04:12:43 +0200 Subject: [PATCH 3/6] Java: Implement suggestions by CodeRabbit --- docs/connect/java.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/connect/java.md b/docs/connect/java.md index 7a43de6f..ef66e1dd 100644 --- a/docs/connect/java.md +++ b/docs/connect/java.md @@ -23,12 +23,11 @@ PostgreSQL JDBC uses the `jdbc:postgresql://` protocol identifier, while CrateDB JDBC uses `jdbc:crate://`. ::: -When applications or frameworks select the vanilla PostgreSQL JDBC -Driver, they might emit SQL statements very specific to PostgreSQL -that CrateDB does not understand. In this case, you are advised to -select the CrateDB JDBC Driver, so downstream layers can assume -"roughly compatible to PostgreSQL", or supply a dialect -implementation specific to CrateDB. +Applications using the PostgreSQL JDBC Driver may emit PostgreSQL-specific +SQL that CrateDB doesn't understand. Use the CrateDB JDBC Driver instead +to ensure compatibility and allow downstream components to handle +CrateDB-specific behavior, for example, by employing a CrateDB-specific +SQL dialect implementation. The {ref}`crate-jdbc:internals` page includes more information about compatibility and differences between the two driver variants, From 493389b84f07f27a76ccf6c5250f926c6696ae1b Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 8 Oct 2025 23:37:33 +0200 Subject: [PATCH 4/6] Java: Encourage using the PostgreSQL JDBC Driver --- docs/connect/java.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/connect/java.md b/docs/connect/java.md index ef66e1dd..e617223f 100644 --- a/docs/connect/java.md +++ b/docs/connect/java.md @@ -23,8 +23,12 @@ PostgreSQL JDBC uses the `jdbc:postgresql://` protocol identifier, while CrateDB JDBC uses `jdbc:crate://`. ::: -Applications using the PostgreSQL JDBC Driver may emit PostgreSQL-specific -SQL that CrateDB doesn't understand. Use the CrateDB JDBC Driver instead +You are encouraged to probe the PostgreSQL JDBC Driver first. This is the +most convenient option, specifically if the system you are connecting with +already includes the driver jar. + +However, applications using the PostgreSQL JDBC Driver may emit PostgreSQL-specific +SQL that CrateDB does not understand. Use the CrateDB JDBC Driver instead to ensure compatibility and allow downstream components to handle CrateDB-specific behavior, for example, by employing a CrateDB-specific SQL dialect implementation. From 1c0f94c14324648589ec139fd31cad3301e9e903 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 8 Oct 2025 23:48:07 +0200 Subject: [PATCH 5/6] Java: Add note about software testing with Java and CrateDB --- docs/connect/java.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/connect/java.md b/docs/connect/java.md index e617223f..98d4cfa7 100644 --- a/docs/connect/java.md +++ b/docs/connect/java.md @@ -184,3 +184,8 @@ Connect to CrateDB and CrateDB Cloud using JDBC. Demonstrates a basic example using both the vanilla PostgreSQL JDBC Driver and the CrateDB JDBC Driver. ::: + +## Further reading + +For testing Java applications against CrateDB, see also documentation +about {ref}`java-junit` and {ref}`testcontainers`. From bb3655173495c9644c4ab1813ed0c699fee48259 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 9 Oct 2025 13:45:10 +0200 Subject: [PATCH 6/6] Java: List PostgreSQL JDBC driver first --- docs/connect/java.md | 101 +++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 51 deletions(-) diff --git a/docs/connect/java.md b/docs/connect/java.md index 98d4cfa7..a47489e2 100644 --- a/docs/connect/java.md +++ b/docs/connect/java.md @@ -37,6 +37,56 @@ The {ref}`crate-jdbc:internals` page includes more information about compatibility and differences between the two driver variants, and more details about the CrateDB JDBC Driver. + +## PostgreSQL JDBC + +:::{rubric} Synopsis +::: + +```java +Properties properties = new Properties(); +properties.put("user", "admin"); +properties.put("password", ""); +properties.put("ssl", true); +Connection conn = DriverManager.getConnection( + "jdbc:postgresql://.cratedb.net:5432/", + properties +); +``` + +:::{rubric} Maven +::: + +```xml + + org.postgresql + postgresql + 42.7.8 + +``` + +:::{rubric} Gradle +::: + +```groovy +repositories { + mavenCentral() +} +dependencies { + implementation 'org.postgresql:postgresql:42.7.8' +} +``` + +:::{rubric} Download +::: + +:::{card} +:link: https://jdbc.postgresql.org/download/ +:link-type: url +{material-outlined}`download;2em` +Download and install the PostgreSQL JDBC Driver. +::: + ## CrateDB JDBC :::{rubric} Synopsis @@ -122,57 +172,6 @@ public class Main { ``` ::: - -## PostgreSQL JDBC - -:::{rubric} Synopsis -::: - -```java -Properties properties = new Properties(); -properties.put("user", "admin"); -properties.put("password", ""); -properties.put("ssl", true); -Connection conn = DriverManager.getConnection( - "jdbc:postgresql://.cratedb.net:5432/", - properties -); -``` - -:::{rubric} Maven -::: - -```xml - - org.postgresql - postgresql - 42.7.8 - -``` - -:::{rubric} Gradle -::: - -```groovy -repositories { - mavenCentral() -} -dependencies { - implementation 'org.postgresql:postgresql:42.7.8' -} -``` - -:::{rubric} Download -::: - -:::{card} -:link: https://jdbc.postgresql.org/download/ -:link-type: url -{material-outlined}`download;2em` -Download and install the PostgreSQL JDBC Driver. -::: - - ## Example :::{card}