0
# Connection Management
1

2
Core database connectivity functionality for creating and managing Oracle Database connections.
3

4
## Capabilities
5

6
### Get Connection
7

8
Creates a single database connection with specified configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a database connection
13
 * @param config - Connection configuration object
14
 * @returns Promise resolving to Connection instance
15
 */
16
function getConnection(config: ConnectionAttributes): Promise<Connection>;
17

18
interface ConnectionAttributes {
19
  user?: string;
20
  password?: string;
21
  newPassword?: string;
22
  accessToken?: string | AccessTokenCallback;
23
  connectString?: string;
24
  connectionClass?: string;
25
  privilege?: number;
26
  externalAuth?: boolean;
27
  stmtCacheSize?: number;
28
  edition?: string;
29
  events?: boolean;
30
  tag?: string;
31
  shardingKey?: (string | number | Date)[];
32
  superShardingKey?: (string | number | Date)[];
33
}
34

35
type AccessTokenCallback = (refresh: boolean, accessTokenConfig: AccessTokenConfig) => Promise<AccessToken>;
36

37
interface AccessTokenConfig {
38
  user: string;
39
  connectString: string;
40
}
41

42
interface AccessToken {
43
  token: string;
44
  privateKey?: string;
45
}
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
const oracledb = require('oracledb');
52

53
// Basic connection
54
const connection = await oracledb.getConnection({
55
  user: "hr",
56
  password: "welcome123",
57
  connectString: "localhost:1521/XE"
58
});
59

60
// Connection with connection class
61
const connection = await oracledb.getConnection({
62
  user: "hr",
63
  password: "welcome123", 
64
  connectString: "localhost:1521/XE",
65
  connectionClass: "POOLED"
66
});
67

68
// External authentication
69
const connection = await oracledb.getConnection({
70
  externalAuth: true,
71
  connectString: "localhost:1521/XE"
72
});
73

74
// Always close connections
75
await connection.close();
76
```
77

78
### Create Pool
79

80
Creates a connection pool for scalable database access.
81

82
```javascript { .api }
83
/**
84
 * Creates a connection pool
85
 * @param config - Pool configuration object
86
 * @returns Promise resolving to Pool instance
87
 */
88
function createPool(config: PoolAttributes): Promise<Pool>;
89

90
interface PoolAttributes extends ConnectionAttributes {
91
  poolAlias?: string;
92
  poolIncrement?: number;
93
  poolMax?: number;
94
  poolMaxPerShard?: number;
95
  poolMin?: number;
96
  poolPingInterval?: number;
97
  poolPingTimeout?: number;
98
  poolTimeout?: number;
99
  queueMax?: number;
100
  queueTimeout?: number;
101
  sessionCallback?: string | SessionCallback;
102
  sodaMetaDataCache?: boolean;
103
  enableStatistics?: boolean;
104
}
105

106
type SessionCallback = (connection: Connection, requestedTag: string, callbackFn: (error?: Error, connection?: Connection) => void) => void;
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
// Create a connection pool
113
const pool = await oracledb.createPool({
114
  user: "hr",
115
  password: "welcome123",
116
  connectString: "localhost:1521/XE",
117
  poolMin: 10,
118
  poolMax: 20,
119
  poolIncrement: 5,
120
  poolTimeout: 300
121
});
122

123
// Get connection from pool
124
const connection = await pool.getConnection();
125
await connection.execute('SELECT 1 FROM dual');
126
await connection.close(); // Returns to pool
127

128
// Close the pool
129
await pool.close();
130
```
131

132
### Get Pool
133

134
Retrieves an existing connection pool by alias.
135

136
```javascript { .api }
137
/**
138
 * Gets an existing pool by alias
139
 * @param alias - Pool alias (optional, defaults to 'default')
140
 * @returns Pool instance
141
 */
142
function getPool(alias?: string): Pool;
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
// Create pool with alias
149
await oracledb.createPool({
150
  user: "hr",
151
  password: "welcome123",
152
  connectString: "localhost:1521/XE",
153
  poolAlias: "hrpool"
154
});
155

156
// Get pool by alias
157
const pool = oracledb.getPool("hrpool");
158
const connection = await pool.getConnection();
159
```
160

161
### Initialize Oracle Client
162

163
Initializes Oracle Client libraries for thick mode operation.
164

165
```javascript { .api }
166
/**
167
 * Initializes Oracle Client libraries
168
 * @param options - Client initialization options
169
 */
170
function initOracleClient(options?: InitOracleClientOptions): void;
171

