Update SessionConfig#database docs with better recommendation (#1020)

bigmontz · web-flow · commit aa63800cb2b6 · 2022-11-25T09:21:02.000+01:00
diff --git a/packages/core/src/driver.ts b/packages/core/src/driver.ts
@@ -132,6 +132,41 @@ class SessionConfig {
     /**
      * The database this session will operate on.
      *
+     * This option has no explicit value by default, but it is recommended to set
+     * one 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 as well as
+     * reduces network communication resulting in better performance.
+     *
+     * 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.
+     *
      * @type {string|undefined}
      */
     this.database = ''
@@ -589,6 +624,5 @@ function createHostNameResolver (config: any): ConfiguredCustomResolver {
   return new ConfiguredCustomResolver(config.resolver)
 }
 
-export { Driver, READ, WRITE }
-export type { SessionConfig }
+export { Driver, READ, WRITE, SessionConfig }
 export default Driver
diff --git a/packages/neo4j-driver-deno/lib/core/driver.ts b/packages/neo4j-driver-deno/lib/core/driver.ts
@@ -132,6 +132,41 @@ class SessionConfig {
     /**
      * The database this session will operate on.
      *
+     * This option has no explicit value by default, but it is recommended to set
+     * one 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 as well as
+     * reduces network communication resulting in better performance.
+     *
+     * 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.
+     *
      * @type {string|undefined}
      */
     this.database = ''
@@ -589,6 +624,5 @@ function createHostNameResolver (config: any): ConfiguredCustomResolver {
   return new ConfiguredCustomResolver(config.resolver)
 }
 
-export { Driver, READ, WRITE }
-export type { SessionConfig }
+export { Driver, READ, WRITE, SessionConfig }
 export default Driver
