#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))

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 `$1`, `$2` and so on, SQL Server uses named bind markers prefixed with `@` as their native bind markers.
+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 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 NamedParameterSupport} 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 whether there is a value defined.
+	 */
+	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.
+	 * @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 NamedParameterSupport}.
+		 *
+		 * @param namedParameterSupport must not be {@literal null}.
+		 * @return {@code this} {@link Builder}.
+		 * @see NamedParameterSupport#enabled()
+		 * @see NamedParameterSupport#disabled()
+		 */
+		Builder namedParameters(NamedParameterSupport namedParameterSupport);
+
 		/**
 		 * 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 NamedParameterSupport} is enabled.
+	 *
+	 * @see NamedParameterSupport
+	 * @see DatabaseClient.Builder#namedParameters(NamedParameterSupport)
 	 */
 	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 NamedParameterSupport namedParameterSupport;
+
 	private final DefaultDatabaseClientBuilder builder;
 
 	DefaultDatabaseClient(ConnectionFactory connector, R2dbcExceptionTranslator exceptionTranslator,
-			ReactiveDataAccessStrategy dataAccessStrategy, DefaultDatabaseClientBuilder builder) {
+			ReactiveDataAccessStrategy dataAccessStrategy, NamedParameterSupport namedParameterSupport,
+			DefaultDatabaseClientBuilder builder) {
 
 		this.connector = connector;
 		this.exceptionTranslator = exceptionTranslator;
 		this.dataAccessStrategy = dataAccessStrategy;
+		this.namedParameterSupport = namedParameterSupport;
 		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 = namedParameterSupport.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 NamedParameterSupport namedParameterSupport;
 
 	DefaultDatabaseClientBuilder() {}
 
@@ -48,6 +49,7 @@ class DefaultDatabaseClientBuilder implements DatabaseClient.Builder {
 		this.connectionFactory = other.connectionFactory;
 		this.exceptionTranslator = other.exceptionTranslator;
 		this.accessStrategy = other.accessStrategy;
+		this.namedParameterSupport = other.namedParameterSupport;
 	}
 
 	@Override
@@ -77,6 +79,15 @@ public Builder dataAccessStrategy(ReactiveDataAccessStrategy accessStrategy) {
 		return this;
 	}
 
+	@Override
+	public Builder namedParameters(NamedParameterSupport namedParameterSupport) {
+
+		Assert.notNull(namedParameterSupport, "NamedParameterSupportAccessStrategy must not be null!");
+
+		this.namedParameterSupport = namedParameterSupport;
+		return this;
+	}
+
 	@Override
 	public DatabaseClient build() {
 
@@ -97,12 +108,20 @@ public DatabaseClient build() {
 			accessStrategy = new DefaultReactiveDataAccessStrategy(dialect);
 		}
 
-		return doBuild(this.connectionFactory, exceptionTranslator, accessStrategy, new DefaultDatabaseClientBuilder(this));
+		NamedParameterSupport namedParameterSupport = this.namedParameterSupport;
+
+		if (namedParameterSupport == null) {
+			namedParameterSupport = NamedParameterSupport.enabled();
+		}
+
+		return doBuild(this.connectionFactory, exceptionTranslator, accessStrategy, namedParameterSupport,
+				new DefaultDatabaseClientBuilder(this));
 	}
 
 	protected DatabaseClient doBuild(ConnectionFactory connector, R2dbcExceptionTranslator exceptionTranslator,
-			ReactiveDataAccessStrategy accessStrategy, DefaultDatabaseClientBuilder builder) {
-		return new DefaultDatabaseClient(connector, exceptionTranslator, accessStrategy, builder);
+			ReactiveDataAccessStrategy accessStrategy, NamedParameterSupport namedParameterSupport,
+			DefaultDatabaseClientBuilder builder) {
+		return new DefaultDatabaseClient(connector, exceptionTranslator, accessStrategy, namedParameterSupport, builder);
 	}
 
 	@Override

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

@@ -41,6 +41,7 @@
 import org.springframework.data.r2dbc.dialect.ArrayColumns;
 import org.springframework.data.r2dbc.dialect.BindMarker;
 import org.springframework.data.r2dbc.dialect.BindMarkers;
+import org.springframework.data.r2dbc.dialect.BindMarkersFactory;
 import org.springframework.data.r2dbc.dialect.Dialect;
 import org.springframework.data.r2dbc.dialect.LimitClause;
 import org.springframework.data.r2dbc.dialect.LimitClause.Position;
@@ -238,6 +239,15 @@ public String getTableName(Class<?> type) {
 		return getRequiredPersistentEntity(type).getTableName();
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.r2dbc.function.ReactiveDataAccessStrategy#getBindMarkersFactory()
+	 */
+	@Override
+	public BindMarkersFactory getBindMarkersFactory() {
+		return dialect.getBindMarkersFactory();
+	}
+
 	private RelationalPersistentEntity<?> getRequiredPersistentEntity(Class<?> typeToRead) {
 		return mappingContext.getRequiredPersistentEntity(typeToRead);
 	}

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

@@ -39,8 +39,9 @@
 class DefaultTransactionalDatabaseClient extends DefaultDatabaseClient implements TransactionalDatabaseClient {
 
 	DefaultTransactionalDatabaseClient(ConnectionFactory connector, R2dbcExceptionTranslator exceptionTranslator,
-			ReactiveDataAccessStrategy dataAccessStrategy, DefaultDatabaseClientBuilder builder) {
-		super(connector, exceptionTranslator, dataAccessStrategy, builder);
+			ReactiveDataAccessStrategy dataAccessStrategy, NamedParameterSupport namedParameterSupport,
+			DefaultDatabaseClientBuilder builder) {
+		super(connector, exceptionTranslator, dataAccessStrategy, namedParameterSupport, builder);
 	}
 
 	@Override