High performance reactive PostgreSQL client written in Java
APACHE-2.0 License
= Reactive Postgres Client
image:https://travis-ci.org/vietj/reactive-pg-client.svg?branch=master["Build Status",link="https://travis-ci.org/vietj/reactive-pg-client"]
IMPORTANT: The Reactive PostgreSQL Client has a new https://github.com/eclipse-vertx/vertx-sql-client/tree/3.8/vertx-pg-client[home], this project remains active for security fixes
This project has evolved to become the https://github.com/eclipse-vertx/vertx-sql-client[Reactive SQL Client] that provides support for PostgreSQL and MySQL.
This project will remain maintained for bug fixes.
== Features
LISTEN/NOTIFY
java.util.stream.Collector
row set transformation== Usage
Latest release is https://github.com/reactiverse/reactive-pg-client/blob/master/RELEASES.adoc[0.11.4].
To use the client, add the following dependency to the dependencies section of your build descriptor:
pom.xml
) for Vert.x 3.7.x:build.gradle
file) for Vert.x 3.7.x: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 result = ar.result(); System.out.println("Got " + result.size() + " results "); } else { System.out.println("Failure: " + ar.cause().getMessage()); }
== Integration / Usages
== Documentations
== Javadoc
== Pipelining
This client supports pipelining requests to the database which can give a significant performance improvement depending on the latency to the database and the type of queries your application is doing.
.100µs latency image::100µs-latency.png[]
.1ms latency image::1ms-latency.png[]
Such results have been produced using this https://github.com/vietj/pg-client-concurrency-benchmark[benchmark].
WARNING: The two results are not normalized, the 100µs latency executes the 5000 queries in about 300ms, the 1ms latency executes the 5000 queries in about 13 seconds.
== Supported Data Types
The Reactive Postgres Client currently supports the following data types
[cols="^,^,^,^,^", options="header"] |==== | _ 2+| Value 2+| 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.
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:
docker/postgres/resources/create-postgres.sql
creates the test dataTLSTest
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
TLSTest
with the specified Postgres with SSL enabled.s.PGSQL.nnnn
and nnnn
is the server's port number,=== 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. 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
mvn compile
to generate jekyll/guide/java/index.md
mvn site
to generate the javadoc in jekyll/apidocs
cd jekyll
docker-compose up