Question
Neo4j 4.x Multi‑Database Connection String Syntax Change Requires Updated Driver Configuration
Rey River
0 reputation · 25 Oct 2020, 03:42 UTC
119.9K views
Loading…
0 reputation · 25 Oct 2020, 03:42 UTC
When upgrading from Neo4j 3.x to 4.x, the database introduced native multi‑database tenancy, which changes how a client specifies the target database. The goal is to define a connection string format that works consistently across driver versions while allowing applications to access either the default database or a named one without hard‑coding server‑specific details.
Constraints include maintaining backward compatibility with Neo4j 3.x drivers that ignore the database parameter, adhering to the official Bolt protocol version negotiation, and avoiding connection‑string patterns that cause the driver to fall back to the default database unintentionally. There is uncertainty about whether the database name should be supplied in the URI query string, as part of the path, or via driver‑level configuration, and how each option behaves when the server runs a mixed version cluster.
What is the recommended URI scheme for specifying a target database in Neo4j 4.x drivers? How should applications handle fallback to the default database when the database name is omitted? Does embedding the database name in the connection string affect connection pooling or session creation overhead?
34775 reputation · 25 Oct 2020, 09:19 UTC
Use a standard Bolt URI for the network endpoint and specify the target database when creating a session, not inside the URI string.
Supported URI schemes: bolt://host:port for single instances and bolt+routing://host:port for clusters. Do not append ?database=name; the Bolt protocol does not define a database query parameter, and official Neo4j 4.x drivers ignore it.
neo4jSessionConfig.builder().withDatabase("name").build() in the Java driver; other official drivers expose an equivalent session-level option.default_database from neo4j.conf.If the application omits the database name, do not add client-side fallback logic. The server applies its configured default. To target the default database explicitly, read default_database from neo4j.conf and pass that name in the session configuration, because omission behavior depends on the server's configured default.
Specifying a database name at session creation does not open a new TCP connection; sessions reuse the driver's existing connection pool. In a clustered deployment, the driver may maintain separate routing information per database. Frequently switching among many different named databases can increase routing-table negotiation, but for a small, stable set of databases the overhead is negligible.
CREATE DATABASE exampleDb;CALL db.currentDatabase(); in both sessions and confirm the named session returns exampleDb while the other returns the server default.Exact method names vary by driver (Java, Python, JavaScript, .NET, Go), but all official 4.x drivers place database selection at session level rather than in the URI.
Use comments to ask for clarification. Post a solution as an answer.
34,775 reputation · 25 Oct 2020, 13:39 UTC
For mixed 3.x/4.x clusters, the driver version is the limiting factor: a 4.x driver is required to route sessions to user databases, while 3.x drivers will only reach the default database regardless of session settings. On URI schemes, prefer neo4j:// for cluster routing in 4.x; bolt:// is intended for direct connections to a single instance. Confirm the exact scheme support in your driver's 4.x release notes, since routing defaults and Bolt protocol negotiation can differ across minor versions.
When pointing at a mixed cluster, also verify that the target user database is actually deployed on the cluster members your routing table returns, because user databases may exist on only a subset of members.