Add opt-in query pipelining support

Allow multiple queries to be sent on the wire before waiting for
responses, reducing round-trip latency. Enabled via client.pipelining = true.
Each query gets its own Sync boundary so errors are isolated.

Tracks in-flight named statements (submittedNamedStatements) to prevent
duplicate Parse messages when pipelining queries with the same prepared
statement name. Handles error/disconnect cleanup for the sent queue.

Author: mcollina

packages/pg/lib/client.js

@@ -83,6 +83,8 @@ class Client extends EventEmitter {
         encoding: this.connectionParameters.client_encoding || 'utf8',
       })
     this._queryQueue = []
+    this._sentQueryQueue = []
+    this.pipelining = false
     this.binary = c.binary || defaults.binary
     this.processID = null
     this.secretKey = null
@@ -126,6 +128,9 @@ class Client extends EventEmitter {
       this._activeQuery = null
     }
 
+    this._sentQueryQueue.forEach(enqueueError)
+    this._sentQueryQueue.length = 0
+
     this._queryQueue.forEach(enqueueError)
     this._queryQueue.length = 0
   }
@@ -363,6 +368,10 @@ class Client extends EventEmitter {
     if (activeQuery) {
       activeQuery.handleReadyForQuery(this.connection)
     }
+    if (this.pipelining && this._sentQueryQueue.length > 0) {
+      this._activeQuery = this._sentQueryQueue.shift()
+      this.readyForQuery = false
+    }
     this._pulseQueryQueue()
   }
 
@@ -476,6 +485,7 @@ class Client extends EventEmitter {
     // it again on the same client
     if (activeQuery.name) {
       this.connection.parsedStatements[activeQuery.name] = activeQuery.text
+      delete this.connection.submittedNamedStatements[activeQuery.name]
     }
   }
 
@@ -554,6 +564,8 @@ class Client extends EventEmitter {
       })
     } else if (client._queryQueue.indexOf(query) !== -1) {
       client._queryQueue.splice(client._queryQueue.indexOf(query), 1)
+    } else if (client._sentQueryQueue.indexOf(query) !== -1) {
+      client._sentQueryQueue.splice(client._sentQueryQueue.indexOf(query), 1)
     }
   }
 
