File: README — Documentation by YARD 0.8.7.6

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
Request cancellation

Usage

Latest release is 0.11.1.

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.1</version>
</dependency>

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

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

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.
Micronaut: supports reactive and non-blocking client to connect to Postgres using reactive-pg-client, allowing to handle many database connections with a single thread.

Documentations

Javadoc

Javadoc

Supported Data Types

The Reactive Postgres Client currently supports the following data types

_ Value Array

_	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[]`	✔

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.

You can change the version of the embedded Postgres by passing a property embedded.postgres.version like this:

> mvn test -Dembedded.postgres.version=9.6

The following versions of embedded Postgres are supported:

9.6
10.6 (default)
11.1 (not supported on Linux)

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 add some properties for testing:

> mvn test -Dconnection.uri=postgres://$username:$password@$host:$port/$database -Dtls.connection.uri=postgres://$username:$password@$host:$port/$database -Dunix.socket.directory=$path

connection.uri(mandatory): configure the client to connect the specified database
tls.connection.uri(mandatory): configure the client to run TLSTest with the specified Postgres with SSL enabled
unix.socket.directory(optional): the single unix socket directory(multiple socket directories are not supported) to test Unix domain socket with a specified database, domain socket tests will be skipped if this property is not specified (Note: Make sure you can access the unix domain socket with this directory under your host machine)
unix.socket.port(optional): unix socket file is named .s.PGSQL.nnnn and nnnn is the server’s port number, this property is mostly used when you test with Docker, when you publish your Postgres container port other than 5432 in your host but Postgres may actually listen on a different port in the container, you will then need this property to help you connect the Postgres with Unix domain socket

Testing with Docker

Run the Postgres containers with docker-compose:

> cd docker/postgres
> docker-compose up --build -V

Run tests:

> mvn test -Dconnection.uri=postgres://$username:$password@$host:$port/$database -Dtls.connection.uri=postgres://$username:$password@$host:$port/$database -Dunix.socket.directory=$path -Dunix.socket.port=$port

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