Add deprecations

This adds deprecations in preparation for `pg@7.0`

- deprecate using event emitters on automatically created results from client.query.
- deprecate query.promise() - it should never have been a public method and it's not documented. I need to do better about using _ prefix on private methods in the future.
- deprecate singleton pool on the `pg` object. `pg.connect`, `pg.end`, and `pg.cancel`.

Author: brianc

lib/client.js

@@ -13,6 +13,7 @@ var pgPass = require('pgpass');
 var TypeOverrides = require('./type-overrides');
 
 var ConnectionParameters = require('./connection-parameters');
+var utils = require('./utils');
 var Query = require('./query');
 var defaults = require('./defaults');
 var Connection = require('./connection');
@@ -348,10 +349,12 @@ Client.prototype.copyTo = function (text) {
   throw new Error("For PostgreSQL COPY TO/COPY FROM support npm install pg-copy-streams");
 };
 
+var DeprecatedEmitterQuery = utils.deprecateEventEmitter(Query);
+
 Client.prototype.query = function(config, values, callback) {
   //can take in strings, config object or query object
   var query = (typeof config.submit == 'function') ? config :
-     new Query(config, values, callback);
+     new DeprecatedEmitterQuery(config, values, callback);
   if(this.binary && !query.binary) {
     query.binary = true;
   }

lib/index.js

@@ -27,7 +27,7 @@ var PG = function(clientConstructor) {
 
 util.inherits(PG, EventEmitter);
 
-PG.prototype.end = function() {
+PG.prototype.end = util.deprecate(function() {
   var self = this;
   var keys = Object.keys(this._pools);
   var count = keys.length;
@@ -47,9 +47,9 @@ PG.prototype.end = function() {
       });
     });
   }
-};
+}, 'PG.end is deprecated - please see the upgrade guide at https://node-postgres.com/guides/upgrading');
 
-PG.prototype.connect = function(config, callback) {
+PG.prototype.connect = util.deprecate(function(config, callback) {
   if(typeof config == "function") {
     callback = config;
     config = null;
@@ -75,10 +75,10 @@ PG.prototype.connect = function(config, callback) {
     }.bind(this));
   }
   return pool.connect(callback);
-};
+}, 'PG.connect is deprecated - please see the upgrade guide at https://node-postgres.com/guides/upgrading');
 
 // cancel the query running on the given client
