#23 - Add support for named parameters.

DatabaseClient now supports named parameters prefixed with a colon such as :name in addition to database-native bind markers. Named parameters thus are supported in annotated repository query methods which also increases portability of queries across database vendors.

Named parameter support unrolls collection arguments to reduce the need for argument-specific SQL statements:

db.execute()
    .sql("SELECT id, name, state FROM table WHERE age IN (:ages)")
    .bind("ages", Arrays.asList(35, 50));

Results in a query: SELECT id, name, state FROM table WHERE age IN (35, 50)

Collection arguments containing nested object arrays can be used to use select lists:

List<Object[]> tuples = new ArrayList<>();
tuples.add(new Object[] {"John", 35});
tuples.add(new Object[] {"Ann",  50});

db.execute()
    .sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)")
    .bind("tuples", tuples);

translates to: SELECT id, name, state FROM table WHERE (name, age) IN (('John', 35), ('Ann', 50))

Original pull request: #47.

Author: mp911de

src/main/asciidoc/new-features.adoc

@@ -1,10 +1,15 @@
 [[new-features]]
 = New & Noteworthy
 
+[[new-features.1-0-0-M2]]
+== What's New in Spring Data R2DBC 1.0.0 M2
+
+* Support for named parameters.
+
 [[new-features.1-0-0-M1]]
 == What's New in Spring Data R2DBC 1.0.0 M1
 
-* Initial R2DBC support through `DatabaseClient`
-* Initial Transaction support through `TransactionalDatabaseClient`
-* Initial R2DBC Repository Support through `R2dbcRepository`
-* Initial Dialect support for Postgres and Microsoft SQL Server
+* Initial R2DBC support through `DatabaseClient`.
+* Initial Transaction support through `TransactionalDatabaseClient`.
+* Initial R2DBC Repository Support through `R2dbcRepository`.
+* Initial Dialect support for Postgres and Microsoft SQL Server.

src/main/asciidoc/reference/r2dbc-repositories.adoc

@@ -104,7 +104,7 @@ Defining such a query is a matter of declaring a method on the repository interf
 ----
 public interface PersonRepository extends ReactiveCrudRepository<Person, Long> {
 
-    @Query("SELECT * FROM person WHERE lastname = $1")
+    @Query("SELECT * FROM person WHERE lastname = :lastname")
     Flux<Person> findByLastname(String lastname);                      <1>
 
     @Query("SELECT firstname, lastname FROM person WHERE lastname = $1")
@@ -114,10 +114,10 @@ public interface PersonRepository extends ReactiveCrudRepository<Person, Long> {
 ----
 <1> The `findByLastname` method shows a query for all people with the given last name.
 The query is provided as R2DBC repositories do not support query derivation.
+<2> A query for a single `Person` entity projecting only `firstname` and `lastname` columns.
 The annotated query uses native bind markers, which are Postgres bind markers in this example.
-<4> A query for a single `Person` entity projecting only `firstname` and `lastname` columns.
 ====
 
 NOTE: R2DBC repositories do not support query derivation.
 
-NOTE: R2DBC repositories require native parameter bind markers that are bound by index.
+NOTE: R2DBC repositories bind parameters to placeholders by index.

src/main/asciidoc/reference/r2dbc.adoc

@@ -446,20 +446,61 @@ Parameter binding supports various binding strategies:
 * By Index using zero-based parameter indexes.
 * By Name using the placeholder name.
 
-The following example shows parameter binding for a PostgreSQL query:
+The following example shows parameter binding for a query:
 
 [source,java]
 ----
 db.execute()
-    .sql("INSERT INTO person (id, name, age) VALUES($1, $2, $3)")
-    .bind(0, "joe")
-    .bind(1, "Joe")
-    .bind(2, 34);
+    .sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)")
+    .bind("id", "joe")
+    .bind("name", "Joe")
+    .bind("age", 34);
 ----
 
-NOTE: If you are familiar with JDBC, then you're also familiar with `?` (question mark) bind markers.
+.R2DBC Native Bind Markers
+****
+R2DBC uses database-native bind markers that depend on the actual database.
+If you are familiar with JDBC, then you're also familiar with `?` (question mark) bind markers.
 JDBC drivers translate question mark bind markers to database-native markers as part of statement execution.
-Make sure to use the appropriate bind markers that are supported by your database as R2DBC requires database-native parameter bind markers.
+
+Postgres uses indexed markers (`$1`, `$2`), SQL Server uses named bind markers prefixed with `@` as its native bind marker syntax.
+Spring Data R2DBC leverages `Dialect` implementations to expand named parameters to native bind markers at the time of query execution which gives you a certain degree of query portability across various database vendors.
+You can still use native bind markers if you prefer to do so.
+****
+
+The query-preprocessor unrolls named `Collection` parameters into a series of bind markers to remove the need of dynamic query creation based on the number of arguments.
+Nested object arrays are expanded to allow usage of e.g. select lists.
+
+Consider the following query:
+
+[source,sql]
+----
+SELECT id, name, state FROM table WHERE (name, age) IN (('John', 35), ('Ann', 50))
+----
+
+This query can be parametrized and executed as:
+
+[source,java]
+----
+List<Object[]> tuples = new ArrayList<>();
+tuples.add(new Object[] {"John", 35});
+tuples.add(new Object[] {"Ann",  50});
+
+db.execute()
+    .sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)")
+    .bind("tuples", tuples);
+----
+
+NOTE: Usage of select lists is vendor-dependent.
+
+A simpler variant using `IN` predicates:
+
+[source,java]
+----
+db.execute()
+    .sql("SELECT id, name, state FROM table WHERE age IN (:ages)")
+    .bind("ages", Arrays.asList(35, 50));
+----
 
 [[r2dbc.datbaseclient.transactions]]
 === Transactions
