0
# Data Sources & Connectors
1

2
LoopBack's flexible data source management system supports multiple database types and external services through a pluggable connector architecture, enabling seamless integration with various data storage and service backends.
3

4
## Capabilities
5

6
### Data Source Creation
7

8
Create and configure data sources with different connectors and connection settings.
9

10
```javascript { .api }
11
/**
12
 * Create a data source with connector configuration
13
 * @param {string} name - Optional data source name
14
 * @param {Object} options - Data source configuration
15
 * @param {string|Function} options.connector - Connector name or constructor
16
 * @param {string} options.host - Database host
17
 * @param {number} options.port - Database port  
18
 * @param {string} options.database - Database name
19
 * @param {string} options.username - Database username
20
 * @param {string} options.password - Database password
21
 * @param {Object} options.settings - Additional connector settings
22
 * @returns {DataSource} Created data source instance
23
 */
24
loopback.createDataSource(name, options);
25

26
/**
27
 * Get or create in-memory data source
28
 * @param {string} name - Optional data source name (defaults to 'default')
29
 * @returns {DataSource} Memory data source instance
30
 */
31
loopback.memory(name);
32
```
33

34
**Usage Examples:**
35

36
```javascript
37
// MySQL data source
38
const mysqlDB = loopback.createDataSource('mysql', {
39
  connector: 'mysql',
40
  host: 'localhost',
41
  port: 3306,
42
  database: 'myapp',
43
  username: 'dbuser',
44
  password: 'dbpass',
45
  acquireTimeout: 60000,
46
  timeout: 60000
47
});
48

49
// MongoDB data source
50
const mongodb = loopback.createDataSource('mongodb', {
51
  connector: 'mongodb',
52
  url: 'mongodb://localhost:27017/myapp',
53
  allowExtendedOperators: true
54
});
55

56
// PostgreSQL data source
57
const postgresDB = loopback.createDataSource('postgres', {
58
  connector: 'postgresql',
59
  host: 'localhost',
60
  port: 5432,
61
  database: 'myapp',
62
  username: 'dbuser',
63
  password: 'dbpass',
64
  ssl: false
65
});
66

67
// REST API data source
68
const apiService = loopback.createDataSource('api', {
69
  connector: 'rest',
70
  baseURL: 'https://api.example.com',
71
  headers: {
72
    'Authorization': 'Bearer token123'
73
  }
74
});
75

76
// In-memory data source
77
const memoryDB = loopback.memory('cache');
78
```
79

80
### DataSource Class
81

82
The DataSource class from loopback-datasource-juggler provides database abstraction.
83

84
```javascript { .api }
85
/**
86
 * DataSource constructor (from loopback-datasource-juggler)
87
 * @param {string} name - Data source name
88
 * @param {Object} settings - Data source settings
89
 * @param {Function} modelBuilder - Optional model builder
90
 */
91
const DataSource = loopback.DataSource;
92

93
/**
94
 * DataSource instance methods
95
 */
96

97
/**
98
 * Connect to the data source
99
 * @param {Function} callback - Callback function
100
 */
101
dataSource.connect(callback);
102

103
/**
104
 * Disconnect from the data source
105
 * @param {Function} callback - Callback function
106
 */
107
dataSource.disconnect(callback);
108

109
/**
110
 * Check if data source is connected
111
 * @returns {boolean} Connection status
112
 */
113
dataSource.connected();
114

115
/**
116
 * Ping the data source
117
 * @param {Function} callback - Callback function
118
 */
119
dataSource.ping(callback);
120

121
/**
122
 * Create model on this data source
123
 * @param {string} name - Model name
124
 * @param {Object} properties - Model properties
125
 * @param {Object} settings - Model settings
126
 * @returns {Function} Model constructor
127
 */
128
dataSource.createModel(name, properties, settings);
129

130
/**
131
 * Define model on this data source
132
 * @param {string} name - Model name
133
 * @param {Object} properties - Model properties
134
 * @param {Object} settings - Model settings
135
 * @returns {Function} Model constructor
136
 */
137
dataSource.define(name, properties, settings);
138

139
/**
140
 * Attach existing model to this data source
141
 * @param {Function} ModelCtor - Model constructor
142
 */
143
dataSource.attach(ModelCtor);
144

145
/**
146
 * Auto-migrate database schema
147
 * @param {string|string[]} models - Model names to migrate
148
 * @param {Function} callback - Callback function
149
 */
150
dataSource.automigrate(models, callback);
151

152
/**
153
 * Auto-update database schema
154
 * @param {string|string[]} models - Model names to update
155
 * @param {Function} callback - Callback function
156
 */
157
dataSource.autoupdate(models, callback);
158

159
/**
160
 * Check if database exists
161
 * @param {Function} callback - Callback function
162
 */
163
dataSource.isActual(callback);
164
```
165

