postgrejs 3.7.0 → 3.9.0

package/util/date-style.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The session's `DateStyle`, when it is not the ISO default.
+ *
+ * PostgreSQL renders a date four ways, and the client cannot tell which
+ * one it is looking at from the string alone - `05.03.2024` is the fifth
+ * of March in every style that prints it, but `05/03/2024` is the fifth
+ * of March under `SQL, DMY` and the third of May under `SQL, MDY`. The
+ * server reports `DateStyle` in its startup parameters and again on
+ * every `SET`, so the convention is known rather than guessed.
+ *
+ * Measured against PostgreSQL 18.4, one value in every combination:
+ *
+ * ```
+ * ISO,      any    2024-11-25 01:02:03.456        2024-03-05
+ * SQL,      MDY    11/25/2024 01:02:03.456 UTC    03/05/2024
+ * SQL,      DMY    25/11/2024 01:02:03.456 UTC    05/03/2024
+ * Postgres, MDY    Mon Nov 25 01:02:03.456 2024   03-05-2024
+ * Postgres, DMY    Mon 25 Nov 01:02:03.456 2024   05-03-2024
+ * German,   any    25.11.2024 01:02:03.456 UTC    05.03.2024
+ * ```
+ *
+ * Two things in that table are not what the setting's name suggests:
+ * German ignores the field order entirely, and `YMD` prints as `MDY`
+ * for every style. Both are read off the measurement rather than off
+ * the documentation.
+ */
+export interface PgDateStyle {
+    style: 'SQL' | 'Postgres' | 'German';
+    /** Whether the numeric day comes before the month. */
+    dayFirst: boolean;
+}
+/**
+ * The `DateStyle` the server reported, or undefined for ISO - which is
+ * the default, is what every existing parser here expects, and is the
+ * one shape that needs no extra work.
+ */
+export declare function parseDateStyleSetting(value: string | undefined): PgDateStyle | undefined;
+/**
+ * Reads a date or timestamp the server rendered in `style`.
+ *
+ * Returns undefined when the string is not that style's shape - a `BC`
+ * year, an `infinity`, or a zone abbreviation nobody can resolve - so
+ * the caller decides what to do with it. What it must never do is guess:
+ * handing `05.03.2024` to `new Date()` is how the fifth of March became
+ * the third of May, silently, for every day of the month up to twelve.
+ */
+export declare function parseStyledDateTime(str: string, style: PgDateStyle, utc?: boolean): Date | undefined;

package/util/date-style.js

