-
Notifications
You must be signed in to change notification settings - Fork 13
/
create-manager.js
291 lines (240 loc) · 11.7 KB
/
create-manager.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
// Dependencies
var util = require('util');
var url = require('url');
var _ = require('@sailshq/lodash');
var pg = require('pg');
module.exports = {
friendlyName: 'Create manager',
description: 'Build and initialize a connection manager instance for this database.',
extendedDescription:
'The `manager` instance returned by this method contains any configuration that is necessary ' +
'for communicating with the database and establishing connections (e.g. host, user, password) ' +
'as well as any other relevant metadata. The manager will often also contain a reference ' +
'to some kind of native container (e.g. a connection pool).\n' +
'\n' +
'Note that a manager instance does not necessarily need to correspond with a pool though--' +
'it might simply be a container for storing config, or it might refer to multiple pools.',
sync: true,
inputs: {
connectionString: {
description: 'A connection string to use to connect to a Postgresql database.',
extendedDescription: 'Be sure to include credentials. You can also optionally provide the name of an existing database on your Postgresql server.',
example: 'postgres://mikermcneil:p4ssw02D@localhost:5432/some_db',
required: true
},
onUnexpectedFailure: {
description: 'A function to call any time an unexpected error event is received from this manager or any of its connections.',
extendedDescription:
'This can be used for anything you like, whether that\'s sending an email to devops, ' +
'or something as simple as logging a warning to the console.\n' +
'\n' +
'For example:\n' +
'```\n' +
'onUnexpectedFailure: function (err) {\n' +
' console.warn(\'Unexpected failure in database manager:\',err);\n' +
'}\n' +
'```',
example: '->'
},
meta: {
friendlyName: 'Meta (custom)',
description: 'Additional PostgreSQL-specific options to use when connecting.',
extendedDescription: 'If specified, should be a dictionary. If there is a conflict between something provided in the connection string, and something in `meta`, the connection string takes priority.',
moreInfoUrl: 'https://github.com/coopernurse/node-pool#documentation',
example: '==='
}
},
exits: {
success: {
description: 'The manager was successfully created.',
extendedDescription:
'The new manager should be passed in to `getConnection()`.' +
'Note that _no matter what_, this manager must be capable of ' +
'spawning an infinite number of connections (i.e. via `getConnection()`). ' +
'The implementation of how exactly it does this varies on a driver-by-driver ' +
'basis; and it may also vary based on the configuration passed into the `meta` input.',
outputVariableName: 'report',
outputDescription: 'The `manager` property is a manager instance that will be passed into `getConnection()`. The `meta` property is reserved for custom driver-specific extensions.',
outputExample: '==='
// example: {
// manager: '===',
// meta: '==='
// }
},
malformed: {
description: 'The provided connection string is not valid for Postgresql.',
outputVariableName: 'report',
outputDescription: 'The `error` property is a JavaScript Error instance explaining that (and preferably "why") the provided connection string is invalid. The `meta` property is reserved for custom driver-specific extensions.',
outputExample: '==='
// example: {
// error: '===',
// meta: '==='
// }
},
failed: {
description: 'Could not create a connection manager for this database using the specified connection string.',
extendedDescription:
'If this exit is called, it might mean any of the following:\n' +
' + the credentials encoded in the connection string are incorrect\n' +
' + there is no database server running at the provided host (i.e. even if it is just that the database process needs to be started)\n' +
' + there is no software "database" with the specified name running on the server\n' +
' + the provided connection string does not have necessary access rights for the specified software "database"\n' +
' + this Node.js process could not connect to the database, perhaps because of firewall/proxy settings\n' +
' + any other miscellaneous connection error\n' +
'\n' +
'Note that even if the database is unreachable, bad credentials are being used, etc, ' +
'this exit will not necessarily be called-- that depends on the implementation of the driver ' +
'and any special configuration passed to the `meta` input. e.g. if a pool is being used that spins up ' +
'multiple connections immediately when the manager is created, then this exit will be called if any of ' +
'those initial attempts fail. On the other hand, if the manager is designed to produce adhoc connections, ' +
'any errors related to bad credentials, connectivity, etc. will not be caught until `getConnection()` is called.',
outputVariableName: 'report',
outputDescription: 'The `error` property is a JavaScript Error instance with more information and a stack trace. The `meta` property is reserved for custom driver-specific extensions.',
outputExample: '==='
// example: {
// error: '===',
// meta: '==='
// }
}
},
fn: function createManager(inputs, exits) {
// Note:
// Support for different types of managers is database-specific, and is not
// built into the Waterline driver spec-- however this type of configurability
// can be instrumented using `meta`.
//
// In particular, support for ad-hoc connections (i.e. no pool) and clusters/multiple
// pools (see "pg-pool": https://github.com/brianc/node-pg-pool)
// could be implemented here, using properties on `meta` to determine whether or not
// to have this manager produce connections ad-hoc, from a pool, or from a cluster of pools.
//
// Feel free to fork this driver and customize as you see fit. Also note that
// contributions to the core driver in this area are welcome and greatly appreciated!
// Build a local variable (`_clientConfig`) to house a dictionary
// of additional Postgres options that will be passed into `.createPool()`
// (Note that these could also be used with `.connect()` or `.createPoolCluster()`)
//
// This is pulled from the `connectionString` and `meta` inputs, and used for
// configuring stuff like `host` and `password`.
//
// For a complete list of available options, see:
// • https://github.com/brianc/node-postgres/wiki/Client#parameters
// • https://github.com/coopernurse/node-pool#documentation
//
// However, note that supported options are explicitly whitelisted below.
var _clientConfig = {};
// Validate and parse `meta` (if specified).
if (!_.isUndefined(inputs.meta)) {
if (!_.isObject(inputs.meta)) {
return exits.error('If provided, `meta` must be a dictionary.');
}
// Use properties of `meta` directly as Postgres client config.
// (note that we're very careful to only stick a property on the client config
// if it was not undefined, just in case that matters)
var configOptions = [
// Postgres Client Options:
// ============================================
// Basic:
'host', 'port', 'database', 'user', 'password', 'ssl',
// Advanced Client Config:
'application_name', 'fallback_application_name',
// General Pool Config:
'max', 'min', 'refreshIdle', 'idleTimeoutMillis',
// Advanced Pool Config:
// These should only be used if you know what you are doing.
// https://github.com/coopernurse/node-pool#documentation
'name', 'create', 'destroy', 'reapIntervalMillis', 'returnToHead',
'priorityRange', 'validate', 'validateAsync', 'log'
];
_.each(configOptions, function addConfigValue(clientConfKeyName) {
if (!_.isUndefined(inputs.meta[clientConfKeyName])) {
_clientConfig[clientConfKeyName] = inputs.meta[clientConfKeyName];
}
});
// In the future, other special properties of `meta` could be used
// as options for the manager-- e.g. whether or not to use pooling,
// or the connection strings of replicas, etc.
}
// Validate & parse connection string, pulling out Postgres client config
// (call `malformed` if invalid).
//
// Remember: connection string takes priority over `meta` in the event of a conflict.
try {
var urlToParse = inputs.connectionString;
// We don't actually care about the protocol, but `url.parse()` returns funky results
// if the argument doesn't have one. So we'll add one if necessary.
// See https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax
if (!urlToParse.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//)) {
urlToParse = 'postgresql://' + urlToParse;
}
var parsedConnectionStr = url.parse(urlToParse);
// Parse port & host
var DEFAULT_HOST = 'localhost';
var DEFAULT_PORT = 5432;
if (parsedConnectionStr.port) {
_clientConfig.port = +parsedConnectionStr.port;
} else {
_clientConfig.port = DEFAULT_PORT;
}
if (parsedConnectionStr.hostname) {
_clientConfig.host = parsedConnectionStr.hostname;
} else {
_clientConfig.host = DEFAULT_HOST;
}
// Parse user & password
if (parsedConnectionStr.auth && _.isString(parsedConnectionStr.auth)) {
var authPieces = parsedConnectionStr.auth.split(/:/);
if (authPieces[0]) {
_clientConfig.user = authPieces[0];
}
if (authPieces[1]) {
_clientConfig.password = authPieces[1];
}
}
// Parse database name
if (_.isString(parsedConnectionStr.pathname)) {
var _databaseName = parsedConnectionStr.pathname;
// Trim leading and trailing slashes
_databaseName = _databaseName.replace(/^\/+/, '');
_databaseName = _databaseName.replace(/\/+$/, '');
// If anything is left, use it as the database name.
if (_databaseName) {
_clientConfig.database = _databaseName;
}
}
} catch (_e) {
_e.message = util.format('Provided value (`%s`) is not a valid Postgres connection string.', inputs.connectionString) + ' Error details: ' + _e.message;
return exits.malformed({
error: _e,
meta: inputs.meta
});
}
// Create a connection pool.
//
// More about using pools with node-pg:
// • https://github.com/brianc/node-pg-pool
var pool = new pg.Pool(_clientConfig);
// Bind an "error" handler in order to handle errors from connections in the pool,
// or from the pool itself. Otherwise, without any further protection, if any Postgres
// connections in the pool die, then the process would crash with an error.
//
// For more background, see:
// • https://github.com/brianc/node-pg-pool#error
pool.on('error', function error(err) {
// When/if something goes wrong in this pool, call the `onUnexpectedFailure` notifier
// (if one was provided)
if (!_.isUndefined(inputs.onUnexpectedFailure)) {
inputs.onUnexpectedFailure(err || new Error('One or more pooled connections to Postgres database were lost. Did the database server go offline?'));
}
});
// Finally, build and return the manager.
var mgr = {
pool: pool,
connectionString: inputs.connectionString
};
return exits.success({
manager: mgr,
meta: inputs.meta
});
}
};