@steadybrew/postgresjs 4.4.1 → 4.5.0

package/src/connection.js

@@ -4,7 +4,7 @@ import crypto from 'crypto'
 import Stream from 'stream'
 import { performance } from 'perf_hooks'
 
-import { stringify, handleValue, addArrayType } from './types.js'
+import { stringify, handleValue, addArrayType, clientSerialize } from './types.js'
 import { Errors, callback } from './errors.js'
 import Result from './result.js'
 import Queue from './queue.js'
@@ -104,6 +104,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     , hostIndex = 0
     , length = 0
     , rows = 0
+    , copyPaused = false
     , serverSignature = null
     , nextWriteTimer = null
     , incomings = null
@@ -214,7 +215,10 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   const connection = {
     queue: queues.closed,
     idleTimer,
-    connect: request => dispatch('acquire', request),
+    // Sentry's hook wraps connect and reads the connection from this, so it must stay a method
+    connect(request) {
+      dispatch('acquire', request)
+    },
     terminate: () => dispatch('terminate'),
     execute,
     release: () => dispatch('release'),
@@ -459,6 +463,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     query = results = errorResponse = chunk = nextWriteTimer = barrier = null
     result = new Result()
     rows = 0
+    copyPaused = false
     nonce = serverSignature = null
   }
 
@@ -538,7 +543,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
       build(q)
       const written = write(toBuffer(q))
