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.M7</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 5432. (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> mono = 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:
mono.flatMapMany(connection -> 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:
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.