@@ -478,14 +519,14 @@ TransactionalDatabaseClient databaseClient = TransactionalDatabaseClient.create(
 
 Flux<Void> completion = databaseClient.inTransaction(db -> {
 
-    return db.execute().sql("INSERT INTO person (id, name, age) VALUES($1, $2, $3)") //
-            .bind(0, "joe") //
-            .bind(1, "Joe") //
-            .bind(2, 34) //
+    return db.execute().sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)")
+            .bind("id", "joe")
+            .bind("name", "Joe")
+            .bind("age", 34)
             .fetch().rowsUpdated()
-            .then(db.execute().sql("INSERT INTO contacts (id, name) VALUES($1, $2)")
-                    .bind(0, "joe")
-                    .bind(1, "Joe")
+            .then(db.execute().sql("INSERT INTO contacts (id, name) VALUES(:id, :name)")
+                    .bind("id", "joe")
+                    .bind("name", "Joe")
                     .fetch().rowsUpdated())
             .then();
 });

src/main/java/org/springframework/data/r2dbc/function/BindParameterSource.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.r2dbc.function;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * Interface that defines common functionality for objects that can offer parameter values for named bind parameters,
+ * serving as argument for {@link NamedParameterExpander} operations.
+ * <p>
+ * This interface allows for the specification of the type in addition to parameter values. All parameter values and
+ * types are identified by specifying the name of the parameter.
+ * <p>
+ * Intended to wrap various implementations like a {@link java.util.Map} with a consistent interface.
+ *
+ * @author Mark Paluch
+ * @see MapBindParameterSource
+ */
+public interface BindParameterSource {
+
+	/**
+	 * Determine whether there is a value for the specified named parameter.
+	 *
+	 * @param paramName the name of the parameter.
+	 * @return {@literal true} if there is a value defined; {@literal false} otherwise.
+	 */
+	boolean hasValue(String paramName);
+
+	/**
+	 * Return the parameter value for the requested named parameter.
+	 *
+	 * @param paramName the name of the parameter.
+	 * @return the value of the specified parameter, can be {@literal null}.
+	 * @throws IllegalArgumentException if there is no value for the requested parameter.
+	 */
+	@Nullable
+	Object getValue(String paramName) throws IllegalArgumentException;
+
+	/**
+	 * Determine the type for the specified named parameter.
+	 *
+	 * @param paramName the name of the parameter.
+	 * @return the type of the specified parameter, or {@link Object#getClass()} if not known.
+	 */
+	default Class<?> getType(String paramName) {
+		return Object.class;
+	}
+}

src/main/java/org/springframework/data/r2dbc/function/DatabaseClient.java

@@ -109,6 +109,16 @@ interface Builder {
 		 */
 		Builder dataAccessStrategy(ReactiveDataAccessStrategy accessStrategy);
 
+		/**
+		 * Configures {@link NamedParameterExpander}.
+		 *
+		 * @param namedParameters must not be {@literal null}.
+		 * @return {@code this} {@link Builder}.
+		 * @see NamedParameterExpander#enabled()
+		 * @see NamedParameterExpander#disabled()
+		 */
+		Builder namedParameters(NamedParameterExpander namedParameters);
+
 		/**
 		 * Configures a {@link Consumer} to configure this builder.
 		 *
@@ -124,7 +134,12 @@ interface Builder {
 	}
 
 	/**
-	 * Contract for specifying a SQL call along with options leading to the exchange.
+	 * Contract for specifying a SQL call along with options leading to the exchange. The SQL string can contain either
+	 * native parameter bind markers (e.g. {@literal $1, $2} for Postgres, {@literal @P0, @P1} for SQL Server) or named
+	 * parameters (e.g. {@literal :foo, :bar}) when {@link NamedParameterExpander} is enabled.
+	 *
+	 * @see NamedParameterExpander
+	 * @see DatabaseClient.Builder#namedParameters(NamedParameterExpander)
 	 */
 	interface SqlSpec {
 

src/main/java/org/springframework/data/r2dbc/function/DefaultDatabaseClient.java

@@ -66,9 +66,6 @@
  */
 class DefaultDatabaseClient implements DatabaseClient, ConnectionAccessor {
 
-	/**
-	 * Logger available to subclasses
-	 */
 	private final Log logger = LogFactory.getLog(getClass());
 
 	private final ConnectionFactory connector;
@@ -77,14 +74,18 @@ class DefaultDatabaseClient implements DatabaseClient, ConnectionAccessor {
 
 	private final ReactiveDataAccessStrategy dataAccessStrategy;
 
+	private final NamedParameterExpander namedParameters;
+
 	private final DefaultDatabaseClientBuilder builder;
 
 	DefaultDatabaseClient(ConnectionFactory connector, R2dbcExceptionTranslator exceptionTranslator,
-			ReactiveDataAccessStrategy dataAccessStrategy, DefaultDatabaseClientBuilder builder) {
+			ReactiveDataAccessStrategy dataAccessStrategy, NamedParameterExpander namedParameters,
+			DefaultDatabaseClientBuilder builder) {
 
 		this.connector = connector;
 		this.exceptionTranslator = exceptionTranslator;
 		this.dataAccessStrategy = dataAccessStrategy;
+		this.namedParameters = namedParameters;
 		this.builder = builder;
 	}
 
@@ -325,8 +326,21 @@ <T> FetchSpec<T> exchange(String sql, BiFunction<Row, RowMetadata, T> mappingFun
 					logger.debug("Executing SQL statement [" + sql + "]");
 				}
 
-				Statement<?> statement = it.createStatement(sql);
-				doBind(statement, byName, byIndex);
+				BindableOperation operation = namedParameters.expand(sql, dataAccessStrategy.getBindMarkersFactory(),
+						new MapBindParameterSource(byName));
+
+				Statement<?> statement = it.createStatement(operation.toQuery());
+
+				byName.forEach((name, o) -> {
+
+					if (o.getValue() != null) {
+						operation.bind(statement, name, o.getValue());
+					} else {
+						operation.bindNull(statement, name, o.getType());
+					}
+				});
+
+				doBind(statement, Collections.emptyMap(), byIndex);
 
 				return statement;
 			};

src/main/java/org/springframework/data/r2dbc/function/DefaultDatabaseClientBuilder.java

@@ -38,6 +38,7 @@ class DefaultDatabaseClientBuilder implements DatabaseClient.Builder {
 	private @Nullable ConnectionFactory connectionFactory;
 	private @Nullable R2dbcExceptionTranslator exceptionTranslator;
 	private ReactiveDataAccessStrategy accessStrategy;
+	private NamedParameterExpander namedParameters;
 
 	DefaultDatabaseClientBuilder() {}
 
@@ -48,8 +49,13 @@ class DefaultDatabaseClientBuilder implements DatabaseClient.Builder {
 		this.connectionFactory = other.connectionFactory;
 		this.exceptionTranslator = other.exceptionTranslator;
 		this.accessStrategy = other.accessStrategy;
+		this.namedParameters = other.namedParameters;
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.r2dbc.function.DatabaseClient.Builder#connectionFactory(io.r2dbc.spi.ConnectionFactory)
+	 */
 	@Override
 	public Builder connectionFactory(ConnectionFactory factory) {
 
@@ -59,6 +65,10 @@ public Builder connectionFactory(ConnectionFactory factory) {
 		return this;
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.r2dbc.function.DatabaseClient.Builder#exceptionTranslator(org.springframework.data.r2dbc.support.R2dbcExceptionTranslator)
+	 */
 	@Override
 	public Builder exceptionTranslator(R2dbcExceptionTranslator exceptionTranslator) {
 
@@ -68,6 +78,10 @@ public Builder exceptionTranslator(R2dbcExceptionTranslator exceptionTranslator)
 		return this;
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.r2dbc.function.DatabaseClient.Builder#dataAccessStrategy(org.springframework.data.r2dbc.function.ReactiveDataAccessStrategy)
+	 */
 	@Override
 	public Builder dataAccessStrategy(ReactiveDataAccessStrategy accessStrategy) {
 
@@ -77,6 +91,23 @@ public Builder dataAccessStrategy(ReactiveDataAccessStrategy accessStrategy) {
 		return this;
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.r2dbc.function.DatabaseClient.Builder#namedParameters(org.springframework.data.r2dbc.function.NamedParameterExpander)
+	 */
+	@Override
+	public Builder namedParameters(NamedParameterExpander namedParameters) {
+
+		Assert.notNull(namedParameters, "NamedParameterExpander must not be null!");
+
+		this.namedParameters = namedParameters;
+		return this;
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.r2dbc.function.DatabaseClient.Builder#build()
+	 */
 	@Override
 	public DatabaseClient build() {
 
@@ -97,19 +128,35 @@ public DatabaseClient build() {
 			accessStrategy = new DefaultReactiveDataAccessStrategy(dialect);
 		}
 
-		return doBuild(this.connectionFactory, exceptionTranslator, accessStrategy, new DefaultDatabaseClientBuilder(this));
+		NamedParameterExpander namedParameters = this.namedParameters;
+
+		if (namedParameters == null) {
+			namedParameters = NamedParameterExpander.enabled();
+		}
+
+		return doBuild(this.connectionFactory, exceptionTranslator, accessStrategy, namedParameters,
+				new DefaultDatabaseClientBuilder(this));
 	}
 
 	protected DatabaseClient doBuild(ConnectionFactory connector, R2dbcExceptionTranslator exceptionTranslator,
-			ReactiveDataAccessStrategy accessStrategy, DefaultDatabaseClientBuilder builder) {
-		return new DefaultDatabaseClient(connector, exceptionTranslator, accessStrategy, builder);
+			ReactiveDataAccessStrategy accessStrategy, NamedParameterExpander namedParameters,
+			DefaultDatabaseClientBuilder builder) {
+		return new DefaultDatabaseClient(connector, exceptionTranslator, accessStrategy, namedParameters, builder);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see java.lang.Object#clone()
+	 */
 	@Override
 	public DatabaseClient.Builder clone() {
 		return new DefaultDatabaseClientBuilder(this);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.r2dbc.function.DatabaseClient.Builder#apply(java.util.function.Consumer)
+	 */
 	@Override
 	public DatabaseClient.Builder apply(Consumer<DatabaseClient.Builder> builderConsumer) {
 		Assert.notNull(builderConsumer, "BuilderConsumer must not be null");