diff --git a/_includes/v19.2/app/BasicExample.java b/_includes/v19.2/app/BasicExample.java index d63c30f6aba..364bf0811ac 100644 --- a/_includes/v19.2/app/BasicExample.java +++ b/_includes/v19.2/app/BasicExample.java @@ -39,6 +39,7 @@ public static void main(String[] args) { ds.setPassword(null); ds.setSsl(true); ds.setSslMode("require"); + ds.setSslRootCert("certs/client.root.crt"); ds.setSslCert("certs/client.maxroach.crt"); ds.setSslKey("certs/client.maxroach.key.pk8"); ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string diff --git a/_includes/v19.2/app/java-tls-note.md b/_includes/v19.2/app/java-tls-note.md new file mode 100644 index 00000000000..3f17cdcb5cd --- /dev/null +++ b/_includes/v19.2/app/java-tls-note.md @@ -0,0 +1,3 @@ +{{site.data.alerts.callout_danger}} +CockroachDB versions v20.1 and lower require TLS 1.2. By default, Java 8 uses TLS 1.2, but applications running on Java 9+ must be configured to run TLS 1.2. For example, when starting your app, use: `$ java -Djdk.tls.client.protocols=TLSv1.2 appName` +{{site.data.alerts.end}} \ No newline at end of file diff --git a/_includes/v19.2/app/java-version-note.md b/_includes/v19.2/app/java-version-note.md new file mode 100644 index 00000000000..3d559314262 --- /dev/null +++ b/_includes/v19.2/app/java-version-note.md @@ -0,0 +1,3 @@ +{{site.data.alerts.callout_info}} +We recommend using Java versions 8+ with CockroachDB. +{{site.data.alerts.end}} \ No newline at end of file diff --git a/_includes/v20.1/app/BasicExample.java b/_includes/v20.1/app/BasicExample.java index d63c30f6aba..364bf0811ac 100644 --- a/_includes/v20.1/app/BasicExample.java +++ b/_includes/v20.1/app/BasicExample.java @@ -39,6 +39,7 @@ public static void main(String[] args) { ds.setPassword(null); ds.setSsl(true); ds.setSslMode("require"); + ds.setSslRootCert("certs/client.root.crt"); ds.setSslCert("certs/client.maxroach.crt"); ds.setSslKey("certs/client.maxroach.key.pk8"); ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string diff --git a/_includes/v20.1/app/java-tls-note.md b/_includes/v20.1/app/java-tls-note.md new file mode 100644 index 00000000000..3f17cdcb5cd --- /dev/null +++ b/_includes/v20.1/app/java-tls-note.md @@ -0,0 +1,3 @@ +{{site.data.alerts.callout_danger}} +CockroachDB versions v20.1 and lower require TLS 1.2. By default, Java 8 uses TLS 1.2, but applications running on Java 9+ must be configured to run TLS 1.2. For example, when starting your app, use: `$ java -Djdk.tls.client.protocols=TLSv1.2 appName` +{{site.data.alerts.end}} \ No newline at end of file diff --git a/_includes/v20.1/app/java-version-note.md b/_includes/v20.1/app/java-version-note.md new file mode 100644 index 00000000000..3d559314262 --- /dev/null +++ b/_includes/v20.1/app/java-version-note.md @@ -0,0 +1,3 @@ +{{site.data.alerts.callout_info}} +We recommend using Java versions 8+ with CockroachDB. +{{site.data.alerts.end}} \ No newline at end of file diff --git a/_includes/v20.2/app/BasicExample.java b/_includes/v20.2/app/BasicExample.java index d63c30f6aba..364bf0811ac 100644 --- a/_includes/v20.2/app/BasicExample.java +++ b/_includes/v20.2/app/BasicExample.java @@ -39,6 +39,7 @@ public static void main(String[] args) { ds.setPassword(null); ds.setSsl(true); ds.setSslMode("require"); + ds.setSslRootCert("certs/client.root.crt"); ds.setSslCert("certs/client.maxroach.crt"); ds.setSslKey("certs/client.maxroach.key.pk8"); ds.setReWriteBatchedInserts(true); // add `rewriteBatchedInserts=true` to pg connection string diff --git a/_includes/v20.2/app/java-tls-note.md b/_includes/v20.2/app/java-tls-note.md new file mode 100644 index 00000000000..8e0bb971c5c --- /dev/null +++ b/_includes/v20.2/app/java-tls-note.md @@ -0,0 +1,7 @@ +{{site.data.alerts.callout_danger}} +CockroachDB versions v20.2 and higher support TLS 1.2 and 1.3, and use 1.3 by default. + +A bug in the TLS 1.3 implementation in Java 11 versions lower than 11.0.7 and Java 13 versions lower than 13.0.3 makes the versions incompatible with CockroachDB. For applications running Java 11 or 13, make sure that you have version 11.0.7 or higher, or 13.0.3 or higher. + +If you cannot upgrade to a version higher than 11.0.7 or 13.0.3, you must configure the application to use TLS 1.2. For example, when starting your app, use: `$ java -Djdk.tls.client.protocols=TLSv1.2 appName` +{{site.data.alerts.end}} \ No newline at end of file diff --git a/_includes/v20.2/app/java-version-note.md b/_includes/v20.2/app/java-version-note.md new file mode 100644 index 00000000000..3d559314262 --- /dev/null +++ b/_includes/v20.2/app/java-version-note.md @@ -0,0 +1,3 @@ +{{site.data.alerts.callout_info}} +We recommend using Java versions 8+ with CockroachDB. +{{site.data.alerts.end}} \ No newline at end of file diff --git a/v19.2/build-a-java-app-with-cockroachdb-hibernate.md b/v19.2/build-a-java-app-with-cockroachdb-hibernate.md index 6134b0f2f75..10e41910033 100644 --- a/v19.2/build-a-java-app-with-cockroachdb-hibernate.md +++ b/v19.2/build-a-java-app-with-cockroachdb-hibernate.md @@ -13,6 +13,8 @@ twitter: false This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM. +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For another use of Hibernate with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. {{site.data.alerts.end}} @@ -21,10 +23,6 @@ For another use of Hibernate with CockroachDB, see our [`examples-orms`](https:/ {% include {{page.version.version}}/app/before-you-begin.md %} -{{site.data.alerts.callout_danger}} -The examples on this page assume you are using a Java version <= 9. They do not work with Java 10. -{{site.data.alerts.end}} - ## Step 1. Install the Gradle build tool This tutorial uses the [Gradle build tool](https://gradle.org/) to get all dependencies for your application, including Hibernate. diff --git a/v19.2/build-a-java-app-with-cockroachdb-jooq.md b/v19.2/build-a-java-app-with-cockroachdb-jooq.md index 9bcfc327e23..6b803073925 100644 --- a/v19.2/build-a-java-app-with-cockroachdb-jooq.md +++ b/v19.2/build-a-java-app-with-cockroachdb-jooq.md @@ -15,6 +15,8 @@ This tutorial shows you how build a simple Java application with CockroachDB and CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases). +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. {{site.data.alerts.end}} @@ -47,10 +49,6 @@ For other ways to install Maven, see [its official documentation](https://maven. Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file. -{{site.data.alerts.callout_info}} -If you have Java 6, Java 8, or Java 11, go to [Download your jOOQ version](https://www.jooq.org/download/versions#trial), and download the free trial of jOOQ for your version of Java. -{{site.data.alerts.end}} - To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder: {% include copy-clipboard.html %} diff --git a/v19.2/build-a-java-app-with-cockroachdb.md b/v19.2/build-a-java-app-with-cockroachdb.md index a7ba6f1bdfb..50ce1408f7f 100644 --- a/v19.2/build-a-java-app-with-cockroachdb.md +++ b/v19.2/build-a-java-app-with-cockroachdb.md @@ -13,17 +13,15 @@ twitter: false This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver. +{% include {{page.version.version}}/app/java-version-note.md %} + ## Before you begin {% include {{page.version.version}}/app/before-you-begin.md %} -{{site.data.alerts.callout_danger}} -The examples on this page assume you are using a Java version <= 9. They do not work with Java 10. -{{site.data.alerts.end}} - ## Step 1. Install the Java JDBC driver -Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). +Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
@@ -35,7 +33,7 @@ Download and set up the Java JDBC driver as described in the [official documenta Create a certificate and key for the `maxroach` user by running the following command. The code samples will run as this user. -New in v19.1: You can pass the [`--also-generate-pkcs8-key` flag](cockroach-cert.html#flag-pkcs8) to generate a key in [PKCS#8 format](https://tools.ietf.org/html/rfc5208), which is the standard key encoding format in Java. In this case, the generated PKCS8 key will be named `client.maxroach.key.pk8`. +You can pass the [`--also-generate-pkcs8-key` flag](cockroach-cert.html#flag-pkcs8) to generate a key in [PKCS#8 format](https://tools.ietf.org/html/rfc5208), which is the standard key encoding format in Java. In this case, the generated PKCS8 key will be named `client.maxroach.key.pk8`. {% include copy-clipboard.html %} ~~~ shell @@ -64,7 +62,7 @@ It does all of the above using the practices we recommend for using JDBC with Co To run it: -1. Download [`BasicExample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v19.1/app/BasicExample.java), or create the file yourself and copy the code below. +1. Download [`BasicExample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/{{page.version.version}}/app/BasicExample.java), or create the file yourself and copy the code below. 2. Compile and run the code (adding the PostgreSQL JDBC driver to your classpath): {% include copy-clipboard.html %} @@ -83,7 +81,7 @@ To clone a version of the code below that connects to insecure clusters, run the `git clone https://github.com/cockroachlabs/hello-world-java-jdbc/` {{site.data.alerts.end}} -The contents of [`BasicExample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v19.1/app/BasicExample.java): +The contents of [`BasicExample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/{{page.version.version}}/app/BasicExample.java): {% include copy-clipboard.html %} ~~~ java @@ -138,7 +136,7 @@ To run it: $ java -classpath .:/path/to/postgresql.jar BasicExample ~~~ -The contents of [`BasicExample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v19.1/app/insecure/BasicExample.java): +The contents of [`BasicExample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/{{page.version.version}}/app/insecure/BasicExample.java): {% include copy-clipboard.html %} ~~~ java diff --git a/v19.2/install-client-drivers.md b/v19.2/install-client-drivers.md index 1e90047f4e8..149ce6863ed 100644 --- a/v19.2/install-client-drivers.md +++ b/v19.2/install-client-drivers.md @@ -129,13 +129,17 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
+{% include {{page.version.version}}/app/java-version-note.md %} + +{% include {{page.version.version}}/app/java-tls-note.md %} + ## Drivers ### JDBC **Support level:** Full -Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). +Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver. For a simple but complete "Hello World" example app, see [Build a Java App with CockroachDB and JDBC](build-a-java-app-with-cockroachdb.html). diff --git a/v20.1/build-a-java-app-with-cockroachdb-hibernate.md b/v20.1/build-a-java-app-with-cockroachdb-hibernate.md index 6aec557a602..fe121dbd79d 100644 --- a/v20.1/build-a-java-app-with-cockroachdb-hibernate.md +++ b/v20.1/build-a-java-app-with-cockroachdb-hibernate.md @@ -14,24 +14,18 @@ twitter: false This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM. +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For a sample app and tutorial that uses Spring Data JPA (Hibernate) and CockroachDB, see [Build a Spring App with CockroachDB and JPA](build-a-spring-app-with-cockroachdb-jpa.html). For another use of Hibernate with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. {{site.data.alerts.end}} -{{site.data.alerts.callout_info}} -For Java applications that use the Spring framework, see the applications listed under [Java/Spring](build-a-spring-app-with-cockroachdb-mybatis.html). -{{site.data.alerts.end}} - ## Before you begin {% include {{page.version.version}}/app/before-you-begin.md %} -{{site.data.alerts.callout_danger}} -The examples on this page assume you are using a Java version <= 9. They do not work with Java 10. -{{site.data.alerts.end}} - ## Step 1. Install the Gradle build tool This tutorial uses the [Gradle build tool](https://gradle.org/) to get all dependencies for your application, including Hibernate. diff --git a/v20.1/build-a-java-app-with-cockroachdb-jooq.md b/v20.1/build-a-java-app-with-cockroachdb-jooq.md index e0bb4544520..cb10572d054 100644 --- a/v20.1/build-a-java-app-with-cockroachdb-jooq.md +++ b/v20.1/build-a-java-app-with-cockroachdb-jooq.md @@ -16,14 +16,12 @@ This tutorial shows you how build a simple Java application with CockroachDB and CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases). +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. {{site.data.alerts.end}} -{{site.data.alerts.callout_info}} -For Java applications that use the Spring framework, see the applications listed under [Java/Spring](build-a-spring-app-with-cockroachdb-mybatis.html). -{{site.data.alerts.end}} - ## Before you begin {% include {{page.version.version}}/app/before-you-begin.md %} @@ -52,10 +50,6 @@ For other ways to install Maven, see [its official documentation](https://maven. Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file. -{{site.data.alerts.callout_info}} -If you have Java 6, Java 8, or Java 11, go to [Download your jOOQ version](https://www.jooq.org/download/versions#trial), and download the free trial of jOOQ for your version of Java. -{{site.data.alerts.end}} - To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder: {% include copy-clipboard.html %} diff --git a/v20.1/build-a-java-app-with-cockroachdb.md b/v20.1/build-a-java-app-with-cockroachdb.md index e7d9fbddadf..060878d7460 100644 --- a/v20.1/build-a-java-app-with-cockroachdb.md +++ b/v20.1/build-a-java-app-with-cockroachdb.md @@ -14,6 +14,8 @@ twitter: false This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver. +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [Build a Spring App with CockroachDB and JDBC](build-a-spring-app-with-cockroachdb-jdbc.html). {{site.data.alerts.end}} @@ -22,13 +24,9 @@ For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [B {% include {{page.version.version}}/app/before-you-begin.md %} -{{site.data.alerts.callout_danger}} -The examples on this page assume you are using a Java version <= 9. They do not work with Java 10. -{{site.data.alerts.end}} - ## Step 1. Install the Java JDBC driver -Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). +Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
diff --git a/v20.1/install-client-drivers.md b/v20.1/install-client-drivers.md index 57be37ded2a..df69c8516e6 100644 --- a/v20.1/install-client-drivers.md +++ b/v20.1/install-client-drivers.md @@ -130,11 +130,15 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe ## Drivers +{% include {{page.version.version}}/app/java-version-note.md %} + +{% include {{page.version.version}}/app/java-tls-note.md %} + ### JDBC **Support level:** Full -Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). +Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver. For a simple but complete "Hello World" example app, see [Build a Java App with CockroachDB and JDBC](build-a-java-app-with-cockroachdb.html). diff --git a/v20.2/build-a-java-app-with-cockroachdb-hibernate.md b/v20.2/build-a-java-app-with-cockroachdb-hibernate.md index 657bdd0d069..fe121dbd79d 100644 --- a/v20.2/build-a-java-app-with-cockroachdb-hibernate.md +++ b/v20.2/build-a-java-app-with-cockroachdb-hibernate.md @@ -14,6 +14,8 @@ twitter: false This tutorial shows you how build a simple Java application with CockroachDB and the Hibernate ORM. +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For a sample app and tutorial that uses Spring Data JPA (Hibernate) and CockroachDB, see [Build a Spring App with CockroachDB and JPA](build-a-spring-app-with-cockroachdb-jpa.html). @@ -24,10 +26,6 @@ For another use of Hibernate with CockroachDB, see our [`examples-orms`](https:/ {% include {{page.version.version}}/app/before-you-begin.md %} -{{site.data.alerts.callout_danger}} -The examples on this page assume you are using a Java version <= 9. They do not work with Java 10. -{{site.data.alerts.end}} - ## Step 1. Install the Gradle build tool This tutorial uses the [Gradle build tool](https://gradle.org/) to get all dependencies for your application, including Hibernate. diff --git a/v20.2/build-a-java-app-with-cockroachdb-jooq.md b/v20.2/build-a-java-app-with-cockroachdb-jooq.md index deb85f3918c..cb10572d054 100644 --- a/v20.2/build-a-java-app-with-cockroachdb-jooq.md +++ b/v20.2/build-a-java-app-with-cockroachdb-jooq.md @@ -16,6 +16,8 @@ This tutorial shows you how build a simple Java application with CockroachDB and CockroachDB is supported in jOOQ [Professional and Enterprise editions](https://www.jooq.org/download/#databases). +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For another use of jOOQ with CockroachDB, see our [`examples-orms`](https://github.com/cockroachdb/examples-orms) repository. {{site.data.alerts.end}} @@ -48,10 +50,6 @@ For other ways to install Maven, see [its official documentation](https://maven. Download the free trial of jOOQ Professional or Enterprise edition from [jOOQ's website](https://www.jooq.org/download), and unzip the file. -{{site.data.alerts.callout_info}} -If you have Java 6, Java 8, or Java 11, go to [Download your jOOQ version](https://www.jooq.org/download/versions#trial), and download the free trial of jOOQ for your version of Java. -{{site.data.alerts.end}} - To install jOOQ to your machine's local Maven repository, run the `maven-install.sh` script included in the jOOQ install folder: {% include copy-clipboard.html %} diff --git a/v20.2/build-a-java-app-with-cockroachdb.md b/v20.2/build-a-java-app-with-cockroachdb.md index e7d9fbddadf..060878d7460 100644 --- a/v20.2/build-a-java-app-with-cockroachdb.md +++ b/v20.2/build-a-java-app-with-cockroachdb.md @@ -14,6 +14,8 @@ twitter: false This tutorial shows you how to build a simple Java application with CockroachDB and the Java JDBC driver. +{% include {{page.version.version}}/app/java-version-note.md %} + {{site.data.alerts.callout_success}} For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [Build a Spring App with CockroachDB and JDBC](build-a-spring-app-with-cockroachdb-jdbc.html). {{site.data.alerts.end}} @@ -22,13 +24,9 @@ For a sample app and tutorial that uses Spring Data JDBC and CockroachDB, see [B {% include {{page.version.version}}/app/before-you-begin.md %} -{{site.data.alerts.callout_danger}} -The examples on this page assume you are using a Java version <= 9. They do not work with Java 10. -{{site.data.alerts.end}} - ## Step 1. Install the Java JDBC driver -Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). +Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver.
diff --git a/v20.2/install-client-drivers.md b/v20.2/install-client-drivers.md index 18c3254635b..44f02ebcd40 100644 --- a/v20.2/install-client-drivers.md +++ b/v20.2/install-client-drivers.md @@ -128,13 +128,17 @@ For instructions on using peewee with CockroachDB, see the [CockroachDatabase pe
+{% include {{page.version.version}}/app/java-version-note.md %} + +{% include {{page.version.version}}/app/java-tls-note.md %} + ## Drivers ### JDBC **Support level:** Full -Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). +Download and set up the Java JDBC driver as described in the [official documentation](https://jdbc.postgresql.org/documentation/head/setup.html). We recommend using the latest PostgreSQL JDBC 42.2.x driver. For a simple but complete "Hello World" example app, see [Build a Java App with CockroachDB and JDBC](build-a-java-app-with-cockroachdb.html).