Reactive Postgres Client

• Simple API focusing on scalability and low overhead.

• Reactive and non blocking which able to handle many database connections with a single thread.

• Ranked #1 in the TechEmpower Benchmark Round 15 Single query benchmark.

Features

• Event driven

• Lightweight

• Built-in connection pooling

• Prepared queries caching

• Publish / subscribe using Postgres LISTEN/NOTIFY

• Batch and cursor support

• Row streaming

• java.util.stream.Collector row set transformation

• Command pipeling

• RxJava 1 and RxJava 2

• Direct memory to object without unnecessary copies

• Java 8 Date and Time

• SSL/TLS

• Unix domain socket

• HTTP/1.x CONNECT, SOCKS4a or SOCKS5 proxy

Usage

Latest release is 0.11.0.

To use the client, add the following dependency to the dependencies section of your build descriptor:

• Maven (in your pom.xml) for Vert.x 3.6.x:

<dependency>
  <groupId>io.reactiverse</groupId>
  <artifactId>reactive-pg-client</artifactId>
  <version>0.11.0</version>
</dependency>

• Gradle (in your build.gradle file) for Vert.x 3.6.x:

dependencies {
  compile 'io.reactiverse:reactive-pg-client:0.11.0'
}

If you are using Vertx 3.5.x you should use instead 0.10.9

Then the code is quite straightforward:

// Pool options
PgPoolOptions options = new PgPoolOptions()
  .setPort(5432)
  .setHost("the-host")
  .setDatabase("the-db")
  .setUser("user")
  .setPassword("secret")
  .setMaxSize(5);

// Create the client pool
PgPool client = PgClient.pool(options);

// A simple query
client.query("SELECT * FROM users WHERE id='julien'", ar -> {
  if (ar.succeeded()) {
    PgResult<Row> result = ar.result();
    System.out.println("Got " + result.size() + " results ");
  } else {
    System.out.println("Failure: " + ar.cause().getMessage());
  }

  // Now close the pool
  client.close();
});

Integration / Usages

• vertx-jooq: writing type safe queries and let them run at high speed using jOOQ, vertx and the reactive-pg-client.

Documentations

• Java docs

• Kotlin docs

• Groovy docs

• Ruby docs

• JavaScript docs

Javadoc

• Javadoc

Supported Data Types

The Reactive Postgres Client currently supports the following data types

_	Value		Array
Postgres	Java	Supported	JAVA	Supported
BOOLEAN	j.l.Boolean	✔	j.l.Boolean[]	✔
INT2	j.l.Short	✔	j.l.Short[]	✔
INT4	j.l.Integer	✔	j.l.Integer[]	✔
INT8	j.l.Long	✔	j.l.Long[]	✔
FLOAT4	j.l.Float	✔	j.l.Float[]	✔
FLOAT8	j.l.Double	✔	j.l.Double[]	✔
CHAR	j.l.Character	✔	j.l.Character[]	✔
VARCHAR	j.l.String	✔	j.l.String[]	✔
TEXT	j.l.String	✔	j.l.String[]	✔
ENUM	j.l.String	✔	j.l.String[]	✔
NAME	j.l.String	✔	j.l.String[]	✔
SERIAL2	j.l.Short	✔	invalid type	✕
SERIAL4	j.l.Integer	✔	invalid type	✕
SERIAL8	j.l.Long	✔	invalid type	✕
NUMERIC	i.r.p.data.Numeric	✔	i.r.p.data.Numeric[]	✔
UUID	j.u.UUID	✔	j.u.UUID[]	✔
DATE	j.t.LocalDate	✔	j.t.LocalDate[]	✔
TIME	j.t.LocalTime	✔	j.t.LocalTime[]	✔
TIMETZ	j.t.OffsetTime	✔	j.t.OffsetTime[]	✔
TIMESTAMP	j.t.LocalDateTime	✔	j.t.LocalDateTime[]	✔
TIMESTAMPTZ	j.t.OffsetDateTime	✔	j.t.OffsetDateTime[]	✔
INTERVAL	i.r.p.data.Interval	✔	i.r.p.data.Interval[]	✔
BYTEA	i.v.c.b.Buffer	✔	i.v.c.b.Buffer[]	✔
JSON	i.r.p.data.Json	✔	i.r.p.data.Json[]	✔
JSONB	i.r.p.data.Json	✔	i.r.p.data.Json[]	✔
POINT	i.r.p.data.Point	✔	i.r.p.data.Point[]	✔
LINE	i.r.p.data.Line	✔	i.r.p.data.Line[]	✔
LSEG	i.r.p.data.LineSegment	✔	i.r.p.data.LineSegment[]	✔
BOX	i.r.p.data.Box	✔	i.r.p.data.Box[]	✔
PATH	i.r.p.data.Path	✔	i.r.p.data.Path[]	✔
POLYGON	i.r.p.data.Polygon	✔	i.r.p.data.Polygon[]	✔
CIRCLE	i.r.p.data.Circle	✔	i.r.p.data.Circle[]	✔
UNKNOWN	j.l.String	✔	j.l.String[]	✔

The following types

MONEY, BIT, VARBIT, MACADDR, INET, CIDR, MACADDR8, XML, HSTORE, OID, VOID, TSQUERY, TSVECTOR

are not implemented yet (PR are welcome).

Snapshots

Snapshots are deploy in Sonatype OSS repository: https://oss.sonatype.org/content/repositories/snapshots/io/reactiverse/reactive-pg-client/

License

Apache License - Version 2.0

Developers

Testing

Out of the box, the test suite runs an embedded Postgres by default.

Testing with an external database

You can run tests with an external database:

• the script docker/postgres/resources/create-postgres.sql creates the test data

• the TLSTest expects the database to be configured with SSL with docker/postgres/resources/server.key / docker/postgres/resources/server.cert`

You need to override the default connection uri for testing:

> mvn test -Dconnection.uri=postgres://$username:$password@$host:$port/$database

Note	unix domain sockets are not testable (yet).

Testing with Docker

Create and run the following docker image:

> docker build -t test/postgres docker/postgres
> docker run --rm --name test-postgres -p 5432:5432 test/postgres

Run tests:

> mvn test -Dconnection.uri=postgres://postgres:postgres@localhost/postgres

Note	unix domain sockets are not testable (yet).

Documentation

The online and published documentation is in /docs and is served by GitHub pages with Jekyll.

You can find the actual guide source in [src/main/docs/index.md](src/main/docs/index.md). At compilation time, this source generates the jekyll/guide/java/index.md.

The current documentation is in /jekyll and can be preview using Docker and your browser

• generate the documentation

  • mvn compile to generate jekyll/guide/java/index.md

  • mvn site to generate the javadoc in jekyll/apidocs

• run Jekyll

  • cd jekyll

  • docker-compose up

• open your browser at http://localhost:4000