Merge pull request #2030 from brianc/bmc/add-pg-cursor

Add pg cursor

.eslintrc

@@ -1,19 +1,21 @@
 {
-  "plugins": [
-    "node"
-  ],
-  "extends": [
-    "standard",
-    "eslint:recommended",
-    "plugin:node/recommended"
-  ],
+  "plugins": ["node"],
+  "extends": ["standard", "eslint:recommended", "plugin:node/recommended"],
   "parserOptions": {
     "ecmaVersion": 2017
   },
   "env": {
     "node": true,
-    "es6": true
+    "es6": true,
+    "mocha": true
   },
   "rules": {
+    "space-before-function-paren": "off",
+    "node/no-unpublished-require": [
+      "error",
+      {
+        "allowModules": ["pg"]
+      }
+    ]
   }
 }

.travis.yml

@@ -36,11 +36,7 @@ matrix:
       addons:
         postgresql: "9.6"
 
-    # PostgreSQL 9.1 and 9.2 only work on precise
-    - node_js: lts/carbon
-      addons:
-        postgresql: "9.1"
-      dist: precise
+    # PostgreSQL 9.2 only works on precise
     - node_js: lts/carbon
       addons:
         postgresql: "9.2"

package.json

@@ -10,7 +10,8 @@
     "packages/*"
   ],
   "scripts": {
-    "test": "yarn lerna exec --parallel yarn test"
+    "test": "yarn lerna exec --parallel yarn test",
+    "lint": "yarn lerna exec --parallel yarn lint"
   },
   "devDependencies": {
     "lerna": "^3.19.0"

packages/pg-cursor/.gitignore

@@ -0,0 +1 @@
+node_modules

packages/pg-cursor/Makefile

@@ -0,0 +1,15 @@
+.PHONY: test
+test:
+	npm test
+
+.PHONY: patch
+patch: test
+	npm version patch -m "Bump version"
+	git push origin master --tags
+	npm publish
+
+.PHONY: minor
+minor: test
+	npm version minor -m "Bump version"
+	git push origin master --tags
+	npm publish

packages/pg-cursor/README.md

@@ -0,0 +1,37 @@
+node-pg-cursor
+==============
+
+Use a PostgreSQL result cursor from node with an easy to use API.
+
+### install
+
+```sh
+$ npm install pg-cursor
+```
+___note___: this depends on _either_ `npm install pg` or `npm install pg.js`, but you __must__ be using the pure JavaScript client.  This will __not work__ with the native bindings.
+
+### :star: [Documentation](https://node-postgres.com/api/cursor) :star:
+
+### license
+
+The MIT License (MIT)
+
+Copyright (c) 2013 Brian M. Carlson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/pg-cursor/index.js

@@ -0,0 +1,218 @@
+'use strict'
+const Result = require('pg/lib/result.js')
+const prepare = require('pg/lib/utils.js').prepareValue
+const EventEmitter = require('events').EventEmitter
+const util = require('util')
+
+let nextUniqueID = 1 // concept borrowed from org.postgresql.core.v3.QueryExecutorImpl
+
+function Cursor (text, values, config) {
+  EventEmitter.call(this)
+
+  this._conf = config || {}
+  this.text = text
+  this.values = values ? values.map(prepare) : null
+  this.connection = null
+  this._queue = []
+  this.state = 'initialized'
+  this._result = new Result(this._conf.rowMode, this._conf.types)
+  this._cb = null
+  this._rows = null
+  this._portal = null
+  this._ifNoData = this._ifNoData.bind(this)
+  this._rowDescription = this._rowDescription.bind(this)
+}
+
+util.inherits(Cursor, EventEmitter)
+
+Cursor.prototype._ifNoData = function () {
+  this.state = 'idle'
+  this._shiftQueue()
+}
+
+Cursor.prototype._rowDescription = function () {
+  if (this.connection) {
+    this.connection.removeListener('noData', this._ifNoData)
+  }
+}
+
+Cursor.prototype.submit = function (connection) {
+  this.connection = connection
+  this._portal = 'C_' + nextUniqueID++
+
+  const con = connection
+
+  con.parse(
+    {
+      text: this.text
+    },
+    true
+  )
+
+  con.bind(
+    {
+      portal: this._portal,
+      values: this.values
+    },
+    true
+  )
+
+  con.describe(
+    {
+      type: 'P',
+      name: this._portal // AWS Redshift requires a portal name
+    },
+    true
+  )
+
+  con.flush()
+
+  if (this._conf.types) {
+    this._result._getTypeParser = this._conf.types.getTypeParser
+  }
+
+  con.once('noData', this._ifNoData)
+  con.once('rowDescription', this._rowDescription)
+}
+
+Cursor.prototype._shiftQueue = function () {
+  if (this._queue.length) {
+    this._getRows.apply(this, this._queue.shift())
+  }
+}
+
+Cursor.prototype._closePortal = function () {
+  // because we opened a named portal to stream results
+  // we need to close the same named portal.  Leaving a named portal
+  // open can lock tables for modification if inside a transaction.
+  // see https://github.com/brianc/node-pg-cursor/issues/56
+  this.connection.close({ type: 'P', name: this._portal })
+  this.connection.sync()
+}
+
+Cursor.prototype.handleRowDescription = function (msg) {
+  this._result.addFields(msg.fields)
+  this.state = 'idle'
+  this._shiftQueue()
+}
+
+Cursor.prototype.handleDataRow = function (msg) {
+  const row = this._result.parseRow(msg.fields)
+  this.emit('row', row, this._result)
+  this._rows.push(row)
+}
+
+Cursor.prototype._sendRows = function () {
+  this.state = 'idle'
+  setImmediate(() => {
+    const cb = this._cb
+    // remove callback before calling it
+    // because likely a new one will be added
+    // within the call to this callback
+    this._cb = null
+    if (cb) {
+      this._result.rows = this._rows
+      cb(null, this._rows, this._result)
+    }
+    this._rows = []
+  })
+}
+
+Cursor.prototype.handleCommandComplete = function (msg) {
+  this._result.addCommandComplete(msg)
+  this._closePortal()
+}
+
+Cursor.prototype.handlePortalSuspended = function () {
+  this._sendRows()
+}
+
+Cursor.prototype.handleReadyForQuery = function () {
+  this._sendRows()
+  this.state = 'done'
+  this.emit('end', this._result)
+}
+
+Cursor.prototype.handleEmptyQuery = function () {
+  this.connection.sync()
+}
+
+Cursor.prototype.handleError = function (msg) {
+  this.connection.removeListener('noData', this._ifNoData)
+  this.connection.removeListener('rowDescription', this._rowDescription)
+  this.state = 'error'
+  this._error = msg
+  // satisfy any waiting callback
+  if (this._cb) {
+    this._cb(msg)
+  }
+  // dispatch error to all waiting callbacks
+  for (let i = 0; i < this._queue.length; i++) {
+    this._queue.pop()[1](msg)
+  }
+
+  if (this.listenerCount('error') > 0) {
+    // only dispatch error events if we have a listener
+    this.emit('error', msg)
+  }
+  // call sync to keep this connection from hanging
+  this.connection.sync()
+}
+
+Cursor.prototype._getRows = function (rows, cb) {
+  this.state = 'busy'
+  this._cb = cb
+  this._rows = []
+  const msg = {
+    portal: this._portal,
+    rows: rows
+  }
+  this.connection.execute(msg, true)
+  this.connection.flush()
+}
+
+// users really shouldn't be calling 'end' here and terminating a connection to postgres
+// via the low level connection.end api
+Cursor.prototype.end = util.deprecate(function (cb) {
+  if (this.state !== 'initialized') {
+    this.connection.sync()
+  }
+  this.connection.once('end', cb)
+  this.connection.end()
+}, 'Cursor.end is deprecated. Call end on the client itself to end a connection to the database.')
+
+Cursor.prototype.close = function (cb) {
+  if (this.state === 'done') {
+    if (cb) {
+      return setImmediate(cb)
+    } else {
+      return
+    }
+  }
+  this._closePortal()
+  this.state = 'done'
+  if (cb) {
+    this.connection.once('closeComplete', function () {
+      cb()
+    })
+  }
+}
+
+Cursor.prototype.read = function (rows, cb) {
+  if (this.state === 'idle') {
+    return this._getRows(rows, cb)
+  }
+  if (this.state === 'busy' || this.state === 'initialized') {
+    return this._queue.push([rows, cb])
+  }
+  if (this.state === 'error') {
+    return setImmediate(() => cb(this._error))
+  }
+  if (this.state === 'done') {
+    return setImmediate(() => cb(null, []))
+  } else {
+    throw new Error('Unknown state: ' + this.state)
+  }
+}
+
+module.exports = Cursor

packages/pg-cursor/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pg-cursor",
+  "version": "2.0.1",
+  "description": "Query cursor extension for node-postgres",
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "test": "mocha && eslint .",
+    "lint": "eslint ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/brianc/node-pg-cursor.git"
+  },
+  "author": "Brian M. Carlson",
+  "license": "MIT",
+  "devDependencies": {
+    "eslint": "^6.5.1",
+    "eslint-config-prettier": "^6.4.0",
+    "eslint-plugin-prettier": "^3.1.1",
+    "mocha": "^6.2.2",
+    "pg": "7.x",
+    "prettier": "^1.18.2"
+  },
+  "prettier": {
+    "semi": false,
+    "printWidth": 120,
+    "trailingComma": "none",
+    "singleQuote": true
+  }
+}