@@ -0,0 +1,123 @@
+const MONTHS = {
+    jan: 0,
+    feb: 1,
+    mar: 2,
+    apr: 3,
+    may: 4,
+    jun: 5,
+    jul: 6,
+    aug: 7,
+    sep: 8,
+    oct: 9,
+    nov: 10,
+    dec: 11,
+};
+/**
+ * `Postgres` style: a weekday, then the month and day in the configured
+ * order, the time, the year, and for timestamptz a zone.
+ */
+const POSTGRES_PATTERN = /^[A-Za-z]{3} (?:([A-Za-z]{3}) (\d{1,2})|(\d{1,2}) ([A-Za-z]{3})) (\d{2}):(\d{2}):(\d{2})(?:\.(\d+))? (\d{1,6})(?: (.+))?$/;
+/** `SQL` and `German`: three numbers, a time, and for timestamptz a zone. */
+const NUMERIC_PATTERN = /^(\d{1,2})([./])(\d{1,2})\2(\d{1,6})(?: (\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?)?(?: (.+))?$/;
+/** `Postgres` style writes a date on its own with dashes. */
+const POSTGRES_DATE_PATTERN = /^(\d{1,2})-(\d{1,2})-(\d{1,6})$/;
+/**
+ * The `DateStyle` the server reported, or undefined for ISO - which is
+ * the default, is what every existing parser here expects, and is the
+ * one shape that needs no extra work.
+ */
+export function parseDateStyleSetting(value) {
+    if (!value)
+        return undefined;
+    const comma = value.indexOf(',');
+    const style = (comma < 0 ? value : value.substring(0, comma)).trim();
+    if (style === 'ISO')
+        return undefined;
+    if (style !== 'SQL' && style !== 'Postgres' && style !== 'German')
+        return undefined;
+    const order = comma < 0 ? '' : value.substring(comma + 1).trim();
+    // German prints day-first whatever the order says, and YMD prints as
+    // MDY - both measured, neither obvious.
+    return { style, dayFirst: style === 'German' || order === 'DMY' };
+}
+/**
+ * The offset a rendered zone stands for, in minutes, or undefined when
+ * it cannot be known.
+ *
+ * Outside ISO the server writes the zone's *abbreviation* where it has
+ * one - `EST`, `IST` - and those do not identify an offset: IST is India
+ * at +05:30, Israel at +02:00 and Ireland at +01:00. A numeric offset
+ * and UTC/GMT are exact, and anything else is refused rather than
+ * guessed at.
+ */
+function zoneOffsetMinutes(zone) {
+    if (zone === 'UTC' || zone === 'GMT' || zone === 'Z')
+        return 0;
+    const m = /^([+-])(\d{1,2})(?::?(\d{2}))?$/.exec(zone);
+    if (!m)
+        return undefined;
+    const sign = m[1] === '-' ? -1 : 1;
+    return sign * (+m[2] * 60 + (m[3] ? +m[3] : 0));
+}
+function build(y, mon, d, h, mi, s, ms, offsetMinutes, utc) {
+    if (offsetMinutes !== undefined)
+        return new Date(Date.UTC(y, mon, d, h, mi - offsetMinutes, s, ms));
+    if (utc)
+        return new Date(Date.UTC(y, mon, d, h, mi, s, ms));
+    return new Date(y, mon, d, h, mi, s, ms);
+}
+function fraction(f) {
+    return f ? +(f + '000').slice(0, 3) : 0;
+}
+/**
+ * Reads a date or timestamp the server rendered in `style`.
+ *
+ * Returns undefined when the string is not that style's shape - a `BC`
+ * year, an `infinity`, or a zone abbreviation nobody can resolve - so
+ * the caller decides what to do with it. What it must never do is guess:
+ * handing `05.03.2024` to `new Date()` is how the fifth of March became
+ * the third of May, silently, for every day of the month up to twelve.
+ */
+export function parseStyledDateTime(str, style, utc) {
+    // Every style writes it the same way, and it is not a date.
+    if (str.endsWith(' BC'))
+        return undefined;
+    if (style.style === 'Postgres') {
+        const m = POSTGRES_PATTERN.exec(str);
+        if (m) {
+            const mon = MONTHS[(m[1] || m[4]).toLowerCase()];
+            if (mon === undefined)
+                return undefined;
+            const day = +(m[2] || m[3]);
+            let offset;
+            if (m[10]) {
+                offset = zoneOffsetMinutes(m[10]);
+                if (offset === undefined)
+                    return undefined;
+            }
+            return build(+m[9], mon, day, +m[5], +m[6], +m[7], fraction(m[8]), offset, utc);
+        }
+        const d = POSTGRES_DATE_PATTERN.exec(str);
+        if (!d)
+            return undefined;
+        const day = +(style.dayFirst ? d[1] : d[2]);
+        const mon = +(style.dayFirst ? d[2] : d[1]) - 1;
+        return build(+d[3], mon, day, 0, 0, 0, 0, undefined, utc);
+    }
+    const m = NUMERIC_PATTERN.exec(str);
+    if (!m)
+        return undefined;
+    // German writes dots and SQL writes slashes; a string using the other
+    // one is not this session's rendering and is not read as if it were.
+    if (m[2] !== (style.style === 'German' ? '.' : '/'))
+        return undefined;
+    const day = +(style.dayFirst ? m[1] : m[3]);
+    const mon = +(style.dayFirst ? m[3] : m[1]) - 1;
+    let offset;
+    if (m[9]) {
+        offset = zoneOffsetMinutes(m[9]);
+        if (offset === undefined)
+            return undefined;
+    }
+    return build(+m[4], mon, day, m[5] ? +m[5] : 0, m[6] ? +m[6] : 0, m[7] ? +m[7] : 0, fraction(m[8]), offset, utc);
+}

package/util/decode-binaryarray.js

@@ -38,7 +38,14 @@ export function decodeBinaryArray(buf, offset, decoder, options = {}) {
     };
     for (let d = 0; d < ndims; d++) {
         dims[d] = io.readInt32BE();
-        io.readInt32BE(); // LBound
+        // The lower bound is read and dropped, deliberately. A server-side
+        // array really can have a non-default one, and a JavaScript array is
+        // always 0-based, so carrying it would mean deciding what a decoded
+        // array is supposed to represent - a wider change than the encoder's.
+        // Note that this is also what hid the encoder writing 0: a value
+        // written and read back through this client looked right, and only
+        // SQL against the stored value saw the difference.
+        io.readInt32BE();
     }
     return readDim(0);
 }