172
interface InitOracleClientOptions {
173
  libDir?: string;
174
  configDir?: string;
175
  errorUrl?: string;
176
  driverName?: string;
177
}
178
```
179

180
**Usage Examples:**
181

182
```javascript
183
// Initialize Oracle Client (must be called before other operations)
184
oracledb.initOracleClient({
185
  libDir: '/usr/lib/oracle/19.3/client64/lib'
186
});
187

188
// Now thick mode features are available
189
const connection = await oracledb.getConnection(config);
190
```
191

192
### Get Network Service Names
193

194
Retrieves network service names from configuration files.
195

196
```javascript { .api }
197
/**
198
 * Gets network service names from tnsnames.ora
199
 * @returns Promise resolving to array of service names
200
 */
201
function getNetworkServiceNames(): Promise<string[]>;
202
```
203

204
**Usage Examples:**
205

206
```javascript
207
// Get available network service names
208
const serviceNames = await oracledb.getNetworkServiceNames();
209
console.log('Available services:', serviceNames);
210

211
// Use a service name for connection
212
const connection = await oracledb.getConnection({
213
  user: "hr",
214
  password: "welcome123",
215
  connectString: serviceNames[0]
216
});
217
```
218

219
### Database Startup and Shutdown
220

221
Administrative functions for starting up and shutting down Oracle Database instances.
222

223
```javascript { .api }
224
/**
225
 * Starts up an Oracle Database instance
226
 * @param options - Startup options
227
 * @returns Promise that resolves when startup is complete
228
 */
229
function startup(options?: StartupOptions): Promise<void>;
230

231
/**
232
 * Shuts down an Oracle Database instance
233
 * @param mode - Shutdown mode
234
 * @param options - Shutdown options
235
 * @returns Promise that resolves when shutdown is complete
236
 */
237
function shutdown(mode?: number, options?: ShutdownOptions): Promise<void>;
238

239
interface StartupOptions {
240
  force?: boolean;
241
  restrict?: boolean;
242
  pfile?: string;
243
}
244

245
interface ShutdownOptions {
246
  force?: boolean;
247
}
248

249
// Shutdown mode constants
250
const SHUTDOWN_MODE_DEFAULT = 0;
251
const SHUTDOWN_MODE_TRANSACTIONAL = 1;
252
const SHUTDOWN_MODE_TRANSACTIONAL_LOCAL = 2;
253
const SHUTDOWN_MODE_IMMEDIATE = 3;
254
const SHUTDOWN_MODE_ABORT = 4;
255
const SHUTDOWN_MODE_FINAL = 5;
256

257
// Startup mode constants  
258
const STARTUP_MODE_DEFAULT = 0;
259
const STARTUP_MODE_FORCE = 1;
260
const STARTUP_MODE_RESTRICT = 2;
261
```
262

263
**Usage Examples:**
264

265
```javascript
266
// Startup database (requires SYSDBA privileges)
267
const connection = await oracledb.getConnection({
268
  user: "sys",
269
  password: "password",
270
  connectString: "localhost:1521/XE",
271
  privilege: oracledb.SYSDBA
272
});
273

274
await oracledb.startup();
275
console.log('Database started successfully');
276

277
// Shutdown database gracefully
278
await oracledb.shutdown(oracledb.SHUTDOWN_MODE_IMMEDIATE);
279
console.log('Database shut down');
280

281
await connection.close();
282
```
283

284
## Connection Class Properties
285

286
```javascript { .api }
287
interface Connection {
288
  // Connection identification
289
  action: string;
290
  clientId: string;
291
  clientInfo: string;
292
  module: string;
293
  
294
  // Database information
295
  dbDomain: string;           // read-only
296
  dbName: string;             // read-only
297
  oracleServerVersion: number; // read-only
298
  oracleServerVersionString: string; // read-only
299
  
300
  // Connection state
301
  currentSchema: string;
302
  stmtCacheSize: number;
303
  tag: string;
304
  thin: boolean;              // read-only
305
  transactionInProgress: boolean; // read-only
306
  
307
  // Performance and monitoring
308
  callTimeout: number;
309
  maxOpenCursors: number;     // read-only
310
  warning: ConnectionWarning; // read-only
311
  
312
  // Operation context
313
  dbOp: string;
314
  ecid: string;
315
  externalName: string;
316
  internalName: string;
317
}
318

319
interface ConnectionWarning {
320
  message: string;
321
  offset: number;
322
}
323
```