Skip to content

Commit 470dcb3

Browse files
committed
Update SessionConfig.withDatabase documentation (neo4j#1334)
1 parent 4770155 commit 470dcb3

File tree

1 file changed

+28
-7
lines changed

1 file changed

+28
-7
lines changed

driver/src/main/java/org/neo4j/driver/SessionConfig.java

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -224,16 +224,37 @@ public Builder withDefaultAccessMode(AccessMode mode) {
224224
}
225225

226226
/**
227-
* Set the database that the newly created session is going to connect to.
227+
* Sets target database name for queries executed within session.
228228
* <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.
232233
* <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>
234255
*
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
237258
*/
238259
public Builder withDatabase(String database) {
239260
requireNonNull(database, "Database name should not be null.");

0 commit comments

Comments
 (0)