0
# Driver Management
1

2
Core driver creation and connection management functionality for establishing and maintaining database connections with Neo4j instances.
3

4
## Capabilities
5

6
### Driver Creation
7

8
Creates a Neo4j driver instance for connecting to a database.
9

10
```typescript { .api }
11
/**
12
 * Construct a new Neo4j Driver. This is your main entry point for this library.
13
 * @param url - The URL for the Neo4j database, supports neo4j://, neo4j+s://, neo4j+ssc://, bolt://, bolt+s://, bolt+ssc:// schemes
14
 * @param authToken - Authentication credentials or auth token manager
15
 * @param config - Configuration object for driver behavior
16
 * @returns Driver instance for database operations
17
 */
18
function driver(
19
  url: string,
20
  authToken?: AuthToken | AuthTokenManager,
21
  config?: Config
22
): Driver;
23
```
24

25
**URL Schemes:**
26
- `neo4j://` - Routing driver with default encryption
27
- `neo4j+s://` - Routing driver with system CA certificates
28
- `neo4j+ssc://` - Routing driver trusting all certificates
29
- `bolt://` - Direct connection with default encryption
30
- `bolt+s://` - Direct connection with system CA certificates
31
- `bolt+ssc://` - Direct connection trusting all certificates
32

33
**Usage Examples:**
34

35
```typescript
36
import { driver, auth } from "neo4j-driver";
37

38
// Basic connection
39
const neo4jDriver = driver(
40
  "neo4j://localhost:7687",
41
  auth.basic("neo4j", "password")
42
);
43

44
// With configuration
45
const configuredDriver = driver(
46
  "neo4j://localhost:7687",
47
  auth.basic("neo4j", "password"),
48
  {
49
    maxConnectionLifetime: 3600000, // 1 hour
50
    maxConnectionPoolSize: 50,
51
    connectionAcquisitionTimeout: 60000,
52
    encrypted: "ENCRYPTION_ON",
53
    trust: "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES"
54
  }
55
);
56

57
// Using cluster endpoint
58
const clusterDriver = driver(
59
  "neo4j://cluster.example.com:7687",
60
  auth.basic("neo4j", "password")
61
);
62
```
63

64
### Server Reachability Check
65

66
Verifies if the driver can reach a server at the given URL without authentication.
67

68
```typescript { .api }
69
/**
70
 * Verifies if the driver can reach a server at the given url.
71
 * @experimental
72
 * @param url - The URL for the Neo4j database
73
 * @param config - Optional configuration object (logging only)
74
 * @returns Promise that resolves to true when server is reachable
75
 * @throws Error when the server is not reachable or the url is invalid
76
 */
77
function hasReachableServer(
78
  url: string,
79
  config?: Pick<Config, 'logging'>
80
): Promise<true>;
81
```
82

83
**Usage Example:**
84

85
```typescript
86
import { hasReachableServer } from "neo4j-driver";
87

88
try {
89
  await hasReachableServer("neo4j://localhost:7687");
90
  console.log("Server is reachable");
91
} catch (error) {
92
  console.error("Server is not reachable:", error.message);
93
}
94
```
95

96
### Driver Interface
97

98
Main driver interface providing session creation and lifecycle management.
99

100
```typescript { .api }
101
interface Driver {
102
  /** Create a new session with optional configuration */
103
  session(config?: SessionConfig): Session;
104
  
105
  /** Create a new reactive session with optional configuration */
106
  rxSession(config?: SessionConfig): RxSession;
107
  
108
  /** Get information about the Neo4j server */
109
  getServerInfo(): Promise<ServerInfo>;
110
  
111
  /** Check if the driver supports multi-database functionality */
112
  supportsMultiDb(): Promise<boolean>;
113
  
114
  /** Check if the driver is encrypted */
115
  isEncrypted(): boolean;
116
  
117
  /** Verify connectivity and return negotiated protocol version */
118
  verifyConnectivity(config?: { database?: string }): Promise<ServerInfo>;
119
  
120
  /** Get the negotiated protocol version without authentication */
121
  getNegotiatedProtocolVersion(): Promise<number>;
122
  
123
  /** Close the driver and all associated resources */
124
  close(): Promise<void>;
125
}
126
```
127

128
### Driver Configuration
129

130
Comprehensive configuration options for driver behavior.
131

132
```typescript { .api }
133
interface Config {
134
  /** Encryption level for connections */
135
  encrypted?: EncryptionLevel;
136
  
137
  /** Trust strategy for TLS certificates */
138
  trust?: TrustStrategy;
139
  
140
  /** List of trusted certificates for custom CA */
141
  trustedCertificates?: string[];
142
  
143
  /** Known hosts file path for certificate verification */
144
  knownHosts?: string;
145
  
146
  /** Maximum lifetime of pooled connections in milliseconds */
147
  maxConnectionLifetime?: number;
148
  
149
  /** Maximum number of connections in the pool */
150
  maxConnectionPoolSize?: number;
151
  
152
  /** Timeout for acquiring connections from pool in milliseconds */
153
  connectionAcquisitionTimeout?: number;
154
  
155
  /** Disable automatic conversion to native JavaScript numbers */
156
  disableLosslessIntegers?: boolean;
157
  
158
  /** Custom logging configuration */
159
  logging?: LoggingConfig;
160
  
161
  /** Custom address resolver function */
162
  resolver?: (address: string) => string[] | Promise<string[]>;
163
  
164
  /** Custom user agent string */
165
  userAgent?: string;
166
  
167
  /** Bolt agent metadata */
168
  boltAgent?: Record<string, any>;
169
  
170
  /** Global notification filtering */
171
  notificationFilter?: NotificationFilter;
172
  
173
  /** Disable telemetry reporting */
174
  telemetryDisabled?: boolean;
175
  
176
  /** Client certificate for mutual TLS */
177
  clientCertificate?: ClientCertificate | ClientCertificateProvider;
178
}
179

180
type EncryptionLevel = "ENCRYPTION_ON" | "ENCRYPTION_OFF";
181
type TrustStrategy = "TRUST_ALL_CERTIFICATES" | "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES";
182

183
interface LoggingConfig {
184
  level: "DEBUG" | "INFO" | "WARN" | "ERROR";
185
  logger: (level: string, message: string) => void;
186
}
187
```
188

189
### Logging Configuration
190

191
Pre-configured logging options for driver debugging and monitoring.
192

193
```typescript { .api }
194
declare const logging: {
195
  /** Console logging configuration with optional level filtering */
196
  console: (level?: "DEBUG" | "INFO" | "WARN" | "ERROR") => LoggingConfig;
197
};
198
```
199

200
**Usage Example:**
201

202
```typescript
203
import { driver, auth, logging } from "neo4j-driver";
204

205
const neo4jDriver = driver(
206
  "neo4j://localhost:7687",
207
  auth.basic("neo4j", "password"),
208
  {
209
    logging: logging.console("DEBUG"),
210
    maxConnectionPoolSize: 100,
211
    connectionAcquisitionTimeout: 60000
212
  }
213
);
214
```
215

216
### Server Information
217

218
Information about the connected Neo4j server.
219

220
```typescript { .api }
221
interface ServerInfo {
222
  address: string;
223
  agent: string;
224
  protocolVersion: number;
225
}
226
```