package/util/encode-binaryarray.d.ts

@@ -1,4 +1,15 @@
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { SmartBuffer } from '../protocol/smart-buffer.js';
 import type { EncodeBinaryFunction, EncodeCalculateDimFunction, OID } from '../types.js';
-export declare function encodeBinaryArray(io: SmartBuffer, value: any[], itemOid: OID, options: DataMappingOptions, encode: EncodeBinaryFunction, encodeCalculateDimFn?: EncodeCalculateDimFunction): void;
+/**
+ * Writes an array in the binary wire format.
+ *
+ * `lowerBound` is the index the first element answers to in SQL, and it
+ * is 1 for every ordinary array - `array_lower('{1,2}'::int4[], 1)` is
+ * 1, and a value written with 0 comes back subscripted from 0, so
+ * `arr[1]` is its *second* element and `::text` renders the
+ * explicit-bounds form `[0:2]={…}`. `oidvector` and `int2vector` are the
+ * exception and really are 0-based - confirmed against the catalog,
+ * `array_lower(pg_index.indkey, 1)` is 0 - so they pass 0 themselves.
+ */
+export declare function encodeBinaryArray(io: SmartBuffer, value: any[], itemOid: OID, options: DataMappingOptions, encode: EncodeBinaryFunction, encodeCalculateDimFn?: EncodeCalculateDimFunction, lowerBound?: number): void;

package/util/encode-binaryarray.js

@@ -1,6 +1,17 @@
 import { DataTypeOIDs } from '../constants.js';
 import { arrayCalculateDim } from './array-calculatedim.js';
