0
# Drivers & Connection
1
2
Connection management and driver creation for Neo4j databases, supporting both direct server connections and cluster routing with comprehensive configuration options. The driver handles connection pooling, authentication, encryption, and provides both synchronous and asynchronous APIs.
3
4
## Capabilities
5
6
### GraphDatabase Factory
7
8
Static factory class providing convenient methods for creating different types of drivers based on connection requirements and database topology.
9
10
```python { .api }
11
class GraphDatabase:
12
@staticmethod
13
def driver(uri: str, *, auth: Auth = None, **config) -> Driver:
14
"""
15
Create a driver instance for connecting to Neo4j.
16
17
Parameters:
18
- uri: Connection URI (bolt://, neo4j://, bolt+s://, neo4j+s://)
19
- auth: Authentication token (basic_auth, kerberos_auth, etc.)
20
- **config: Driver configuration options
21
22
Returns:
23
Driver instance (BoltDriver or Neo4jDriver based on URI scheme)
24
"""
25
26
@staticmethod
27
def bookmark_manager(
28
initial_bookmarks: list[Bookmark] = None,
29
bookmarks_supplier: Callable = None,
30
bookmarks_consumer: Callable = None
31
) -> BookmarkManager:
32
"""
33
Create a default BookmarkManager implementation.
34
35
Parameters:
36
- initial_bookmarks: Starting bookmarks for causal consistency
37
- bookmarks_supplier: Function to supply bookmarks
38
- bookmarks_consumer: Function to consume bookmarks
39
40
Returns:
41
BookmarkManager instance for managing causal consistency
42
"""
43
44
@staticmethod
45
def bolt_driver(target: str, **config) -> BoltDriver:
46
"""
47
Create a direct Bolt driver for single server connections.
48
49
Parameters:
50
- target: Bolt server address
51
- **config: Driver configuration options
52
53
Returns:
54
BoltDriver instance for direct server connection
55
"""
56
57
@staticmethod
58
def neo4j_driver(
59
*targets: str,
60
routing_context: dict = None,
61
**config
62
) -> Neo4jDriver:
63
"""
64
Create a routing driver for Neo4j cluster connections.
65
66
Parameters:
67
- *targets: Cluster member addresses
68
- routing_context: Routing context for cluster discovery
69
- **config: Driver configuration options
70
71
Returns:
72
Neo4jDriver instance for cluster routing
73
"""
74
```
75
76
Example usage:
77
78
```python
79
from neo4j import GraphDatabase, basic_auth
80
81
# Create driver with automatic type selection
82
driver = GraphDatabase.driver(
83
"neo4j://localhost:7687",
84
auth=basic_auth("neo4j", "password"),
85
max_connection_lifetime=30 * 60, # 30 minutes
86
max_connection_pool_size=50,
87
connection_acquisition_timeout=60.0
88
)
89
90
# Create direct bolt driver
91
bolt_driver = GraphDatabase.bolt_driver(
92
"bolt://localhost:7687",
93
auth=basic_auth("neo4j", "password")
94
)
95
96
# Create cluster routing driver
97
cluster_driver = GraphDatabase.neo4j_driver(
98
"localhost:7687",
99
"localhost:7688",
100
"localhost:7689",
101
routing_context={"region": "us-east-1"}
102
)
103
```
104
105
### AsyncGraphDatabase Factory
106
107
Asynchronous version of GraphDatabase providing the same factory methods but returning async-compatible drivers.
108
109
```python { .api }
110
class AsyncGraphDatabase:
111
@staticmethod
112
def driver(uri: str, *, auth: Auth = None, **config) -> AsyncDriver:
113
"""
114
Create an async driver instance for connecting to Neo4j.
115
116
Returns:
117
AsyncDriver instance with async methods
118
"""
119
120
@staticmethod
121
def bookmark_manager(
122
initial_bookmarks: list[Bookmark] = None,
123
bookmarks_supplier: Callable = None,
124
bookmarks_consumer: Callable = None
125
) -> AsyncBookmarkManager:
126
"""
127
Create an async BookmarkManager implementation.
128
129
Returns:
130
AsyncBookmarkManager for async bookmark management
131
"""
132
133
@staticmethod
134
def bolt_driver(target: str, **config) -> AsyncBoltDriver:
135
"""Create async direct Bolt driver."""
136
137
@staticmethod
138
def neo4j_driver(
139
*targets: str,
140
routing_context: dict = None,
141
**config
142
) -> AsyncNeo4jDriver:
143
"""Create async routing driver."""
144
```
145
146
### Driver Base Class
147
148
Base class for all synchronous driver types providing core functionality for session creation, query execution, and connection management.
149
150
```python { .api }
151
class Driver:
152
@property
153
def encrypted(self) -> bool:
154
"""Indicates if driver uses encryption."""
155
156
@property
157
def execute_query_bookmark_manager(self) -> BookmarkManager:
158
"""Default bookmark manager for execute_query operations."""
159
160
def session(
161
self,
162
*,
163
database: str = None,
164
default_access_mode: str = None,
165
bookmarks: list[Bookmark] = None,
166
bookmark_manager: BookmarkManager = None,
167
auth: Auth = None,
168
**config
169
) -> Session:
170
"""
171
Create a new session for executing work.
172
173
Parameters:
174
- database: Target database name (None for default)
175
- default_access_mode: READ_ACCESS or WRITE_ACCESS
176
- bookmarks: Initial bookmarks for causal consistency
177
- bookmark_manager: Custom bookmark manager
178
- auth: Session-level authentication override
179
- **config: Additional session configuration
180
181
Returns:
182
Session instance for executing queries and transactions
183
"""
184
185
def execute_query(
186
self,
187
query: str,
188
parameters: dict = None,
189
routing: RoutingControl = RoutingControl.WRITE,
190
database: str = None,
191
impersonated_user: str = None,
192
bookmark_manager: BookmarkManager = None,
193
auth: Auth = None,
194
result_transformer: Callable = None,
195
**kwargs
196
) -> Any:
197
"""
198
Execute a query in a managed transaction function.
199
200
Parameters:
201
- query: Cypher query string
202
- parameters: Query parameters dictionary
203
- routing: Query routing control (READ/WRITE)
204
- database: Target database name
205
- impersonated_user: User to impersonate
206
- bookmark_manager: Bookmark manager for causal consistency
207
- auth: Authentication override
208
- result_transformer: Function to transform results
209
210
Returns:
211
Transformed query results (default: records, summary, keys tuple)
212
"""
213
214
def close(self) -> None:
215
"""
216
Shut down the driver and close all connections.
217
Blocks until all connections are closed.
218
"""
219
220
def verify_connectivity(
221
self,
222
*,
223
database: str = None,
224
auth: Auth = None
225
) -> None:
226
"""
227
Verify that the driver can connect to the server.
228
229
Parameters:
230
- database: Database to test connectivity against
231
- auth: Authentication credentials to test
232
233
Raises:
234
Exception if connectivity verification fails
235
"""
236
237
def get_server_info(
238
self,
239
*,
240
database: str = None,
241
auth: Auth = None
242
) -> ServerInfo:
243
"""
244
Get information about the connected Neo4j server.
245
246
Parameters:
247
- database: Target database for server info
248
- auth: Authentication credentials
249
250
Returns:
251
ServerInfo containing server details
252
"""
253
254
def verify_authentication(
255
self,
256
*,
257
auth: Auth = None,
258
**config
259
) -> bool:
260
"""
261
Verify authentication credentials against the server.
262
263
Parameters:
264
- auth: Authentication credentials to verify
265
- **config: Additional verification configuration
266
267
Returns:
268
True if authentication is valid, False otherwise
269
"""
270
271
def supports_multi_db(self) -> bool:
272
"""
273
Check if the server supports multiple databases.
274
275
Returns:
276
True if multi-database is supported
277
"""
278
279
def supports_session_auth(self) -> bool:
280
"""
281
Check if the server supports session-level re-authentication.
282
283
Returns:
284
True if session auth is supported
285
"""
286
```
287
288
### AsyncDriver Base Class
289
290
Asynchronous version of the Driver base class with async methods for all operations.
291
292
```python { .api }
293
class AsyncDriver:
294
@property
295
def encrypted(self) -> bool:
296
"""Indicates if driver uses encryption."""
297
298
@property
299
def execute_query_bookmark_manager(self) -> AsyncBookmarkManager:
300
"""Default async bookmark manager for execute_query operations."""
301
302
def session(
303
self,
304
*,
305
database: str = None,
306
default_access_mode: str = None,
307
bookmarks: list[Bookmark] = None,
308
bookmark_manager: AsyncBookmarkManager = None,
309
auth: Auth = None,
310
**config
311
) -> AsyncSession:
312
"""Create async session."""
313
314
async def execute_query(
315
self,
316
query: str,
317
parameters: dict = None,
318
routing: RoutingControl = RoutingControl.WRITE,
319
**kwargs
320
) -> Any:
321
"""Execute query asynchronously."""
322
323
async def close(self) -> None:
324
"""Asynchronously close driver and connections."""
325
326
async def verify_connectivity(self, **config) -> None:
327
"""Verify connectivity asynchronously."""
328
329
async def get_server_info(self, **config) -> ServerInfo:
330
"""Get server info asynchronously."""
331
332
async def verify_authentication(self, **config) -> bool:
333
"""Verify authentication asynchronously."""
334
335
async def supports_multi_db(self) -> bool:
336
"""Check multi-database support asynchronously."""
337
338
async def supports_session_auth(self) -> bool:
339
"""Check session auth support asynchronously."""
340
```
341
342
### Specific Driver Types
343
344
Concrete driver implementations for different connection patterns.
345
346
```python { .api }
347
class BoltDriver(Driver):
348
"""
349
Direct driver for single Bolt server connections.
350
Inherits all Driver methods and properties.
351
"""
352
353
class AsyncBoltDriver(AsyncDriver):
354
"""
355
Async direct driver for single Bolt server connections.
356
Inherits all AsyncDriver methods and properties.
357
"""
358
359
class Neo4jDriver(Driver):
360
"""
361
Routing driver for Neo4j cluster connections.
362
Inherits all Driver methods with cluster routing capabilities.
363
"""
364
365
class AsyncNeo4jDriver(AsyncDriver):
366
"""
367
Async routing driver for Neo4j cluster connections.
368
Inherits all AsyncDriver methods with cluster routing capabilities.
369
"""
370
```
371
372
## Usage Examples
373
374
### Basic Driver Creation
375
376
```python
377
from neo4j import GraphDatabase, basic_auth
378
379
# Simple driver creation
380
driver = GraphDatabase.driver(
381
"bolt://localhost:7687",
382
auth=basic_auth("neo4j", "password")
383
)
384
385
# Driver with configuration
386
driver = GraphDatabase.driver(
387
"neo4j://cluster.example.com:7687",
388
auth=basic_auth("neo4j", "password"),
389
max_connection_lifetime=30 * 60,
390
max_connection_pool_size=50,
391
connection_acquisition_timeout=60.0,
392
resolver=custom_resolver_function
393
)
394
```
395
396
### Async Driver Usage
397
398
```python
399
import asyncio
400
from neo4j import AsyncGraphDatabase, basic_auth
401
402
async def example():
403
driver = AsyncGraphDatabase.driver(
404
"neo4j://localhost:7687",
405
auth=basic_auth("neo4j", "password")
406
)
407
408
# Use execute_query for simple operations
409
records, summary, keys = await driver.execute_query(
410
"MATCH (n:Person) RETURN n.name AS name LIMIT 10"
411
)
412
413
await driver.close()
414
415
asyncio.run(example())
416
```
417
418
### Cluster Configuration
419
420
```python
421
from neo4j import GraphDatabase, basic_auth
422
423
# Create cluster driver with multiple seed addresses
424
driver = GraphDatabase.neo4j_driver(
425
"server1.cluster.com:7687",
426
"server2.cluster.com:7687",
427
"server3.cluster.com:7687",
428
auth=basic_auth("neo4j", "password"),
429
routing_context={
430
"region": "us-west-2",
431
"zone": "us-west-2a"
432
}
433
)
434
```
435
436
## Types
437
438
```python { .api }
439
class ServerInfo:
440
"""Information about the connected Neo4j server."""
441
address: Address
442
protocol_version: tuple
443
agent: str
444
445
class BookmarkManager:
446
"""Abstract base class for managing bookmarks."""
447
448
class AsyncBookmarkManager:
449
"""Abstract base class for async bookmark management."""
450
451
class RoutingControl:
452
"""Enum for controlling query routing."""
453
READ: str
454
WRITE: str
455
```