Method WithDatabase

Namespace: Neo4j.Driver

Assembly: Neo4j.Driver.dll

WithDatabase(string)

Sets the target database name for queries executed within the constructed session.

public SessionConfigBuilder WithDatabase(string database)

Parameters

database string: The database name.

Returns

SessionConfigBuilder: This SessionConfigBuilder instance.

Remarks

This option has no explicit value by default, as such it is recommended to set a value if the target database is known in advance. This has the benefit of ensuring a consistent target database name throughout the session in a straightforward way and potentially simplifies driver logic, which reduces network communication and might result in better performance.

Cypher clauses such as USE are not a replacement for this option as Cypher is handled by the server and not the driver.

When no explicit name is set, the driver behavior depends on the connection URI scheme supplied to the driver on instantiation and Bolt protocol version.

Specifically, the following applies:

bolt schemes - queries are dispatched to the server for execution without explicit database name supplied, meaning that the target database name for query execution is determined by the server. It is important to note that the target database may change (even within the same session), for instance if the user's home database is changed on the server.
neo4j schemes - providing that Bolt protocol version 4.4, which was introduced with Neo4j server 4.4, or above is available, the driver fetches the user's home database name from the server on first query execution within the session and uses the fetched database name explicitly for all queries executed within the session. This ensures that the database name remains consistent within the given session. For instance, if the user's home database name is 'movies' and the server supplies it to the driver upon database name fetching for the session, all queries within that session are executed with the explicit database name 'movies' supplied. Any change to the user’s home database is reflected only in sessions created after such change takes effect. This behavior requires additional network communication. In clustered environments, it is strongly recommended to avoid a single point of failure. For instance, by ensuring that the connection URI resolves to multiple endpoints. For older Bolt protocol versions the behavior is the same as described for the bolt schemes above.

Exceptions

ArgumentNullException: Throws ArgumentNullException when provided database name is null or an empty string.