Skip to content
R2DBC PostgreSQL Implementation
Branch: master
Clone or download
Pull request Compare This branch is 33 commits behind r2dbc:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.mvn/wrapper
ci
src
.gitignore
CHANGELOG
LICENSE
NOTICE
README.md
intellij-style.xml
mvnw
mvnw.cmd
pom.xml

README.md

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.

You can’t perform that action at this time.