166
### Built-in Connectors
167

168
LoopBack includes several built-in connectors for common data sources.
169

170
```javascript { .api }
171
/**
172
 * Memory connector for in-memory storage
173
 */
174
const Memory = loopback.Memory;
175

176
/**
177
 * Memory connector constructor
178
 * @param {Object} settings - Connector settings
179
 */
180
function Memory(settings);
181

182
/**
183
 * Mail connector for email services
184
 */
185
const Mail = loopback.Mail;
186

187
/**
188
 * Mail connector constructor  
189
 * @param {Object} settings - Mail settings
190
 * @param {Object} settings.transports - Transport configurations
191
 * @param {string} settings.transports.type - Transport type
192
 */
193
function Mail(settings);
194

195
/**
196
 * Remote connector for REST APIs
197
 */
198
const Remote = loopback.Remote;
199

200
/**
201
 * Base connector class
202
 */
203
const Connector = loopback.Connector;
204

205
/**
206
 * Base connector constructor
207
 * @param {Object} settings - Connector settings
208
 */
209
function Connector(settings);
210
```
211

212
### Mail Connector Configuration
213

214
Email sending capabilities through various transport providers.
215

216
```javascript { .api }
217
/**
218
 * Mail connector with transport configuration
219
 */
220
const mailConnector = {
221
  connector: Mail,
222
  transports: [
223
    {
224
      type: 'smtp',
225
      host: 'smtp.gmail.com',
226
      port: 587,
227
      secure: false,
228
      auth: {
229
        user: 'sender@gmail.com',
230
        pass: 'password'
231
      }
232
    },
233
    {
234
      type: 'direct',
235
      name: 'localhost'
236
    },
237
    {
238
      type: 'stub' // For testing
239
    }
240
  ]
241
};
242

243
/**
244
 * Mail connector methods
245
 */
246

247
/**
248
 * Setup email transport
249
 */
250
mailConnector.setupTransport();
251

252
/**
253
 * Get transport by name
254
 * @param {string} name - Transport name
255
 * @returns {Object} Transport instance
256
 */
257
mailConnector.transportForName(name);
258

259
/**
260
 * Get default transport
261
 * @returns {Object} Default transport
262
 */
263
mailConnector.defaultTransport();
264

265
/**
266
 * Mailer class for sending emails
267
 */
268
class Mailer {
269
  /**
270
   * Send email message
271
   * @param {Object} options - Email options
272
   * @param {string} options.from - Sender address
273
   * @param {string} options.to - Recipient address
274
   * @param {string} options.subject - Email subject
275
   * @param {string} options.text - Plain text content
276
   * @param {string} options.html - HTML content
277
   * @param {Function} callback - Callback function
278
   */
279
  send(options, callback);
280
}
281
```
282

283
**Usage Example:**
284

285
```javascript
286
// Configure mail data source
287
const emailDS = loopback.createDataSource('email', {
288
  connector: loopback.Mail,
289
  transports: [{
290
    type: 'smtp',
291
    host: 'smtp.gmail.com',
292
    port: 587,
293
    secure: false,
294
    auth: {
295
      user: process.env.EMAIL_USER,
296
      pass: process.env.EMAIL_PASS
297
    }
298
  }]
299
});
300

301
// Attach Email model to mail data source
302
app.model(loopback.Email, { dataSource: emailDS });
303
```
304

305
### Connector Registration
306

307
Register custom connectors with applications.
308

309
```javascript { .api }
310
/**
311
 * Register connector with application (from application.js)
312
 * @param {string} name - Connector name
313
 * @param {Function} connector - Connector constructor
314
 */
315
app.connector(name, connector);
316
```
317

318
**Usage Example:**
319

320
```javascript
321
// Register custom connector
322
app.connector('custom', MyCustomConnector);
323

324
// Use custom connector
325
const customDS = app.dataSource('custom', {
326
  connector: 'custom',
327
  customOption: 'value'
328
});
329
```
330

331
### Key-Value Store Connector
332

333
Built-in key-value store connector for simple storage operations.
334