-export function encodeBinaryArray(io, value, itemOid, options, encode, encodeCalculateDimFn) {
+/**
+ * Writes an array in the binary wire format.
+ *
+ * `lowerBound` is the index the first element answers to in SQL, and it
+ * is 1 for every ordinary array - `array_lower('{1,2}'::int4[], 1)` is
+ * 1, and a value written with 0 comes back subscripted from 0, so
+ * `arr[1]` is its *second* element and `::text` renders the
+ * explicit-bounds form `[0:2]={…}`. `oidvector` and `int2vector` are the
+ * exception and really are 0-based - confirmed against the catalog,
+ * `array_lower(pg_index.indkey, 1)` is 0 - so they pass 0 themselves.
+ */
+export function encodeBinaryArray(io, value, itemOid, options, encode, encodeCalculateDimFn, lowerBound = 1) {
     encodeCalculateDimFn = encodeCalculateDimFn || arrayCalculateDim;
     itemOid = itemOid || DataTypeOIDs.varchar;
     const dim = encodeCalculateDimFn(value);
@@ -12,7 +23,7 @@ export function encodeBinaryArray(io, value, itemOid, options, encode, encodeCal
     let d;
     for (d = 0; d < ndims; d++) {
         io.writeInt32BE(dim[d]); // Number of items in dimension
-        io.writeInt32BE(0); // LBound always 0.
+        io.writeInt32BE(lowerBound); // Index the first element answers to
     }
     let hasNull = false;
     let pos;

package/util/format-datetime.d.ts

@@ -8,3 +8,21 @@ export declare function formatTimestamp(v: Date | number | string, options?: Dat
  * ignores `utcDates`, which only governs the zone-less types.
  */
 export declare function formatTimestamptz(v: Date | number | string): string;
+/**
+ * A `Date` as a parameter, rendered the way `pg` renders one: the wall
+ * clock in the process's own zone, followed by that zone's offset.
+ *
+ * It is the only rendering that is right for both column kinds at once,
+ * which is why the parameter path uses it instead of declaring a type.
+ * A `timestamptz` column honours the offset and stores the instant; a
+ * `timestamp` column discards it and keeps the wall clock - so the
+ * server decides, from the column, what one JavaScript `Date` could
+ * never say on its own. Declaring `timestamp` instead moved the instant
+ * by the client's offset, and declaring `timestamptz` moved the wall
+ * clock by it; measured against `pg` in three session zones, this
+ * matches in all six.
+ *
+ * Under `utcDates` the UTC components go out with a zero offset, which
+ * is the same rule the zone-less encoders follow.
+ */
+export declare function formatDateParam(v: Date | number | string, options?: DataMappingOptions): string;

package/util/format-datetime.js

@@ -69,3 +69,36 @@ export function formatTimestamptz(v) {
         return d;
     return d.toISOString().replace('T', ' ').replace('Z', '+00');
 }
+/**
+ * A `Date` as a parameter, rendered the way `pg` renders one: the wall
+ * clock in the process's own zone, followed by that zone's offset.
+ *
+ * It is the only rendering that is right for both column kinds at once,
+ * which is why the parameter path uses it instead of declaring a type.
+ * A `timestamptz` column honours the offset and stores the instant; a
+ * `timestamp` column discards it and keeps the wall clock - so the
+ * server decides, from the column, what one JavaScript `Date` could
+ * never say on its own. Declaring `timestamp` instead moved the instant
+ * by the client's offset, and declaring `timestamptz` moved the wall
+ * clock by it; measured against `pg` in three session zones, this
+ * matches in all six.
+ *
+ * Under `utcDates` the UTC components go out with a zero offset, which
+ * is the same rule the zone-less encoders follow.
+ */
+export function formatDateParam(v, options) {
+    const d = coerce(v);
+    if (typeof d === 'string')
+        return d;
+    const p = parts(d, options);
+    const clock = `${pad(p.year, 4)}-${pad(p.month)}-${pad(p.day)}` +
+        ` ${pad(p.hour)}:${pad(p.minute)}:${pad(p.second)}.${pad(p.ms, 3)}`;
+    if (options?.utcDates)
+        return clock + '+00:00';
+    // getTimezoneOffset() counts minutes west of UTC, the opposite way
+    // round from how an offset is written.
+    const offset = -d.getTimezoneOffset();
+    const sign = offset < 0 ? '-' : '+';
+    const abs = Math.abs(offset);
+    return `${clock}${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+}

package/util/parse-datetime.d.ts

@@ -1,3 +1,4 @@
-export declare function parseDate(str: string, utc?: boolean): Date | number;
-export declare function parseDateTime(str: string, utc?: boolean): Date | number;
-export declare function parseDateTimeTz(str: string, utc?: boolean): Date | number;
+import { type PgDateStyle } from './date-style.js';
+export declare function parseDate(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;
+export declare function parseDateTime(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;
+export declare function parseDateTimeTz(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;

package/util/parse-datetime.js

@@ -1,4 +1,5 @@
 // noinspection RegExpUnnecessaryNonCapturingGroup
+import { parseStyledDateTime } from './date-style.js';
 import { fastParseInt } from './fast-parseint.js';
 import { parsePgTimestampString } from './parse-pg-timestamp.js';
 // noinspection RegExpUnnecessaryNonCapturingGroup
@@ -21,7 +22,12 @@ function fillTimeArgs(m, args) {
         }
     }
 }
-export function parseDate(str, utc) {
+export function parseDate(str, utc, dateStyle) {
+    if (dateStyle) {
+        const styled = parseStyledDateTime(str, dateStyle, utc);
+        if (styled)
+            return styled;
+    }
     const m = str.match(TIMESTAMP_PATTERN);
     if (!m)
         return noMatch(str);
@@ -40,7 +46,12 @@ export function parseDate(str, utc) {
         return new Date(Date.UTC(...args));
     return new Date(...args);
 }
-export function parseDateTime(str, utc) {
+export function parseDateTime(str, utc, dateStyle) {
+    if (dateStyle) {
+        const styled = parseStyledDateTime(str, dateStyle, utc);
+        if (styled)
+            return styled;
+    }
     if (!utc) {
         if (str === 'infinity')
             return Infinity;
@@ -49,9 +60,14 @@ export function parseDateTime(str, utc) {
         const fast = parsePgTimestampString(str);
         if (fast)
             return fast;
-        const d = new Date(str);
-        if (!isNaN(d.getTime()))
-            return d;
+        // Only reached under the ISO DateStyle: `new Date()` reads
+        // `05.03.2024` as the third of May, and a session that renders dates
+        // that way has said so above.
+        if (!dateStyle) {
+            const d = new Date(str);
+            if (!isNaN(d.getTime()))
+                return d;
+        }
     }
     const m = str.match(TIMESTAMP_PATTERN);
     if (!m)
@@ -72,7 +88,12 @@ export function parseDateTime(str, utc) {
         return new Date(Date.UTC(...args));
     return new Date(...args);
 }
-export function parseDateTimeTz(str, utc) {
+export function parseDateTimeTz(str, utc, dateStyle) {
+    if (dateStyle) {
+        const styled = parseStyledDateTime(str, dateStyle, utc);
+        if (styled)
+            return styled;
+    }
     if (str === 'infinity')
         return Infinity;
     if (str === '-infinity')
@@ -80,9 +101,13 @@ export function parseDateTimeTz(str, utc) {
     const fast = parsePgTimestampString(str);
     if (fast)
         return fast;
-    const native = new Date(str);
-    if (!isNaN(native.getTime()))
-        return native;
+    // See parseDateTime(): the engine's guess is only trusted where the
+    // session renders ISO.
+    if (!dateStyle) {
+        const native = new Date(str);
+        if (!isNaN(native.getTime()))
+            return native;
+    }
     const m = str.match(TIMESTAMP_PATTERN);
     if (!m)
         return noMatch(str);

package/util/resolve-column-formats.js

@@ -42,6 +42,10 @@ export function resolveColumnFormats(fields, options, typeMap) {
     const named = !!asString && asString.length > 0;
     if (!fields || (!named && !unknownAsString))
         return base;
+    // Both options do one thing: ask for a column as text. A row that is
+    // already all text has nothing left for them to ask.
+    if (base === DataFormat.text)
+        return base;
     const l = fields.length;
     const baseIsArray = Array.isArray(base);
     const out = new Array(l);

package/util/row-decoder.d.ts

@@ -17,12 +17,28 @@ import type { AnyParseFunction } from '../types.js';
  * every other row's bytes in it) alive until released.
  */
 export declare abstract class RowDecoder {
+    /**
+     * What `QueryResult.rowType`/`Cursor.rowType` reports for rows this
+     * decoder produced - a promise to the caller about their shape, so it
+     * is the decoder's to make. `'custom'` here is the honest answer for
+     * a decoder nobody else knows anything about; the two built-ins name
+     * their own shape, and a subclass of one that still produces that
+     * shape inherits the right answer without doing anything.
+     *
+     * Set it when a subclass changes the shape - a decoder that hands
+     * back a lazy view rather than a plain array is not an `'array'`, and
+     * a caller that indexes it because the result said so would be
+     * reading the wrong thing.
+     */
+    readonly rowType: 'array' | 'object' | 'custom';
     abstract decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): any;
 }
 export declare class ArrayRowDecoder extends RowDecoder {
+    readonly rowType: "array";
     decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions): any[];
 }
 export declare class ObjectRowDecoder extends RowDecoder {
+    readonly rowType: "object";
     decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): object;
 }
 export declare const DEFAULT_ARRAY_ROW_DECODER: ArrayRowDecoder;
@@ -40,10 +56,14 @@ interface RowDecoderOptions {
  */
 export declare function resolveRowDecoder(options: RowDecoderOptions): RowDecoder;
 /**
- * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`. `'custom'`
- * when the caller supplied their own RowDecoder subclass - there's no way to
- * know what shape it returns - otherwise the same `'array' | 'object'` this
- * option has always reported.
+ * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`.
+ *
+ * Asked of the decoder rather than worked out from its class: an
+ * `instanceof` test answers `'array'` for anything derived from
+ * `ArrayRowDecoder`, including a subclass that overrode `decode()` to
+ * return something else entirely - which is the only reason to subclass
+ * it. The built-ins declare their own shape, so the answers are
+ * unchanged, and a subclass that changes the shape can now say so.
  */
 export declare function resolveRowType(options: RowDecoderOptions): 'array' | 'object' | 'custom';
 export {};

package/util/row-decoder.js

@@ -15,13 +15,29 @@ import { parseObjectRow, parseRow } from './parse-row.js';
  * every other row's bytes in it) alive until released.
  */
 export class RowDecoder {
+    /**
+     * What `QueryResult.rowType`/`Cursor.rowType` reports for rows this
+     * decoder produced - a promise to the caller about their shape, so it
+     * is the decoder's to make. `'custom'` here is the honest answer for
+     * a decoder nobody else knows anything about; the two built-ins name
+     * their own shape, and a subclass of one that still produces that
+     * shape inherits the right answer without doing anything.
+     *
+     * Set it when a subclass changes the shape - a decoder that hands
+     * back a lazy view rather than a plain array is not an `'array'`, and
+     * a caller that indexes it because the result said so would be
+     * reading the wrong thing.
+     */
+    rowType = 'custom';
 }
 export class ArrayRowDecoder extends RowDecoder {
+    rowType = 'array';
     decode(parsers, data, columnCount, options) {
         return parseRow(parsers, data, columnCount, options);
     }
 }
 export class ObjectRowDecoder extends RowDecoder {
+    rowType = 'object';
     decode(parsers, data, columnCount, options, fields) {
         return parseObjectRow(parsers, data, columnCount, options, fields);
     }
@@ -48,16 +64,15 @@ export function resolveRowDecoder(options) {
         : DEFAULT_ARRAY_ROW_DECODER;
 }
 /**
- * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`. `'custom'`
- * when the caller supplied their own RowDecoder subclass - there's no way to
- * know what shape it returns - otherwise the same `'array' | 'object'` this
- * option has always reported.
+ * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`.
+ *
+ * Asked of the decoder rather than worked out from its class: an
+ * `instanceof` test answers `'array'` for anything derived from
+ * `ArrayRowDecoder`, including a subclass that overrode `decode()` to
+ * return something else entirely - which is the only reason to subclass
+ * it. The built-ins declare their own shape, so the answers are
+ * unchanged, and a subclass that changes the shape can now say so.
  */
 export function resolveRowType(options) {
-    const decoder = resolveRowDecoder(options);
-    if (decoder instanceof ObjectRowDecoder)
-        return 'object';
-    if (decoder instanceof ArrayRowDecoder)
-        return 'array';
-    return 'custom';
+    return resolveRowDecoder(options).rowType;
 }

package/util/sql-tag.js

@@ -1,7 +1,11 @@
 import { BindParam } from '../connection/bind-param.js';
 import { DataTypeMap, GlobalTypeMap } from '../data-type-map.js';
+import { arrayLeaf } from './array-leaf.js';
 import { escapeIdentifier } from './escape-identifier.js';
 import { escapeLiteral } from './escape-literal.js';
+import { formatDateParam } from './format-datetime.js';
+import { stringifyArrayLiteral } from './stringify-arrayliteral.js';
+import { isUnspecifiedParam } from './unspecified-param.js';
 /**
  * A statement built by the `sql` tag: its text with the values pulled out.
  *
@@ -171,6 +175,18 @@ function encodeLiteral(value, typeMap, options) {
     }
     if (v == null)
         return 'null';
+    // A Date and a string go in bare, exactly as they go out as
+    // parameters with no declared type (see unspecified-param.ts): an
+    // unadorned literal is `unknown` and takes the type of wherever it
+    // lands. The cast this path adds everywhere else is what keeps
+    // query() and execute() meaning the same thing, and for these two it
+    // is what would break that - `'{"a":1}'::varchar` is refused by a
+    // json column that takes the parameter without complaint.
+    if (oid == null && isUnspecifiedParam(v)) {
+        if (!Array.isArray(v))
+            return escapeLiteral(v instanceof Date ? formatDateParam(v, options) : '' + v);
+        return escapeLiteral(stringifyArrayLiteral(v, options, arrayLeaf(v) instanceof Date ? formatDateParam : undefined));
+    }
     oid = oid ?? typeMap.determine(v);
     /* c8 ignore start - typeMap.determine() always falls back to the
        "unknown" oid rather than returning null/undefined, so this can't

package/util/stringify-for-sql.js

@@ -2,6 +2,7 @@ import { DataTypeOIDs } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { UuidType } from '../data-types/uuid-type.js';
 import { escapeLiteral } from './escape-literal.js';
+import { formatDateParam } from './format-datetime.js';
 export function stringifyArrayForSQL(v, options, encode) {
     const arr = v.map(x => stringifyValueForSQL(x, options, encode));
     return 'ARRAY[' + arr.join(',') + ']';
@@ -51,6 +52,12 @@ export function stringifyValueForSQL(v, options, encode) {
         return v.toString();
     if (typeof v === 'string' && UuidType.isType(v))
         return escapeLiteral('' + v) + '::uuid';
+    // A Date is written bare, with its offset and no cast, so that it
+    // means the same inlined as it does bound - the server resolves it
+    // from the column either way. See format-datetime.ts's
+    // formatDateParam().
+    if (v instanceof Date)
+        return escapeLiteral(formatDateParam(v, options));
     if (typeof v === 'object')
         return stringifyObjectForSQL(v, options);
     // A string is deliberately written bare. determine() would answer

package/util/transaction-command.d.ts

@@ -0,0 +1,7 @@
+/** Whether `sql` opens or closes a transaction. */
+export declare function isTransactionCommand(sql: string): boolean;
+/**
+ * Whether `sql` must not run inside a savepoint - it is a transaction
+ * command, or it configures the transaction.
+ */
+export declare function refusesSavepoint(sql: string): boolean;

package/util/transaction-command.js

@@ -0,0 +1,32 @@
+/**
+ * Statements that open or close a transaction, and so manage their own
+ * boundaries: an implicit BEGIN or COMMIT around one would be wrong, and
+ * wrapping one in a savepoint - COMMIT, say - is nonsense.
+ */
+const TRANSACTION_COMMAND_PATTERN = /^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i;
+/**
+ * `SET TRANSACTION`, which configures the transaction it runs in rather
+ * than opening or closing one.
+ *
+ * It needs an answer of its own because the two are not the same
+ * question. PostgreSQL refuses two of its forms inside a subtransaction
+ * - `SET TRANSACTION ISOLATION LEVEL` and `SET TRANSACTION [NOT]
+ * DEFERRABLE`, both 25001 - so the savepoint `rollbackOnError` puts
+ * around every statement in a transaction made them impossible to run
+ * at all. But the implicit BEGIN that `autoCommit: false` adds is
+ * exactly what they need, so answering "transaction command" for them
+ * and suppressing both would trade one failure for another.
+ */
+const CONFIGURES_TRANSACTION_PATTERN = /^\bSET\s+TRANSACTION\b/i;
+/** Whether `sql` opens or closes a transaction. */
+export function isTransactionCommand(sql) {
+    return TRANSACTION_COMMAND_PATTERN.test(sql);
+}
+/**
+ * Whether `sql` must not run inside a savepoint - it is a transaction
+ * command, or it configures the transaction.
+ */
+export function refusesSavepoint(sql) {
+    return (TRANSACTION_COMMAND_PATTERN.test(sql) ||
+        CONFIGURES_TRANSACTION_PATTERN.test(sql));
+}

package/util/unspecified-param.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether a parameter goes out with no declared type (OID 0), as text,
+ * for the server to resolve from wherever it lands.
+ *
+ * Two kinds of value cannot say what they are:
+ *
+ * - A `Date` is an instant or a wall clock depending on the column, and
+ *   declaring either one moves the other. See `format-datetime.ts`.
+ * - A string is whichever of PostgreSQL's text-input types the context
+ *   calls for. `determine()` answers `varchar`, and declaring that stops
+ *   the server inferring: `insert into t(j) values($1)` into a `json`
+ *   column, `id = $1` against a `uuid`, `coalesce($1, 1)` and an enum
+ *   column all fail with "expression is of type character varying".
+ *   Unspecified, every one of them works.
+ *
+ * This is what `pg` sends for both, and the divergence from it is what
+ * the shapes above were failing on. It is not free: a parameter with no
+ * context to be resolved from - `$1 is null`, `array_agg($1)`,
+ * `concat($1, 1)` - now raises "could not determine data type", exactly
+ * as it does under `pg`. A cast (`$1::text`) or a named type
+ * (`new BindParam(DataTypeOIDs.varchar, v)`) says which type is meant.
+ *
+ * Numbers, booleans and Buffers keep their declared types: they are
+ * already right nearly everywhere, and sending them as text would give
+ * up the binary encoding for no correctness gain.
+ */
+export declare function isUnspecifiedParam(v: any): boolean;

package/util/unspecified-param.js

@@ -0,0 +1,31 @@
+import { arrayLeaf } from './array-leaf.js';
+/**
+ * Whether a parameter goes out with no declared type (OID 0), as text,
+ * for the server to resolve from wherever it lands.
+ *
+ * Two kinds of value cannot say what they are:
+ *
+ * - A `Date` is an instant or a wall clock depending on the column, and
+ *   declaring either one moves the other. See `format-datetime.ts`.
+ * - A string is whichever of PostgreSQL's text-input types the context
+ *   calls for. `determine()` answers `varchar`, and declaring that stops
+ *   the server inferring: `insert into t(j) values($1)` into a `json`
+ *   column, `id = $1` against a `uuid`, `coalesce($1, 1)` and an enum
+ *   column all fail with "expression is of type character varying".
+ *   Unspecified, every one of them works.
+ *
+ * This is what `pg` sends for both, and the divergence from it is what
+ * the shapes above were failing on. It is not free: a parameter with no
+ * context to be resolved from - `$1 is null`, `array_agg($1)`,
+ * `concat($1, 1)` - now raises "could not determine data type", exactly
+ * as it does under `pg`. A cast (`$1::text`) or a named type
+ * (`new BindParam(DataTypeOIDs.varchar, v)`) says which type is meant.
+ *
+ * Numbers, booleans and Buffers keep their declared types: they are
+ * already right nearly everywhere, and sending them as text would give
+ * up the binary encoding for no correctness gain.
+ */
+export function isUnspecifiedParam(v) {
+    const x = arrayLeaf(v);
+    return typeof x === 'string' || x instanceof Date;
+}