Reactive Relational Database Connectivity PostgreSQL Implementation

This project contains the PostgreSQL implementation of the R2DBC SPI. This implementation is not intended to be used directly, but rather to be used as the backing implementation for a humane client library to delegate to.

This driver provides the following features:

• Login with username/password or implicit trust
• Explict transactions
• Execution of prepared statements with bindings
• Execution of batch statements without bindings
• Read and write support for all data types except LOB types (e.g. BLOB, CLOB)

Next steps:

• TLS
• Multi-dimensional arrays
• Notifications
• SCRAM authentication
• Binary data transfer

Maven

Both milestone and snapshot artifacts (library, source, and javadoc) can be found in Maven repositories.

<dependency>
  <groupId>io.r2dbc</groupId>
  <artifactId>r2dbc-postgresql</artifactId>
  <version>1.0.0.M5</version>
</dependency>

Artifacts can be found at the following repositories.

Repositories

<repository>
    <id>spring-snapshots</id>
    <name>Spring Snapshots</name>
    <url>https://repo.spring.io/snapshot</url>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

<repository>
    <id>spring-milestones</id>
    <name>Spring Milestones</name>
    <url>https://repo.spring.io/milestone</url>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
</repository>

Usage

Configuration of the ConnectionFactory can be accomplished in two ways:

Connection Factory Discovery

ConnectionFactory connectionFactory = ConnectionFactories.get(ConnectionFactoryOptions.builder()
   .option(DRIVER, "postgresql")
   .option(HOST, "...")
   .option(PORT, "...")  // optional, defaults to 5432
   .option(USER, "...")
   .option(PASSWORD, "...")
   .option(DATABASE, "...")  // optional
   .build());

Publisher<? extends Connection> connectionPublisher = connectionFactory.create();

// Alternative: Creating a Mono using Project Reactor
Mono<Connection> connectionMono = Mono.from(connectionFactory.create());

Supported Connection Factory Discovery options:

Option	Description
driver	Must be postgresql
host	Server hostname to connect to
port	Server port to connect to. Defaults to 1443. (Optional)
username	Login username
password	Login password
database	Database to select. (Optional)
applicationName	The name of the application connecting to the database. Defaults to r2dbc-postgresql. (Optional)
schema	The schema to set. (Optional)

Programmatic

ConnectionFactory connectionFactory = new PostgresqlConnectionFactory(PostgresqlConnectionConfiguration.builder()
    .host("...")
    .port("...").  // optional, defaults to 5432
    .username("...")
    .password("...")
    .database("...")  // optional
    .build());

Mono<Connection> connection = connectionFactory.create();

PostgreSQL uses index parameters that are prefixed with $. The following SQL statement makes use of parameters:

INSERT INTO person (id, first_name, last_name) VALUES ($1, $2, $3)

Parameters are referenced using the same identifiers when binding these:

connection
    .createStatement("INSERT INTO person (id, first_name, last_name) VALUES ($1, $2, $3)")
    .bind("$1", 1)
    .bind("$2", "Walter")
    .bind("$3", "White")
    .execute()

Binding also allowed positional index (zero-based) references. The parameter index is derived from the parameter discovery order when parsing the query.

Data Type Mapping

This reference table shows the type mapping between PostgreSQL and Java data types:

PostgreSQL Type	Supported Data Type
bigint	Long, Boolean, Byte, Short, Integer
bit	Not yet supported.
bit varying	Not yet supported.
boolean or bool	Boolean
box	Not yet supported.
bytea	Not yet supported.
character	String
character varying	String
cidr	Not yet supported.
circle	Not yet supported.
date	LocalDate
double precision	Double, Float
inet	InetAddress
integer	Integer, Boolean, Byte, Short, Long
interval	Not yet supported.
json	Not yet supported.
line	Not yet supported.
lseg	Not yet supported.
macaddr	Not yet supported.
macaddr8	Not yet supported.
money	Not yet supported.
numeric	BigDecimal
path	Not yet supported.
pg_lsn	Not yet supported.
point	Not yet supported.
polygon	Not yet supported.
real	Float, Double
smallint	Short, Boolean, Byte, Integer, Long
smallserial	Integer, Boolean, Byte, Short, Long
serial	Long, Boolean, Byte, Short, Integer
text	String
time [without time zone]	LocalTime
time [with time zone]	Not yet supported.
timestamp [without time zone]	LocalDateTime
timestamp [with time zone]	ZonedDateTime
tsquery	Not yet supported.
tsvector	Not yet supported.
txid_snapshot	Not yet supported.
uuid	UUID, String
xml	Not yet supported.

Types in bold indicate the native (default) Java type.

Support for the following single-dimensional arrays (read and write):

PostgreSQL Type	Supported Data Type
text[]	String[]
integer[] or int[]	Integer[], Long[], Short[]

License

This project is released under version 2.0 of the Apache License.