@@ -224,16 +224,37 @@ public Builder withDefaultAccessMode(AccessMode mode) {
224
224
}
225
225
226
226
/**
227
- * Set the database that the newly created session is going to connect to .
227
+ * Sets target database name for queries executed within session .
228
228
* <p>
229
- * For connecting to servers that support multi-databases,
230
- * it is highly recommended to always set the database explicitly in the {@link SessionConfig} for each session.
231
- * If the database name is not set, then session defaults to connecting to the default database configured in server configuration.
229
+ * This option has no explicit value by default, but it is recommended to set one if the target database is
230
+ * known in advance. This has the benefit of ensuring a consistent target database name throughout the session
231
+ * in a straightforward way and potentially simplifies driver logic as well as reduces network communication
232
+ * resulting in better performance.
232
233
* <p>
233
- * For servers that do not support multi-databases, leave this database value unset. The only database will be used instead.
234
+ * When no explicit name is set, the driver behavior depends on the connection URI scheme supplied to the driver
235
+ * on instantiation and Bolt protocol version.
236
+ * <p>
237
+ * Specifically, the following applies:
238
+ * <ul>
239
+ * <li><b>bolt schemes</b> - queries are dispatched to the server for execution without explicit database name
240
+ * supplied, meaning that the target database name for query execution is determined by the server. It is
241
+ * important to note that the target database may change (even within the same session), for instance if the
242
+ * user's home database is changed on the server.</li>
243
+ * <li><b>neo4j schemes</b> - providing that Bolt protocol version 4.4, which was introduced with Neo4j server
244
+ * 4.4, or above is available, the driver fetches the user's home database name from the server on first query
245
+ * execution within the session and uses the fetched database name explicitly for all queries executed within
246
+ * the session. This ensures that the database name remains consistent within the given session. For instance,
247
+ * if the user's home database name is 'movies' and the server supplies it to the driver upon database name
248
+ * fetching for the session, all queries within that session are executed with the explicit database name
249
+ * 'movies' supplied. Any change to the user’s home database is reflected only in sessions created after such
250
+ * change takes effect. This behavior requires additional network communication. In clustered environments, it
251
+ * is strongly recommended to avoid a single point of failure. For instance, by ensuring that the connection URI
252
+ * resolves to multiple endpoints. For older Bolt protocol versions the behavior is the same as described for
253
+ * the <b>bolt</b> schemes above.</li>
254
+ * </ul>
234
255
*
235
- * @param database the database the session going to connect to. Provided value should not be {@code null}.
236
- * @return this builder.
256
+ * @param database the target database name, must not be {@code null}
257
+ * @return this builder
237
258
*/
238
259
public Builder withDatabase (String database ) {
239
260
requireNonNull (database , "Database name should not be null." );
0 commit comments