diff --git a/docs/_include/links.md b/docs/_include/links.md index 5c2eafeb..21385cd8 100644 --- a/docs/_include/links.md +++ b/docs/_include/links.md @@ -35,6 +35,7 @@ [Executable stack with Apache Kafka, Apache Flink, and CrateDB]: https://github.com/crate/cratedb-examples/tree/main/framework/flink/kafka-jdbcsink-java [Geospatial Data Model]: https://cratedb.com/data-model/geospatial [Geospatial Database]: https://cratedb.com/geospatial-spatial-database +[Hibernate]: https://hibernate.org/ [HNSW]: https://en.wikipedia.org/wiki/Hierarchical_navigable_small_world [HNSW paper]: https://arxiv.org/pdf/1603.09320 [HoloViews]: https://www.holoviews.org/ @@ -45,6 +46,8 @@ [inverted index]: https://en.wikipedia.org/wiki/Inverted_index [JDBC]: https://en.wikipedia.org/wiki/Java_Database_Connectivity [JOIN]: inv:crate-reference#sql_joins +[jOOQ]: https://www.jooq.org/ +[JPA]: https://en.wikipedia.org/wiki/Jakarta_Persistence [JSON Database]: https://cratedb.com/solutions/json-database [kNN]: https://en.wikipedia.org/wiki/K-nearest_neighbor_algorithm [LangChain and CrateDB: Code Examples]: https://github.com/crate/cratedb-examples/tree/main/topic/machine-learning/langchain diff --git a/docs/_include/logos.md b/docs/_include/logos.md new file mode 100644 index 00000000..de6647b0 --- /dev/null +++ b/docs/_include/logos.md @@ -0,0 +1,17 @@ + + + +[CrateDB home]: https://cratedb.com/ +[CrateDB logo]: https://avatars.githubusercontent.com/u/4048232?s=200&v=4 +[Flink home]: https://flink.apache.org/ +[Flink logo]: https://flink.apache.org/img/logo/png/50/color_50.png +[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 +[Spark logo]: https://www.vectorlogo.zone/logos/apache_spark/apache_spark-icon.svg +[Spark home]: https://spark.apache.org/ +[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 diff --git a/docs/connect/index.md b/docs/connect/index.md index 3912e98a..c22c8f1a 100644 --- a/docs/connect/index.md +++ b/docs/connect/index.md @@ -176,7 +176,7 @@ application :maxdepth: 1 :hidden: -java +java/index javascript php python diff --git a/docs/connect/java.md b/docs/connect/java.md deleted file mode 100644 index 51ea397a..00000000 --- a/docs/connect/java.md +++ /dev/null @@ -1,191 +0,0 @@ -(connect-java)= - -# Java - -:::{include} /_include/links.md -::: - -:::{div} sd-text-muted -Java applications mostly use JDBC to connect to CrateDB. -::: - -::: -[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://`. -::: - -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. - -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 -::: - -```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; - -public class Main { - public static void main(String[] args) { - try { - 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 - ); - - Statement statement = conn.createStatement(); - ResultSet resultSet = statement.executeQuery("SELECT name FROM sys.cluster"); - resultSet.next(); - String name = resultSet.getString("name"); - - System.out.println(name); - } catch (SQLException e) { - e.printStackTrace(); - } - } -} -``` -::: - -## 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. -::: - -## See also - -For testing Java applications against CrateDB, see also documentation -about {ref}`java-junit` and {ref}`testcontainers`. diff --git a/docs/connect/java/_jdbc_example.md b/docs/connect/java/_jdbc_example.md new file mode 100644 index 00000000..171d5117 --- /dev/null +++ b/docs/connect/java/_jdbc_example.md @@ -0,0 +1,13 @@ +--- +orphan: true +--- +:::{card} +:link: https://github.com/crate/cratedb-examples/tree/main/by-language/java-jdbc +:link-type: url +:width: 50% +{material-regular}`play_arrow;2em` +Connect to CrateDB using JDBC. ++++ +Demonstrates a basic example using both the vanilla PostgreSQL JDBC Driver +and the CrateDB JDBC Driver. +::: diff --git a/docs/connect/java/cratedb-jdbc.md b/docs/connect/java/cratedb-jdbc.md new file mode 100644 index 00000000..f91f9fec --- /dev/null +++ b/docs/connect/java/cratedb-jdbc.md @@ -0,0 +1,154 @@ +:::{include} /_include/logos.md +::: + +(crate-jdbc)= +(cratedb-jdbc)= + +# CrateDB JDBC + +```{div} .float-right +[![Java: JDBC, QA](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-maven.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-maven.yml) +``` +```{div} .clearfix +``` + +:::{include} /_include/links.md +::: + +:::{div} sd-text-muted +Connect to CrateDB using CrateDB JDBC. +::: + +:::{rubric} About +::: + +:::{div} +The [CrateDB JDBC Driver] is an open-source JDBC driver written in +Pure Java (Type 4), which communicates using the PostgreSQL native +network protocol. CrateDB JDBC needs Java >= 11. +::: + +:::{rubric} Synopsis +::: + +`example.java` +```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(); + +} +``` + +:::{rubric} CrateDB Cloud +::: + +For connecting to CrateDB Cloud, use the `sslmode=require` parameter, +and replace username, password, and hostname with values matching +your environment. +```java +properties.put("user", "admin"); +properties.put("password", "password"); +Connection conn = DriverManager.getConnection( + "jdbc:crate://testcluster.cratedb.net:5432/doc?sslmode=require", + properties +); +``` + +## Install + +:::{rubric} Download +::: + +:::{card} +:link: https://cratedb.com/docs/jdbc/en/latest/getting-started.html#installation +:link-type: url +{material-regular}`download;2em` +Navigate to the CrateDB JDBC Driver installation page. +::: + +:::{card} +:link: https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar +:link-type: url +{material-regular}`download;2em` +Directly download the recommended `crate-jdbc-standalone-2.7.0.jar`. +::: + +:::{card} Linux / macOS +```shell +wget https://repo1.maven.org/maven2/io/crate/crate-jdbc-standalone/2.7.0/crate-jdbc-standalone-2.7.0.jar +``` +::: +:::{card} Windows +```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 +``` +::: + +:::{rubric} Maven `pom.xml` +::: +```xml + + + io.crate + crate-jdbc + 2.7.0 + + +``` + +:::{rubric} Gradle `build.gradle` +::: +```groovy +repositories { + mavenCentral() +} +dependencies { + implementation 'io.crate:crate-jdbc:2.7.0' +} +``` + +## Run + +:::{rubric} Quickstart example +::: + +Create the file `example.java` including the synopsis code shared above. + +:::{include} ../_cratedb.md +::: +Invoke program. This example needs Java >= 25 ([JEP 512]), +with earlier versions please use the full example. +```shell +java -cp crate-jdbc-standalone-2.7.0.jar example.java +``` + +:::{rubric} Full example +::: + +:::{include} _jdbc_example.md +::: + + +[JEP 512]: https://openjdk.org/jeps/512 diff --git a/docs/connect/java/hibernate.md b/docs/connect/java/hibernate.md new file mode 100644 index 00000000..72da41ab --- /dev/null +++ b/docs/connect/java/hibernate.md @@ -0,0 +1,27 @@ +(jpa)= +(hibernate)= +(panache)= +(quarkus)= + +# Hibernate / JPA + +:::{include} /_include/links.md +::: + +:::{div} +[Hibernate] is the top dog ORM for Java, supporting a range of databases, +including PostgreSQL. [JPA], or Jakarta Persistence API (formerly Java +Persistence API), is a Java specification that simplifies the process of +mapping Java objects to relational databases. +::: + +:::{card} +:link: https://github.com/crate/cratedb-examples/tree/main/by-language/java-quarkus-panache +:link-type: url +:width: 50% +{material-regular}`play_arrow;2em` +Connect to CrateDB using JPA and Panache. ++++ +How CrateDB can be utilized with Quarkus in a very intuitive way +using the Hibernate ORM deriving from PostgreSQL. +::: diff --git a/docs/connect/java/index.md b/docs/connect/java/index.md new file mode 100644 index 00000000..c31aa2db --- /dev/null +++ b/docs/connect/java/index.md @@ -0,0 +1,118 @@ +(java)= +(connect-java)= + +# Java + +:::{include} /_include/links.md +::: +:::{include} /_include/logos.md +::: + +:::{div} sd-text-muted +Connect to CrateDB and CrateDB Cloud from Java. +::: + +## JDBC + +:::{div} +[JDBC] is the standard Java API that provides a common interface for accessing +databases in Java. +::: + +:::{rubric} Driver options +::: + +Choose one of two JDBC drivers: + +- {ref}`postgresql-jdbc` — `jdbc:postgresql://` +- {ref}`cratedb-jdbc` — `jdbc:crate://` + +Prefer the PostgreSQL JDBC driver first, it’s often already in your classpath +and works out of the box. If your application or framework emits +PostgreSQL‑specific SQL that CrateDB doesn’t support, switch to the CrateDB +JDBC driver for full CrateDB dialect support and smoother integration. + +For example, the JDBC catalog integration with Apache Flink depends on CrateDB +JDBC, in this case we recommend to use that driver depending on your needs. + +The {ref}`CrateDB JDBC internals ` page includes more information +about compatibility and differences between the two driver variants, +and more details about the CrateDB JDBC Driver. + +:::{rubric} Adapters and drivers +::: + +:::::{grid} 2 2 2 3 +:gutter: 2 +:padding: 0 + +::::{grid-item-card} ![PostgreSQL logo][PostgreSQL logo]{height=40px}   PostgreSQL JDBC +:link: postgresql-jdbc +:link-type: ref +:link-alt: PostgreSQL JDBC (pgJDBC) +The PostgreSQL JDBC driver. +:::: + +::::{grid-item-card} ![CrateDB logo][CrateDB logo]{height=40px}   CrateDB JDBC +:link: cratedb-jdbc +:link-type: ref +:link-alt: CrateDB JDBC +The CrateDB JDBC driver. +:::: + +::::{grid-item-card} ![Hibernate logo][Hibernate logo]{height=40px}   Hibernate +:link: hibernate +:link-type: ref +:link-alt: Hibernate with CrateDB +A Hibernate example using Quarkus/Panache. +:::: + +::::{grid-item-card} ![jOOQ logo][jOOQ logo]{height=40px}   jOOQ +:link: jooq +:link-type: ref +:link-alt: jOOQ with CrateDB +A jOOQ example. +:::: + +::::{grid-item-card} {material-outlined}`verified;2em`   Software testing +:link: java-testing +:link-type: ref +:link-alt: Software testing with CrateDB and Java +JUnit support and Testcontainers for CrateDB. +:::: + +::::: + +:::{rubric} Frameworks +::: + +:::::{grid} 2 2 2 3 +:gutter: 2 +:padding: 0 + +::::{grid-item-card} ![Flink logo][Flink logo]{height=40px}   Apache Flink +:link: flink +:link-type: ref +:link-alt: Apache Flink and CrateDB +Use CrateDB with Apache Flink. +:::: + +::::{grid-item-card} ![Spark logo][Spark logo]{height=40px}   Apache Spark +:link: spark +:link-type: ref +:link-alt: Apache Spark and CrateDB +Use CrateDB with Apache Spark. +:::: + +::::: + + +:::{toctree} +:maxdepth: 1 +:hidden: +postgresql-jdbc +cratedb-jdbc +hibernate +jooq +testing +::: diff --git a/docs/connect/java/jooq.md b/docs/connect/java/jooq.md new file mode 100644 index 00000000..85357aa2 --- /dev/null +++ b/docs/connect/java/jooq.md @@ -0,0 +1,43 @@ +(jooq)= + +# jOOQ + +:::{include} /_include/links.md +::: + +```{div} .float-right .text-right +[![Java jOOQ](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-jooq.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-jooq.yml) +``` +```{div} .clearfix +``` + +:::{div} +[jOOQ] is an internal DSL and source code generator, modelling the SQL +language as a type-safe Java API to help you write better SQL. +::: + +```java +// Fetch records, with filtering and sorting. +Result result = db.select() + .from(AUTHOR) + .where(AUTHOR.NAME.like("Ja%")) + .orderBy(AUTHOR.NAME) + .fetch(); + +// Iterate and display records. +for (Record record : result) { + Integer id = record.getValue(AUTHOR.ID); + String name = record.getValue(AUTHOR.NAME); + System.out.println("id: " + id + ", name: " + name); +} +``` + +:::{card} +:link: https://github.com/crate/cratedb-examples/tree/main/by-language/java-jooq +:link-type: url +:width: 50% +{material-regular}`play_arrow;2em` +Connect to CrateDB using jOOQ. ++++ +Java jOOQ demo application with CrateDB using PostgreSQL JDBC. +::: diff --git a/docs/connect/java/postgresql-jdbc.md b/docs/connect/java/postgresql-jdbc.md new file mode 100644 index 00000000..abbe5ae4 --- /dev/null +++ b/docs/connect/java/postgresql-jdbc.md @@ -0,0 +1,152 @@ +:::{include} /_include/logos.md +::: + +(pgjdbc)= +(postgresql-jdbc)= + +# PostgreSQL JDBC + +```{div} .float-right +[![Java: JDBC, QA](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-maven.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-maven.yml) +``` +```{div} .clearfix +``` + +:::{include} /_include/links.md +::: + +:::{div} sd-text-muted +Connect to CrateDB using PostgreSQL JDBC. +::: + +:::{rubric} About +::: + +:::{div} +The [PostgreSQL JDBC Driver] is an open-source JDBC driver written in +Pure Java (Type 4), which communicates using the PostgreSQL native +network protocol. PostgreSQL JDBC needs Java >= 8. +::: + +:::{rubric} Synopsis +::: + +`example.java` +```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(); + +} +``` + +:::{rubric} CrateDB Cloud +::: + +For connecting to CrateDB Cloud, use the `sslmode=require` parameter, +and replace username, password, and hostname with values matching +your environment. +```java +properties.put("user", "admin"); +properties.put("password", "password"); +Connection conn = DriverManager.getConnection( + "jdbc:postgresql://testcluster.cratedb.net:5432/doc?sslmode=require", + properties +); +``` + +## Install + +:::{rubric} Download +::: + +:::{card} +: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-type: url +{material-regular}`download;2em` +Directly download the recommended `postgresql-42.7.8.jar`. +::: + +:::{card} Linux / macOS +```shell +wget https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.8/postgresql-42.7.8.jar +``` +::: +:::{card} Windows +```powershell +Invoke-WebRequest https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.8/postgresql-42.7.8.jar -OutFile postgresql-42.7.8.jar +``` +::: + +:::{rubric} Maven `pom.xml` +::: +```xml + + org.postgresql + postgresql + 42.7.8 + +``` + +:::{rubric} Gradle `build.gradle` +::: +```groovy +repositories { + mavenCentral() +} +dependencies { + implementation 'org.postgresql:postgresql:42.7.8' +} +``` + +## Run + +:::{rubric} Quickstart example +::: + +Create the file `example.java` including the synopsis code shared above. + +:::{include} ../_cratedb.md +::: +Invoke program. This example needs Java >= 25 ([JEP 512]), +with earlier versions please use the full example. +```shell +java -cp postgresql-42.7.8.jar example.java +``` + +:::{rubric} Full example +::: + +:::{include} _jdbc_example.md +::: + + +[JEP 512]: https://openjdk.org/jeps/512 diff --git a/docs/connect/java/testing.md b/docs/connect/java/testing.md new file mode 100644 index 00000000..13fde574 --- /dev/null +++ b/docs/connect/java/testing.md @@ -0,0 +1,80 @@ +:::{include} /_include/logos.md +::: + +(java-testing)= + +# Software testing + +```{div} .float-right +[![JUnit logo][JUnit logo]{height=60px loading=lazy}][JUnit home] +[![Testcontainers logo][Testcontainers logo]{height=60px loading=lazy}][Testcontainers for Java] +``` +:::{div} sd-text-muted +Testing Java applications against CrateDB. +::: +```{div} .clearfix +``` + +(junit)= +(java-junit)= +## JUnit + +The popular [JUnit] framework is supported by *CrateDB Java Testing Classes*. +The package includes `CrateTestServer` and `CrateTestCluster` classes for use +as [JUnit external resources]. Both classes download and start CrateDB before +test execution, and stop CrateDB afterward. + +:::::{grid} +::::{grid-item} + +:Package: `io.crate:crate-testing:0.12.1` +:Download: [io.crate:crate-testing] (Maven Central) +:Repository: [crate-java-testing] +:CI status: [![Java: JDBC, QA](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-maven.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-java-maven.yml) +:::: +::::{grid-item} +:::{card} Using JUnit "crate-testing" with CrateDB +:link: https://github.com/crate/cratedb-examples/tree/main/by-language/java-qa +This example project uses the `io.crate:crate-testing` package and includes a +corresponding project setup that you can use right away to get started. +::: +:::: +::::: + +(testcontainers-java)= +## Testcontainers + +[Testcontainers] is an open-source framework for providing throwaway, +lightweight instances of databases, message brokers, web browsers, or +just about anything that can run in a Docker container. +CrateDB provides Testcontainers implementations for both Java and Python +which are using its {ref}`OCI container image `. + +:::::{grid} +::::{grid-item} + +:Package: `org.testcontainers:testcontainers-cratedb:2.0.1` +:Download: [org.testcontainers:testcontainers-cratedb] (Maven Central) +:Repository: [testcontainers-cratedb sources] +:Documentation: [Testcontainers CrateDB Module] +:CI status: [![Testcontainers for Java](https://github.com/crate/cratedb-examples/actions/workflows/testing-testcontainers-java.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/testing-testcontainers-java.yml) +:::: +::::{grid-item} +:::{card} Using "Testcontainers for Java" with CrateDB +:link: https://github.com/crate/cratedb-examples/tree/main/testing/testcontainers/java +This example project uses the `testcontainers-cratedb` package and includes a +corresponding project setup that you can use right away to get started. +::: +:::: +::::: + + +[crate-java-testing]: https://github.com/crate/crate-java-testing +[JUnit]: https://junit.org/ +[JUnit external resources]: https://github.com/junit-team/junit4/wiki/Rules#externalresource-rules +[Testcontainers]: https://testcontainers.com/ +[Testcontainers CrateDB Module]: https://java.testcontainers.org/modules/databases/cratedb/ +[testcontainers-cratedb sources]: https://github.com/testcontainers/testcontainers-java/tree/main/modules/cratedb/src/main/java/org/testcontainers/cratedb + +[io.crate:crate-testing]: https://repo1.maven.org/maven2/io/crate/crate-testing/ +[org.testcontainers:testcontainers-cratedb]: https://repo1.maven.org/maven2/org/testcontainers/testcontainers-cratedb/ diff --git a/docs/install/container/index.md b/docs/install/container/index.md index 847c0bc3..9d8872ec 100644 --- a/docs/install/container/index.md +++ b/docs/install/container/index.md @@ -1,3 +1,4 @@ +(oci)= (install-container)= # Container setup diff --git a/docs/topic/testing/index.md b/docs/topic/testing/index.md index 17a5fb31..139ae22c 100644 --- a/docs/topic/testing/index.md +++ b/docs/topic/testing/index.md @@ -1,27 +1,35 @@ (testing)= # Software Testing +:::{include} /_include/logos.md +::: + :::{div} sd-text-muted Test frameworks and libraries that support software integration testing with CrateDB. ::: -(java-junit)= -## Java JUnit - -The popular [JUnit] framework is supported by *CrateDB Java Testing Classes*, -provided per [io.crate:crate-testing] package available on Maven Central. -Its source code is maintained within the [crate-java-testing] repository on GitHub. +## Java -The package includes `CrateTestServer` and `CrateTestCluster` classes for use -as [JUnit external resources]. Both classes download and start CrateDB before -test execution, and stop CrateDB afterwards. +:::::{grid} 2 2 2 3 +:gutter: 2 +:padding: 0 -This example project includes a corresponding setup that you can use right away -to get started. +::::{grid-item-card} ![JUnit logo][JUnit logo]{height=40px loading=lazy}   JUnit +:link: junit +:link-type: ref +:link-alt: Use JUnit with CrateDB +Use JUnit with CrateDB. +:::: -- [Using "crate-testing" with CrateDB and JUnit] +::::{grid-item-card} ![Testcontainers logo][Testcontainers logo]{height=40px loading=lazy}   Testcontainers for Java +:link: testcontainers-java +:link-type: ref +:link-alt: Use Testcontainers for Java with CrateDB +Use Testcontainers for Java with CrateDB. +:::: +::::: (python-pytest)= ## Python pytest @@ -59,24 +67,17 @@ just about anything that can run in a Docker container. CrateDB provides Testcontainers implementations for both Java and Python. -- [Using "Testcontainers for Java" with CrateDB] - [Using "Testcontainers for Python" with CrateDB and pytest] - [Using "Testcontainers for Python" with CrateDB and unittest] [cr8]: https://pypi.org/project/cr8/ -[crate-java-testing]: https://github.com/crate/crate-java-testing -[io.crate:crate-testing]: https://repo1.maven.org/maven2/io/crate/crate-testing/ -[JUnit]: https://en.wikipedia.org/wiki/JUnit -[JUnit external resources]: https://github.com/junit-team/junit4/wiki/Rules#externalresource-rules [pytest]: https://docs.pytest.org/ [pytest-cratedb]: https://pypi.org/project/pytest-cratedb/ [run-crate]: https://pypi.org/project/cr8/#run-crate [Testcontainers]: https://testcontainers.com/ [unittest]: https://docs.python.org/3/library/unittest.html [Using "cr8" test layers with CrateDB and unittest]: https://github.com/crate/cratedb-examples/tree/main/testing/native/python-unittest -[Using "crate-testing" with CrateDB and JUnit]: https://github.com/crate/cratedb-examples/tree/main/by-language/java-qa [Using "pytest-cratedb" with CrateDB and pytest]: https://github.com/crate/cratedb-examples/tree/main/testing/native/python-pytest -[Using "Testcontainers for Java" with CrateDB]: https://github.com/crate/cratedb-examples/tree/main/testing/testcontainers/java [Using "Testcontainers for Python" with CrateDB and pytest]: https://github.com/crate/cratedb-examples/tree/main/testing/testcontainers/python-pytest [Using "Testcontainers for Python" with CrateDB and unittest]: https://github.com/crate/cratedb-examples/tree/main/testing/testcontainers/python-unittest