Improve documentation of SessionConfig#Database

Author: fbiville

neo4j/session_with_context.go

@@ -82,7 +82,37 @@ type SessionConfig struct {
 	// within the same session will automatically use the bookmark from the previous command in the
 	// session.
 	Bookmarks Bookmarks
-	// DatabaseName contains the name of the database that the commands in the session will execute on.
+	// DatabaseName sets the target database name for the queries executed within the session created with this
+	// configuration.
+	// Usage of Cypher clauses like USE is not a replacement for this option.
+	// Drive​r sends Cypher to the server for processing.
+	// 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:
+	//
+	// - for 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.
+	//
+	// - for 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.
 	DatabaseName string
 	// FetchSize defines how many records to pull from server in each batch.
 	// From Bolt protocol v4 (Neo4j 4+) records can be fetched in batches as compared to fetching