@@ -577,6 +589,10 @@ class Client extends EventEmitter {
   }
 
   _pulseQueryQueue() {
+    if (this.pipelining) {
+      this._pulsePipelinedQueryQueue()
+      return
+    }
     if (this.readyForQuery === true) {
       this._activeQuery = this._queryQueue.shift()
       const activeQuery = this._getActiveQuery()
@@ -599,6 +615,31 @@ class Client extends EventEmitter {
     }
   }
 
+  _pulsePipelinedQueryQueue() {
+    if (!this._connected) {
+      return
+    }
+    while (this._queryQueue.length > 0) {
+      const query = this._queryQueue.shift()
+      this.hasExecuted = true
+      const queryError = query.submit(this.connection)
+      if (queryError) {
+        process.nextTick(() => {
+          query.handleError(queryError, this.connection)
+        })
+        continue
+      }
+      this._sentQueryQueue.push(query)
+    }
+    if (!this._activeQuery && this._sentQueryQueue.length > 0) {
+      this._activeQuery = this._sentQueryQueue.shift()
+      this.readyForQuery = false
+    }
+    if (!this._activeQuery && this._sentQueryQueue.length === 0 && this._queryQueue.length === 0 && this.hasExecuted) {
+      this.emit('drain')
+    }
+  }
+
   query(config, values, callback) {
     // can take in strings, config object or query object
     let query
@@ -654,6 +695,11 @@ class Client extends EventEmitter {
         const index = this._queryQueue.indexOf(query)
         if (index > -1) {
           this._queryQueue.splice(index, 1)
+        } else if (this.pipelining) {
+          const sentIndex = this._sentQueryQueue.indexOf(query)
+          if (sentIndex > -1) {
+            this._sentQueryQueue.splice(sentIndex, 1)
+          }
         }
 
         this._pulseQueryQueue()
@@ -687,7 +733,7 @@ class Client extends EventEmitter {
       return result
     }
 
-    if (this._queryQueue.length > 0) {
+    if (this._queryQueue.length > 0 && !this.pipelining) {
       queryQueueLengthDeprecationNotice()
     }
     this._queryQueue.push(query)
@@ -715,7 +761,7 @@ class Client extends EventEmitter {
       }
     }
 
-    if (this._getActiveQuery() || !this._queryable) {
+    if (this._getActiveQuery() || this._sentQueryQueue.length > 0 || !this._queryable) {
       // if we have an active query we need to force a disconnect
       // on the socket - otherwise a hung query could block end forever
       this.connection.stream.destroy()

packages/pg/lib/connection.js

@@ -23,6 +23,7 @@ class Connection extends EventEmitter {
     this._keepAlive = config.keepAlive
     this._keepAliveInitialDelayMillis = config.keepAliveInitialDelayMillis
     this.parsedStatements = {}
+    this.submittedNamedStatements = {}
     this.ssl = config.ssl || false
     this._ending = false
     this._emitMessage = false

packages/pg/lib/query.js

@@ -153,7 +153,7 @@ class Query extends EventEmitter {
     if (typeof this.text !== 'string' && typeof this.name !== 'string') {
       return new Error('A query must have either text or a name. Supplying neither is unsupported.')
     }
-    const previous = connection.parsedStatements[this.name]
+    const previous = connection.parsedStatements[this.name] || connection.submittedNamedStatements[this.name]
     if (this.text && previous && this.text !== previous) {
       return new Error(`Prepared statements must be unique - '${this.name}' was used for a different statement`)
     }
@@ -183,7 +183,7 @@ class Query extends EventEmitter {
   }
 
   hasBeenParsed(connection) {
-    return this.name && connection.parsedStatements[this.name]
+    return this.name && (connection.parsedStatements[this.name] || connection.submittedNamedStatements[this.name])
   }
 
   handlePortalSuspended(connection) {
@@ -214,6 +214,9 @@ class Query extends EventEmitter {
         name: this.name,
         types: this.types,
       })
+      if (this.name) {
+        connection.submittedNamedStatements[this.name] = this.text
+      }
     }
 
     // because we're mapping user supplied values to

packages/pg/test/integration/client/pipelining-tests.js

@@ -0,0 +1,88 @@
+'use strict'
+const helper = require('./test-helper')
+const assert = require('assert')
+const suite = new helper.Suite()
+
+suite.test('basic pipelining with simple queries', async function () {
+  const client = helper.client()
+  client.pipelining = true
+
+  const [r1, r2, r3] = await Promise.all([
+    client.query('SELECT 1 AS num'),
+    client.query('SELECT 2 AS num'),
+    client.query('SELECT 3 AS num'),
+  ])
+
+  assert.equal(r1.rows[0].num, 1)
+  assert.equal(r2.rows[0].num, 2)
+  assert.equal(r3.rows[0].num, 3)
+
+  await client.end()
+})
+
+suite.test('pipelining with parameterized queries', async function () {
+  const client = helper.client()
+  client.pipelining = true
+
+  const [r1, r2, r3] = await Promise.all([
+    client.query('SELECT $1::int AS num', [10]),
+    client.query('SELECT $1::text AS name', ['hello']),
+    client.query('SELECT $1::int + $2::int AS sum', [3, 4]),
+  ])
+
+  assert.equal(r1.rows[0].num, 10)
+  assert.equal(r2.rows[0].name, 'hello')
+  assert.equal(r3.rows[0].sum, 7)
+
+  await client.end()
+})
+
+suite.test('pipelining with named prepared statements', async function () {
+  const client = helper.client()
+  client.pipelining = true
+
+  const [r1, r2] = await Promise.all([
+    client.query({ name: 'fetch-num', text: 'SELECT $1::int AS num', values: [42] }),
+    client.query({ name: 'fetch-num', text: 'SELECT $1::int AS num', values: [99] }),
+  ])
+
+  assert.equal(r1.rows[0].num, 42)
+  assert.equal(r2.rows[0].num, 99)
+
+  await client.end()
+})
+
+suite.test('pipelining error isolation', async function () {
+  const client = helper.client()
+  client.pipelining = true
+
+  const results = await Promise.allSettled([
+    client.query('SELECT 1 AS num'),
+    client.query('SELECT INVALID SYNTAX'),
+    client.query('SELECT 3 AS num'),
+  ])
+
+  assert.equal(results[0].status, 'fulfilled')
+  assert.equal(results[0].value.rows[0].num, 1)
+  assert.equal(results[1].status, 'rejected')
+  assert.equal(results[2].status, 'fulfilled')
+  assert.equal(results[2].value.rows[0].num, 3)
+
+  await client.end()
+})
+
+suite.test('pipelining drain event', async function () {
+  const client = helper.client()
+  client.pipelining = true
+
+  const drainPromise = new Promise((resolve) => {
+    client.on('drain', resolve)
+  })
+
+  client.query('SELECT 1')
+  client.query('SELECT 2')
+  client.query('SELECT 3')
+
+  await drainPromise
+  await client.end()
+})

packages/pg/test/unit/client/simple-query-tests.js

@@ -114,6 +114,66 @@ test('executing query', function () {
     })
   })
 
+  test('pipelining', function () {
+    test('sends all queries immediately after readyForQuery', function () {
+      const client = helper.client()
+      client.pipelining = true
+      client.connection.emit('readyForQuery')
+      client.query('one')
+      client.query('two')
+      client.query('three')
+      assert.lengthIs(client.connection.queries, 3)
+      assert.equal(client.connection.queries[0], 'one')
+      assert.equal(client.connection.queries[1], 'two')
+      assert.equal(client.connection.queries[2], 'three')
+    })
+
+    test('completes queries in order', function (done) {
+      const client = helper.client()
+      client.pipelining = true
+      const con = client.connection
+      con.emit('readyForQuery')
+
+      const results = []
+      client.query('one', (err, res) => {
+        results.push('one')
+      })
+      client.query('two', (err, res) => {
+        results.push('two')
+      })
+      client.query('three', (err, res) => {
+        results.push('three')
+      })
+
+      // simulate server responding to each query in order
+      con.emit('readyForQuery')
+      con.emit('readyForQuery')
+      con.emit('readyForQuery')
+
+      process.nextTick(() => {
+        assert.deepStrictEqual(results, ['one', 'two', 'three'])
+        done()
+      })
+    })
+
+    test('emits drain after all queries complete', function (done) {
+      const client = helper.client()
+      client.pipelining = true
+      const con = client.connection
+      con.emit('readyForQuery')
+
+      client.query('one')
+      client.query('two')
+
+      client.on('drain', () => {
+        done()
+      })
+
+      con.emit('readyForQuery')
+      con.emit('readyForQuery')
+    })
+  })
+
   test('handles errors', function () {
     const client = helper.client()