335
```javascript { .api }
336
/**
337
 * Key-value memory connector (from datasource-juggler)
338
 */
339
const kvMemory = require('loopback-datasource-juggler/lib/connectors/kv-memory');
340

341
/**
342
 * Key-value operations available through KeyValueModel
343
 */
344

345
/**
346
 * Get value by key
347
 * @param {string} key - Key to retrieve
348
 * @param {Function} callback - Callback function
349
 */
350
KeyValueModel.get(key, callback);
351

352
/**
353
 * Set key-value pair
354
 * @param {string} key - Key to set
355
 * @param {*} value - Value to store
356
 * @param {number} ttl - Time to live in seconds (optional)
357
 * @param {Function} callback - Callback function
358
 */
359
KeyValueModel.set(key, value, ttl, callback);
360

361
/**
362
 * Set expiration for key
363
 * @param {string} key - Key to expire
364
 * @param {number} ttl - Time to live in seconds
365
 * @param {Function} callback - Callback function
366
 */
367
KeyValueModel.expire(key, ttl, callback);
368

369
/**
370
 * Get time to live for key
371
 * @param {string} key - Key to check
372
 * @param {Function} callback - Callback function
373
 */
374
KeyValueModel.ttl(key, callback);
375

376
/**
377
 * Delete key
378
 * @param {string} key - Key to delete
379
 * @param {Function} callback - Callback function
380
 */
381
KeyValueModel.delete(key, callback);
382

383
/**
384
 * Get all keys matching pattern
385
 * @param {string} pattern - Key pattern (* for all)
386
 * @param {Function} callback - Callback function
387
 */
388
KeyValueModel.keys(pattern, callback);
389
```
390

391
**Usage Example:**
392

393
```javascript
394
// Create key-value data source
395
const kvStore = loopback.createDataSource('kv', {
396
  connector: 'kv-memory'
397
});
398

399
// Attach KeyValueModel
400
const Cache = loopback.createModel('Cache', {}, {
401
  base: 'KeyValueModel'
402
});
403
Cache.attachTo(kvStore);
404

405
// Use key-value operations
406
Cache.set('user:123', { name: 'John', age: 30 }, 3600, (err) => {
407
  if (err) return console.error(err);
408
  
409
  Cache.get('user:123', (err, user) => {
410
    console.log('Retrieved user:', user);
411
  });
412
});
413
```
414

415
### Data Source Configuration Types
416

417
Configuration interfaces for different data source types.
418

419
```javascript { .api }
420
/**
421
 * Common data source settings
422
 */
423
interface DataSourceSettings {
424
  connector: string | Function;    // Connector name or constructor
425
  host?: string;                  // Database host
426
  port?: number;                  // Database port
427
  database?: string;              // Database name
428
  username?: string;              // Database username
429
  password?: string;              // Database password
430
  url?: string;                   // Connection URL
431
  debug?: boolean;                // Enable debug mode
432
  lazyConnect?: boolean;          // Lazy connection
433
}
434

435
/**
436
 * MySQL/PostgreSQL specific settings
437
 */
438
interface SQLDataSourceSettings extends DataSourceSettings {
439
  acquireTimeout?: number;        // Connection acquire timeout
440
  timeout?: number;               // Query timeout
441
  reconnectTries?: number;        // Reconnection attempts
442
  ssl?: boolean | Object;         // SSL configuration
443
  timezone?: string;              // Database timezone
444
}
445

446
/**
447
 * MongoDB specific settings
448
 */
449
interface MongoDataSourceSettings extends DataSourceSettings {
450
  allowExtendedOperators?: boolean;   // Allow MongoDB operators
451
  enableGeoIndexing?: boolean;        // Enable geo indexing
452
  maxPoolSize?: number;              // Connection pool size
453
  authSource?: string;               // Authentication database
454
}
455

456
/**
457
 * REST API specific settings
458
 */
459
interface RESTDataSourceSettings extends DataSourceSettings {
460
  baseURL: string;                   // API base URL
461
  headers?: Object;                  // Default headers
462
  timeout?: number;                  // Request timeout
463
  auth?: Object;                     // Authentication config
464
  proxy?: string;                    // Proxy configuration
465
}
466

467
/**
468
 * Mail specific settings
469
 */
470
interface MailDataSourceSettings extends DataSourceSettings {
471
  transports: Array<{
472
    type: string;                    // Transport type (smtp, direct, stub)
473
    host?: string;                   // SMTP host
474
    port?: number;                   // SMTP port
475
    secure?: boolean;                // Use SSL/TLS
476
    auth?: {                        // Authentication
477
      user: string;
478
      pass: string;
479
    };
480
  }>;
481
}
482
```