-      if (q.describeFirst || q.cursorFn || mayCopy(q))
+      if (q.describeFirst || q.cursorFn || mayCopy(q) || (q.prepare && !q.prepared && !q.options.simple && q.parameters.length))
         barrier = q
       return written && accepting()
     } catch (error) {
@@ -576,7 +581,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function prepared(q) {
     return Buffer.concat([
-      Bind(q.parameters, q.statement.types, q.statement.name, q.cursorName),
+      Bind(q),
       q.cursorFn
         ? Execute('', q.cursorRows)
         : ExecuteUnnamed
@@ -604,8 +609,11 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     q.signature = q.prepare && types + string
     q.onlyDescribe && (delete statements[q.signature])
     q.parameters = q.parameters || parameters
+    q.inferred = options.parameter_types === 'server' ? null : types.slice()
     q.prepared = q.prepare && q.signature in statements
-    q.describeFirst = q.onlyDescribe || (parameters.length && !q.prepared)
+    q.describeFirst = q.onlyDescribe || (!q.prepared && types.some((x, i) =>
+      !x && (options.parameter_types !== 'client' || Array.isArray(q.parameters[i]))
+    ))
     q.statement = q.prepared
       ? statements[q.signature]
       : { string, types, name: q.prepare ? statementId + statementCount++ : '' }
@@ -678,6 +686,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function errored(err) {
     stream && (stream.destroy(err), stream = null)
+    resumeCopy()
     query && queryError(query, err)
   }
 
@@ -689,7 +698,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
       err = new Error(err)
 
     'query' in err || 'parameters' in err || Object.defineProperties(err, {
-      stack: { value: err.stack + query.origin.replace(/.*\n/, '\n'), enumerable: options.debug },
+      stack: { value: err.stack + query.origin.replace(/.*\n/, '\n'), enumerable: options.debug, writable: true, configurable: true },
       query: { value: query.string, enumerable: options.debug },
       parameters: { value: query.parameters, enumerable: options.debug },
       args: { value: query.args, enumerable: options.debug },
@@ -794,7 +803,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
         query.prepared && retryRoutines.has(errorResponse.routine) && delete statements[query.signature]
         query.retried
           ? errored(query.retried)
-          : query.prepared && retryRoutines.has(errorResponse.routine) && query.owner === connection.owner && !barrier
+          : query.prepared && retryRoutines.has(errorResponse.routine) && query.owner === connection.owner && !barrier && !query.cancelled
             && (x[5] !== 69 || endsAbortedState.test(query.string))
             ? retry(query, errorResponse)
             : errored(errorResponse)
@@ -808,6 +817,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
     query = results = errorResponse = null
     result = new Result()
+    rows = 0
 
     dispatch('ready')
   }
@@ -1040,8 +1050,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function mismatchReason(x, xs) {
     return (
+      (x === 'read-write' && xs.in_hot_standby === 'on' && 'is a standby') ||
       (x === 'read-write' && xs.default_transaction_read_only === 'on' && 'is read-only') ||
-      (x === 'read-only' && xs.default_transaction_read_only === 'off' && 'is read-write') ||
+      (x === 'read-only' && xs.in_hot_standby === 'off' && xs.default_transaction_read_only === 'off' && 'is read-write') ||
       (x === 'primary' && xs.in_hot_standby === 'on' && 'is a standby') ||
       (x === 'standby' && xs.in_hot_standby === 'off' && 'is a primary') ||
       (x === 'prefer-standby' && xs.in_hot_standby === 'off' && standbyPass() && 'is a primary') ||
@@ -1140,7 +1151,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function CopyOutResponse() {
     stream = new Stream.Readable({
-      read() { socket.resume() }
+      read() { copyPaused = false; socket.resume() }
     })
     query.resolve(stream)
     connection.owner && connection.owner.next()
@@ -1150,7 +1161,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   function CopyBothResponse() {
     stream = new Stream.Duplex({
       autoDestroy: true,
-      read() { socket.resume() },
+      read() { copyPaused = false; socket.resume() },
       /* c8 ignore next 11 */
       write(chunk, encoding, callback) {
         socket.write(b().d().raw(chunk).end(), callback)
@@ -1170,12 +1181,23 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   }
 
   function CopyData(x) {
-    stream && (stream.push(x.subarray(5)) || socket.pause())
+    if (stream && !stream.push(x.subarray(5))) {
+      copyPaused = true
+      socket.pause()
+    }
   }
 
   function CopyDone() {
     stream && stream.push(null)
     stream = null
+    resumeCopy()
+  }
+
+  function resumeCopy() {
+    if (copyPaused) {
+      copyPaused = false
+      socket.resume()
+    }
   }
 
   function NoticeResponse(x) {
@@ -1213,20 +1235,21 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   }
 
   /* Messages */
-  function Bind(parameters, types, statement = '', portal = '') {
+  function Bind(q) {
+    const differences = []
     let prev
       , type
 
-    b().B().str(portal + b.N).str(statement + b.N).i16(0).i16(parameters.length)
+    b().B().str((q.cursorName || '') + b.N).str(q.statement.name + b.N).i16(0).i16(q.parameters.length)
 
-    parameters.forEach((x, i) => {
+    q.parameters.forEach((x, i) => {
       if (x === null)
         return b.i32(0xFFFFFFFF)
 
-      type = types[i]
-      x = type in options.serializers
-        ? options.serializers[type](x)
-        : '' + x
+      type = q.statement.types[i]
+      x = !q.inferred || q.inferred[i] || Array.isArray(x)
+        ? serialize(x, type)
+        : options.parameter_types === 'client' ? clientSerialize(x) : compare(x, type, i, differences)
 
       prev = b.i
       b.inc(4).str(x).i32(b.i - prev - 4, prev)
@@ -1234,7 +1257,27 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
     b.i16(0)
 
-    return b.end()
+    const message = b.end()
+    differences.length && callback(options.ontypemismatch || console.warn, { query: q.string, parameters: differences }) // eslint-disable-line
+    return message
+  }
+
+  function serialize(x, type) {
+    return type in options.serializers
+      ? options.serializers[type](x)
+      : '' + x
+  }
+
+  function compare(x, type, i, differences) {
+    const serverText = serialize(x, type)
+    let clientText
+    try {
+      clientText = clientSerialize(x)
+    } catch (error) {
+      clientText = error
+    }
+    serverText === clientText || differences.push({ position: i + 1, oid: type, typeof: typeof x, ...options.debug && { serverText, clientText } })
+    return serverText
   }
 
   function Parse(str, parameters, types, name = '') {

package/src/errors.js

@@ -1,8 +1,8 @@
 export class PostgresError extends Error {
   constructor(x) {
-    super(x.message)
+    super(typeof x === 'string' ? x : x.message)
     this.name = this.constructor.name
-    Object.assign(this, x)
+    typeof x === 'string' || Object.assign(this, x)
   }
 }
 

package/src/index.js

@@ -86,7 +86,8 @@ function Postgres(a, b) {
     listen,
     begin,
     close,
-    end
+    end,
+    ...Symbol.asyncDispose && { [Symbol.asyncDispose]: () => end() }
   })
 
   return sql
@@ -327,10 +328,17 @@ function Postgres(a, b) {
 
   async function reserve() {
     const l = await lease(false)
-    const sql = Sql(q => send(l, q))
+    const sql = Sql(handler)
     sql.release = () => settle(l, Lease.Released)
+    Symbol.dispose && (sql[Symbol.dispose] = () => sql.release())
+    Symbol.asyncDispose && (sql[Symbol.asyncDispose] = async() => sql.release())
     sql.stats = stats
     return sql
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q) {
+      send(l, q)
+    }
   }
 
   async function begin(options, fn) {
@@ -347,7 +355,7 @@ function Postgres(a, b) {
     }
 
     async function transaction() {
-      await Sql(q => send(l, q)).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
+      await Sql(handler).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
         e instanceof PostgresError && settle(l, Lease.Released)
         throw e
       })
@@ -358,7 +366,7 @@ function Postgres(a, b) {
       let result
       l.state = Lease.Settling
       try {
-        result = await statement(Sql(q => send(l, q, Lease.Settling)))
+        result = await statement(Sql(q => handler(q, Lease.Settling)))
       } catch (e) {
         settle(l, Lease.Discarded)
         throw e
@@ -368,7 +376,7 @@ function Postgres(a, b) {
     }
 
     async function scope(fn, name) {
-      const sql = Sql(handler)
+      const sql = Sql(track)
       sql.savepoint = savepoint
       sql.prepare = x => {
         if (typeof x !== 'string' || !x || x.includes('\0'))
@@ -422,11 +430,16 @@ function Postgres(a, b) {
         return scope(fn, 's' + savepoints++ + (name ? '_' + name : ''))
       }
 
-      function handler(q) {
+      function track(q) {
         q.catch(e => uncaughtError || (uncaughtError = e))
-        send(l, q)
+        handler(q)
       }
     }
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q, expected) {
+      send(l, q, expected)
+    }
   }
 
   function move(c, queue) {
@@ -674,6 +687,7 @@ function parseOptions(a, b) {
     prepare         : true,
     debug           : false,
     fetch_types     : true,
+    parameter_types : 'server',
     publications    : 'alltables',
     target_session_attrs: null
   }
@@ -688,8 +702,8 @@ function parseOptions(a, b) {
     ...Object.entries(defaults).reduce(
       (acc, [k, d]) => {
         const value = k in o ? o[k] : k in query
-          ? (query[k] === 'disable' || query[k] === 'false' ? false : query[k])
-          : env['PG' + k.toUpperCase()] || d
+          ? off(query[k])
+          : env['PG' + k.toUpperCase()] ? off(env['PG' + k.toUpperCase()]) : d
         acc[k] = typeof value === 'string' && ints.includes(k)
           ? +value
           : value
@@ -704,11 +718,13 @@ function parseOptions(a, b) {
     },
     types           : o.types || {},
     target_session_attrs: tsa(o, url, env),
+    parameter_types : parameterTypes(o, url, env),
     onnotice        : o.onnotice,
     onnotify        : o.onnotify,
     onclose         : o.onclose,
     onidle          : o.onidle,
     onparameter     : o.onparameter,
+    ontypemismatch  : o.ontypemismatch,
     socket          : o.socket,
     transform       : parseTransform(o.transform || { undefined: undefined }),
     parameters      : {},
@@ -720,6 +736,10 @@ function parseOptions(a, b) {
   return options
 }
 
+function off(x) {
+  return x === 'disable' || x === 'false' ? false : x
+}
+
 function tsa(o, url, env) {
   const x = o.target_session_attrs || url.searchParams.get('target_session_attrs') || env.PGTARGETSESSIONATTRS
   if (!x || ['read-write', 'read-only', 'primary', 'standby', 'prefer-standby'].includes(x))
@@ -728,6 +748,14 @@ function tsa(o, url, env) {
   throw new Error('target_session_attrs ' + x + ' is not supported')
 }
 
+function parameterTypes(o, url, env) {
+  const x = o.parameter_types || url.searchParams.get('parameter_types') || env.PGPARAMETER_TYPES || 'server'
+  if (['server', 'client', 'warn'].includes(x))
+    return x
+
+  throw new Error('parameter_types ' + x + ' is not supported')
+}
+
 function max_lifetime() {
   return 60 * (30 + Math.random() * 30)
 }

package/src/query.js

@@ -23,16 +23,9 @@ export class Query extends Promise {
     this.state = null
     this.statement = null
 
-    this.resolve = x => {
-      this.active = false
-      this.settled = true
-      resolve(x)
-    }
-    this.reject = x => {
-      this.active = false
-      this.settled = true
-      reject(x)
-    }
+    // dd-trace's load-time rewrite only accepts single-expression arrows here
+    this.resolve = x => (this.active = false, this.settled = true, resolve(x))
+    this.reject = x => (this.active = false, this.settled = true, reject(x))
 
     this.active = false
     this.settled = false
@@ -62,6 +55,7 @@ export class Query extends Promise {
     if (!this.canceller || this.settled)
       return Promise.resolve()
 
+    Promise.prototype.then.call(this, undefined, () => undefined)
     const cancelled = this.canceller(this)
     this.canceller = null
     cancelled.catch(() => undefined)

package/src/types.js

@@ -248,6 +248,11 @@ export const inferType = function inferType(x) {
   )
 }
 
+export function clientSerialize(x) {
+  const proto = typeof x === 'object' && Object.getPrototypeOf(x)
+  return proto === Object.prototype || proto === null ? JSON.stringify(x) : '' + x
+}
+
 const escapeBackslash = /\\/g
 const escapeQuote = /"/g
 
@@ -341,14 +346,14 @@ function arrayParserLoop(s, x, parser, typarray) {
 export const toCamel = x => {
   let str = x[0]
   for (let i = 1; i < x.length; i++)
-    str += x[i] === '_' ? x[++i].toUpperCase() : x[i]
+    str += x[i] === '_' && i + 1 < x.length ? x[++i].toUpperCase() : x[i]
   return str
 }
 
 export const toPascal = x => {
   let str = x[0].toUpperCase()
   for (let i = 1; i < x.length; i++)
-    str += x[i] === '_' ? x[++i].toUpperCase() : x[i]
+    str += x[i] === '_' && i + 1 < x.length ? x[++i].toUpperCase() : x[i]
   return str
 }
 

package/types/index.d.ts

@@ -1,4 +1,4 @@
-import { Readable, Writable } from 'node:stream'
+import { Duplex, Readable, Writable } from 'node:stream'
 
 /**
  * Establish a connection to a PostgreSQL server.
@@ -45,6 +45,8 @@ interface BaseOptions<T extends Record<string, postgres.PostgresType>> {
    * @default false
   */
   ssl: 'require' | 'allow' | 'prefer' | 'verify-full' | boolean | object;
+  /** Set to 'direct' to start TLS immediately with ALPN instead of sending an SSLRequest first */
+  sslnegotiation: 'direct' | 'postgres' | null;
   /**
    * Max number of connections
    * @default 10
@@ -110,6 +112,10 @@ interface BaseOptions<T extends Record<string, postgres.PostgresType>> {
    * @default true
    */
   fetch_types: boolean;
+  /** How values whose type cannot be told from the JavaScript value are serialized: 'server' (default) asks PostgreSQL for the placeholder's type first, 'client' sends their text for PostgreSQL to parse, 'warn' does the same as 'server' and reports values 'client' would send differently */
+  parameter_types: 'server' | 'client' | 'warn';
+  /** Called in parameter_types: 'warn' mode with each query whose values would be sent differently, console.warn by default; if it throws, the error is rethrown as an uncaught exception */
+  ontypemismatch: (report: postgres.TypeMismatchReport) => void;
   /**
    * Publications to subscribe to (only relevant when calling `sql.subscribe()`)
    * @default 'alltables'
@@ -122,6 +128,8 @@ interface BaseOptions<T extends Record<string, postgres.PostgresType>> {
   backoff: boolean | ((attemptNum: number) => number);
   max_lifetime: number | null;
   keep_alive: number | null;
+  /** Function, sync or async, returning the socket-like duplex stream to connect through; it receives the parsed options */
+  socket?: (options: postgres.ParsedOptions) => Duplex | Promise<Duplex>;
 }
 
 
@@ -199,6 +207,8 @@ type Return<T, K extends readonly any[]> =
 
 declare namespace postgres {
   class PostgresError extends Error {
+    constructor(message: string);
+    constructor(fields: Partial<Omit<PostgresError, 'name' | 'stack' | 'cause'>>);
     name: 'PostgresError';
     severity_local: string;
     severity: string;
@@ -411,6 +421,23 @@ declare namespace postgres {
     };
   }
 
+  interface TypeMismatchReport {
+    query: string;
+    parameters: TypeMismatch[];
+  }
+
+  interface TypeMismatch {
+    /** The `$n` number of the placeholder */
+    position: number;
+    /** The type OID PostgreSQL inferred for the placeholder */
+    oid: number;
+    typeof: string;
+    /** Only set when debug is enabled */
+    serverText?: string;
+    /** Only set when debug is enabled; the error is what the 'client' mode would throw */
+    clientText?: string | globalThis.Error;
+  }
+
   interface Notice {
     [field: string]: string;
   }
@@ -742,6 +769,9 @@ declare namespace postgres {
 
     end(options?: { timeout?: number | undefined } | undefined): Promise<void>;
 
+    /** Calls `end()` with no timeout when an `await using` scope exits */
+    [Symbol.asyncDispose](): Promise<void>;
+
     listen(channel: string, onnotify: (value: string) => void, onlisten?: (() => void) | undefined): ListenRequest;
 
     /** `onerror` receives replication connection errors and errors thrown while a change is decoded; such a change is skipped. */
@@ -767,6 +797,12 @@ declare namespace postgres {
 
   interface ReservedSql<TTypes extends Record<string, unknown> = {}> extends Sql<TTypes> {
     release(): void;
+
+    /** Calls `release()` when a `using` scope exits */
+    [Symbol.dispose](): void;
+
+    /** Calls `release()` when an `await using` scope exits */
+    [Symbol.asyncDispose](): Promise<void>;
   }
 }
 

package/types/package.json

@@ -1,5 +1,5 @@
 {
   "devDependencies": {
-    "@types/node": "^16"
+    "@types/node": "^22"
   }
 }