diff --git a/docs/content/preview/develop/build-apps/java/ycql-4.6.md b/docs/content/preview/develop/build-apps/java/ycql-4.6.md index 6a7cca465740..344d76f51253 100644 --- a/docs/content/preview/develop/build-apps/java/ycql-4.6.md +++ b/docs/content/preview/develop/build-apps/java/ycql-4.6.md @@ -24,6 +24,12 @@ type: docs YSQL - JDBC +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ycql.md b/docs/content/preview/develop/build-apps/java/ycql.md index 32813cb8141d..8d906aa1dd2f 100644 --- a/docs/content/preview/develop/build-apps/java/ycql.md +++ b/docs/content/preview/develop/build-apps/java/ycql.md @@ -24,6 +24,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ysql-ebean.md b/docs/content/preview/develop/build-apps/java/ysql-ebean.md index b5ebaa247e84..c1e043745e8a 100644 --- a/docs/content/preview/develop/build-apps/java/ysql-ebean.md +++ b/docs/content/preview/develop/build-apps/java/ysql-ebean.md @@ -25,6 +25,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ysql-hibernate.md b/docs/content/preview/develop/build-apps/java/ysql-hibernate.md index 4a982db6dcf1..61c8ae97b1f1 100644 --- a/docs/content/preview/develop/build-apps/java/ysql-hibernate.md +++ b/docs/content/preview/develop/build-apps/java/ysql-hibernate.md @@ -25,6 +25,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ysql-jdbc-ssl.md b/docs/content/preview/develop/build-apps/java/ysql-jdbc-ssl.md index aec20a9a4c65..3cfd3ddee83d 100644 --- a/docs/content/preview/develop/build-apps/java/ysql-jdbc-ssl.md +++ b/docs/content/preview/develop/build-apps/java/ysql-jdbc-ssl.md @@ -24,6 +24,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ysql-jdbc.md b/docs/content/preview/develop/build-apps/java/ysql-jdbc.md index 5a02031466a7..bfe21f432dac 100644 --- a/docs/content/preview/develop/build-apps/java/ysql-jdbc.md +++ b/docs/content/preview/develop/build-apps/java/ysql-jdbc.md @@ -24,6 +24,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ysql-sdyb.md b/docs/content/preview/develop/build-apps/java/ysql-sdyb.md index 0e4130df62e5..499d3d0cbf02 100644 --- a/docs/content/preview/develop/build-apps/java/ysql-sdyb.md +++ b/docs/content/preview/develop/build-apps/java/ysql-sdyb.md @@ -25,6 +25,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ysql-spring-data.md b/docs/content/preview/develop/build-apps/java/ysql-spring-data.md index eaf19ed00a20..f44104844d73 100644 --- a/docs/content/preview/develop/build-apps/java/ysql-spring-data.md +++ b/docs/content/preview/develop/build-apps/java/ysql-spring-data.md @@ -24,6 +24,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/develop/build-apps/java/ysql-vertx-pg-client.md b/docs/content/preview/develop/build-apps/java/ysql-vertx-pg-client.md new file mode 100644 index 000000000000..0852df123b22 --- /dev/null +++ b/docs/content/preview/develop/build-apps/java/ysql-vertx-pg-client.md @@ -0,0 +1,223 @@ +--- +title: Build a Java application that uses YSQL +headerTitle: Build a Java application +linkTitle: More examples +description: Build a sample Java application with the Vertx PG Client and use the YSQL API to connect to and interact with YugabyteDB. +menu: + preview: + parent: cloud-java + identifier: java-10 + weight: 550 +type: docs +--- + + + +[Vertx PG Client](https://vertx.io/docs/vertx-pg-client/java/) is the client for PostgreSQL with simple APIs to communicate with the database. It is a reactive and non-blocking client for handling the database connections with a single threaded API. + +Since YugabyteDB is wire compatible with PostgreSQL, Vertx PG Client works with YugabyteDB as well. + +## Prerequisites + +This tutorial assumes that: + +- YugabyteDB up and running. Download and install the latest version of YugabyteDB by following the steps in [Quick start](../../../../quick-start/). +{{< note title="Note" >}} +The `executeBatch()` API of the Vertx PG Client is supported in the YugabyteDB version - `2.15.2.0-b0` onwards. +{{< /note >}} +- Java Development Kit (JDK) 1.8, or later, is installed. +- [Apache Maven](https://maven.apache.org/index.html) 3.3 or later, is installed. + +## Create and configure the Java project + +1. Create a project called "vertx-pg-example". + + ```sh + $ mvn archetype:generate \ + -DgroupId=com.yugabyte \ + -DartifactId=vertx-pg-example \ + -DarchetypeArtifactId=maven-archetype-quickstart \ + -DinteractiveMode=false + + $ cd vertx-pg-example + ``` +1. Add the following properties in the `pom.xml` file within the `` element. + + ```xml + + 1.8 + 1.8 + + ``` + +1. Add the following dependency for the Vertx PG Client within the `` element in the `pom.xml` file. + + ```xml + + io.vertx + vertx-pg-client + 4.3.2 + + ``` + +1. Install the added dependency. + + ```sh + $ mvn install + ``` + +## Create the sample Java application + +1. Copy the following Java code to a new file `src/main/java/com/yugabyte/vertxPgExample.java`: + + ```java + package com.yugabyte; + + import io.vertx.core.Promise; + import io.vertx.core.Vertx; + import io.vertx.pgclient.PgConnectOptions; + import io.vertx.pgclient.PgPool; + import io.vertx.sqlclient.PoolOptions; + import io.vertx.sqlclient.Tuple; + import io.vertx.sqlclient.Row; + import io.vertx.sqlclient.RowStream; + + public class vertxPgExample { + public static void main(String[] args) { + + PgConnectOptions options = new PgConnectOptions() + .setPort(5433) + .setHost("127.0.0.1") + .setDatabase("yugabyte") + .setUser("yugabyte") + .setPassword("yugabyte"); + + Vertx vertx = Vertx.vertx(); + // creating the PgPool with configuration as option and maxsize 10. + PgPool pool = PgPool.pool(vertx, options, new PoolOptions().setMaxSize(10)); + + //getting a connection from the pool and running the example on that + pool.getConnection().compose(connection -> { + Promise promise = Promise.promise(); + // create a test table + connection.query("create table test(id int primary key, name text)").execute() + .compose(v -> { + // insert some test data + return connection.query("insert into test values (1, 'Hello'), (2, 'World'), (3,'Example'), (4, 'Vertx'), (5, 'Yugabyte')").execute(); + }) + .compose(v -> { + // prepare the query + return connection.prepare("select * from test order by id"); + }) + .map(preparedStatement -> { + // create a stream for the prepared statement + return preparedStatement.createStream(50, Tuple.tuple()); + }) + .onComplete(ar -> { + if (ar.succeeded()) { + RowStream stream = ar.result(); + stream + .exceptionHandler(promise::fail) + .endHandler(promise::complete) + .handler(row -> System.out.println(row.toJson())); // Printing each row as JSON + } else { + promise.fail(ar.cause()); + } + }); + return promise.future().onComplete(v -> { + // close the connection + connection.close(); + }); + }).onComplete(ar -> { + if (ar.succeeded()) { + System.out.println("Example ran successfully!"); + } else { + ar.cause().printStackTrace(); + } + }); + + } + } + ``` + +1. Run the program. + + ```sh + $ mvn -q package exec:java -DskipTests -Dexec.mainClass=com.yugabyte.vertxPgExample + ``` + + You should see the following as the output: + + ```output + {"id":1,"name":"Hello"} + {"id":2,"name":"World"} + {"id":3,"name":"Example"} + {"id":4,"name":"Vertx"} + {"id":5,"name":"Yugabyte"} + Example ran successfully! + ``` +## Limitation + +[Pub/sub](https://vertx.io/docs/vertx-pg-client/java/#_pubsub) feature of Vertx PG client is currently not supported with YugabyteDB. This limitation will go away when `LISTEN`/`NOTIFY` support is added to YugabyteDB. See [GitHub issue](https://github.com/yugabyte/yugabyte-db/issues/1872). + diff --git a/docs/content/preview/develop/build-apps/java/ysql-yb-jdbc.md b/docs/content/preview/develop/build-apps/java/ysql-yb-jdbc.md index fb5ad70bbd9a..21b77a763e39 100644 --- a/docs/content/preview/develop/build-apps/java/ysql-yb-jdbc.md +++ b/docs/content/preview/develop/build-apps/java/ysql-yb-jdbc.md @@ -30,6 +30,12 @@ type: docs YSQL - JDBC
    • +
  • + + + YSQL - Vertx PG Client + +
  • diff --git a/docs/content/preview/reference/drivers/ysql-client-drivers.md b/docs/content/preview/reference/drivers/ysql-client-drivers.md index 956b5699c0e0..58f204eaf457 100644 --- a/docs/content/preview/reference/drivers/ysql-client-drivers.md +++ b/docs/content/preview/reference/drivers/ysql-client-drivers.md @@ -150,6 +150,14 @@ To download binary JAR files, go to [PostgreSQL JDBC driver – Downloads](https To get the latest versions for projects using [Apache Maven](https://maven.apache.org), see [Maven Central Repository Search](https://search.maven.org/artifact/org.postgresql/postgresql/42.2.14.jre7/jar). +### Vertx PG Client + +[Vertx PG Client](https://vertx.io/docs/vertx-pg-client/java/) is the client for PostgreSQL with simple APIs to communicate with the database. It is a reactive and non-blocking client for handling the database connections with a single threaded API. + +For a tutorial on building a sample Java application with the Vertx PG Client, see [Build a Java application](../../../develop/build-apps/java/ysql-vertx-pg-client/). + +To get the latest versions for projects using [Apache Maven](https://maven.apache.org), see [Maven Central Repository of Vertx PG Client](https://mvnrepository.com/artifact/io.vertx/vertx-pg-client). + ## Node.JS ### node-postgres