-PG.prototype.cancel = function(config, client, query) {
+PG.prototype.cancel = util.deprecate(function(config, client, query) {
   if(client.native) {
     return client.cancel(query);
   }
@@ -89,7 +89,7 @@ PG.prototype.cancel = function(config, client, query) {
   }
   var cancellingClient = new this.Client(c);
   cancellingClient.cancel(client, query);
-};
+}, 'PG.cancel is deprecated - use client.cancel instead');
 
 if(typeof process.env.NODE_PG_FORCE_NATIVE != 'undefined') {
   module.exports = new PG(require('./native'));

lib/native/index.js

@@ -46,6 +46,8 @@ var Client = module.exports = function(config) {
   this.namedQueries = {};
 };
 
+Client.Query = NativeQuery;
+
 util.inherits(Client, EventEmitter);
 
 //connect to the backend
@@ -139,6 +141,35 @@ Client.prototype.query = function(config, values, callback) {
   return query;
 };
 
+var DeprecatedQuery = require('../utils').deprecateEventEmitter(NativeQuery);
+
+//send a query to the server
+//this method is highly overloaded to take
+//1) string query, optional array of parameters, optional function callback
+//2) object query with {
+//    string query
+//    optional array values,
+//    optional function callback instead of as a separate parameter
+//    optional string name to name & cache the query plan
+//    optional string rowMode = 'array' for an array of results
+//  }
+Client.prototype.query = function(config, values, callback) {
+  if (typeof config.submit == 'function') {
+    // accept query(new Query(...), (err, res) => { }) style
+    if (typeof values == 'function') {
+      config.callback = values;
+    }
+    this._queryQueue.push(config);
+    this._pulseQueryQueue();
+    return config;
+  }
+
+  var query = new DeprecatedQuery(config, values, callback);
+  this._queryQueue.push(query);
+  this._pulseQueryQueue();
+  return query;
+};
+
 //disconnect from the backend server
 Client.prototype.end = function(cb) {
   var self = this;

lib/native/query.js

@@ -11,15 +11,15 @@ var util = require('util');
 var utils = require('../utils');
 var NativeResult = require('./result');
 
-var NativeQuery = module.exports = function(native) {
+var NativeQuery = module.exports = function(config, values, callback) {
   EventEmitter.call(this);
-  this.native = native;
-  this.text = null;
-  this.values = null;
-  this.name = null;
-  this.callback = null;
+  config = utils.normalizeQueryConfig(config, values, callback);
+  this.text = config.text;
+  this.values = config.values;
+  this.name = config.name;
+  this.callback = config.callback;
   this.state = 'new';
-  this._arrayMode = false;
+  this._arrayMode = config.rowMode == 'array';
 
   //if the 'row' event is listened for
   //then emit them as they come in
@@ -34,6 +34,13 @@ var NativeQuery = module.exports = function(native) {
 
 util.inherits(NativeQuery, EventEmitter);
 
+// TODO - remove in 7.0
+// this maintains backwards compat so someone could instantiate a query
+// manually: `new Query().then()`...
+NativeQuery._on = NativeQuery.on;
+NativeQuery._once = NativeQuery.once;
+
+
 NativeQuery.prototype.then = function(onSuccess, onFailure) {
   return this.promise().then(onSuccess, onFailure);
 };
@@ -42,15 +49,19 @@ NativeQuery.prototype.catch = function(callback) {
   return this.promise().catch(callback);
 };
 
-NativeQuery.prototype.promise = function() {
+NativeQuery.prototype._getPromise = function() {
   if (this._promise) return this._promise;
   this._promise = new Promise(function(resolve, reject) {
-    this.once('end', resolve);
-    this.once('error', reject);
+    this._once('end', resolve);
+    this._once('error', reject);
   }.bind(this));
   return this._promise;
 };
 
+NativeQuery.prototype.promise = util.deprecate(function() {
+  return this._getPromise();
+}, 'Query.promise() is deprecated - see the upgrade guide at https://node-postgres.com/guides/upgrading');
+
 NativeQuery.prototype.handleError = function(err) {
   var self = this;
   //copy pq error fields into the error object
@@ -71,6 +82,7 @@ NativeQuery.prototype.handleError = function(err) {
 NativeQuery.prototype.submit = function(client) {
   this.state = 'running';
   var self = this;
+  self.native = client.native;
   client.native.arrayMode = this._arrayMode;
 
   var after = function(err, rows) {

lib/query.js

@@ -40,23 +40,33 @@ var Query = function(config, values, callback) {
 
 util.inherits(Query, EventEmitter);
 
+// TODO - remove in 7.0
+// this maintains backwards compat so someone could instantiate a query
+// manually: `new Query().then()`...
+Query._on = Query.on;
+Query._once = Query.once;
+
 Query.prototype.then = function(onSuccess, onFailure) {
-  return this.promise().then(onSuccess, onFailure);
+  return this._getPromise().then(onSuccess, onFailure);
 };
 
 Query.prototype.catch = function(callback) {
-  return this.promise().catch(callback);
+  return this._getPromise().catch(callback);
 };
 
-Query.prototype.promise = function() {
+Query.prototype._getPromise = function () {
   if (this._promise) return this._promise;
   this._promise = new Promise(function(resolve, reject) {
-    this.once('end', resolve);
-    this.once('error', reject);
+    this._once('end', resolve);
+    this._once('error', reject);
   }.bind(this));
   return this._promise;
 };
 
+Query.prototype.promise = util.deprecate(function() {
+  return this._getPromise();
+}, 'Query.promise() is deprecated - see the upgrade guide at https://node-postgres.com/guides/upgrading');
+
 Query.prototype.requiresPreparation = function() {
   //named queries must always be prepared
   if(this.name) { return true; }

lib/utils.js

@@ -6,6 +6,8 @@
  * README.md file in the root directory of this source tree.
  */
 
+var util = require('util');
+
 var defaults = require('./defaults');
 
 function escapeElement(elementRepresentation) {
@@ -137,11 +139,26 @@ function normalizeQueryConfig (config, values, callback) {
   return config;
 }
 
+var queryEventEmitterOverloadDeprecationMessage = 'Using the automatically created return value from client.query as an event emitter is deprecated. Please see the upgrade guide at https://node-postgres.com/guides/upgrading';
+
+var deprecateEventEmitter = function(Emitter) {
+  var Result = function () {
+    Emitter.apply(this, arguments);
+  };
+  util.inherits(Result, Emitter);
+  Result.prototype._on = Result.prototype.on;
+  Result.prototype._once = Result.prototype.once;
+  Result.prototype.on = util.deprecate(Result.prototype.on, queryEventEmitterOverloadDeprecationMessage);
+  Result.prototype.once = util.deprecate(Result.prototype.once, queryEventEmitterOverloadDeprecationMessage);
+  return Result;
+};
+
 module.exports = {
   prepareValue: function prepareValueWrapper (value) {
     //this ensures that extra arguments do not get passed into prepareValue
     //by accident, eg: from calling values.map(utils.prepareValue)
     return prepareValue(value);
   },
-  normalizeQueryConfig: normalizeQueryConfig
+  normalizeQueryConfig: normalizeQueryConfig,
+  deprecateEventEmitter: deprecateEventEmitter,
 };

test/test-helper.js

@@ -1,6 +1,8 @@
 //make assert a global...
 assert = require('assert');
 
+process.noDeprecation = true
+
 //support for node@0.10.x
 if (typeof Promise == 'undefined') {
   global.Promise = require('promise-polyfill')