postgrejs 3.3.0 → 3.5.0

package/connection/intl-connection.d.ts

@@ -1,5 +1,9 @@
 import { ConnectionState } from '../constants.js';
+import type { DataTypeMap } from '../data-type-map.js';
+import type { BatchResult } from '../interfaces/batch-result.js';
+import type { CopyFromRowsOptions, CopyFromRowsResult } from '../interfaces/copy-from-rows-options.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+import type { FieldInfo } from '../interfaces/field-info.js';
 import type { FunctionCallOptions } from '../interfaces/function-call-options.js';
 import type { FunctionCallResult } from '../interfaces/function-call-result.js';
 import type { QueryOptions } from '../interfaces/query-options.js';
@@ -9,10 +13,25 @@ import type { ScriptResult } from '../interfaces/script-result.js';
 import { PgSocket } from '../protocol/pg-socket.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import type { Maybe, OID } from '../types.js';
+import type { AnyParseFunction, Maybe, OID } from '../types.js';
+import { type CopyRowSource } from '../util/copy-from-rows.js';
 import type { Connection } from './connection.js';
 import { CopyFromStream, CopyToStream } from './copy-stream.js';
 export declare class IntlConnection extends SafeEventEmitter {
+    /**
+     * Server-side prepared statements this connection has built, keyed by
+     * the SQL text and its parameter OIDs - both, because the OIDs are part
+     * of what was parsed, not just how it is bound.
+     *
+     * A Map, relied on for its insertion order: re-inserting on every hit
+     * makes the first entry the least recently used, which is what gets
+     * closed when the cache is full. Statements belong to the session, so
+     * this is per connection and dies with it.
+     */
+    private _preparedCache;
+    /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
+    private _preparedCandidates;
+    private _preparedCounter;
     private _executeReusedParserCache;
     protected _refCount: number;
     protected _transactionDepth: number;
@@ -136,6 +155,21 @@ export declare class IntlConnection extends SafeEventEmitter {
      * Runs a COPY ... FROM STDIN and hands back a stream to feed it.
      * Resolves once the server is ready for data.
      */
+    /**
+     * Streams rows into a table with `COPY ... FROM STDIN (FORMAT binary)`,
+     * encoding each value with its own type's binary encoder.
+     *
+     * Binary COPY performs no conversion server-side, so the destination
+     * column types have to be known exactly. They are read from the server
+     * unless the caller supplies them: a Describe of `select <columns> from
+     * <table> where false` against the unnamed statement returns a
+     * RowDescription carrying each column's OID, which costs one round trip
+     * and leaves nothing to close (the next Parse replaces the unnamed
+     * statement). Letting PostgreSQL resolve the name is the reason to do it
+     * this way rather than reading the catalog here - schemas, quoting,
+     * search_path and views then behave exactly as they will for the COPY.
+     */
+    copyFromRows(table: string, source: CopyRowSource, options?: CopyFromRowsOptions): Promise<CopyFromRowsResult>;
     copyFrom(sql: string): Promise<CopyFromStream>;
     protected _execute(sql: string, options?: ScriptExecuteOptions, cb?: (event: string, ...args: any[]) => void): Promise<ScriptResult>;
     /**
@@ -145,7 +179,48 @@ export declare class IntlConnection extends SafeEventEmitter {
      * +close()'s 7 round trips whenever there's no cursor and no explicit/
      * active transaction to wrap (see Connection.query() for that gating).
      */
-    queryOnce(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    /**
+     * Runs a one-shot extended query, reusing a server-side prepared
+     * statement when this connection has run the same SQL before.
+     *
+     * A repeated query then costs Bind/Execute instead of
+     * Parse/Bind/Describe/Execute, which the server can answer without
+     * planning again - fifty concurrent calls of one statement measured
+     * 0.97ms against 3.13ms, and socket reads dropped from 38 to 8.
+     *
+     * Nothing is prepared on first sight: SQL has to be seen
+     * PREPARE_AFTER_USES times before it earns a name, so a query that runs
+     * once costs exactly what it costs today.
+     *
+     * A cached statement can be invalidated under us - `alter table` between
+     * two calls makes PostgreSQL answer 0A000, "cached plan must not change
+     * result type". That is caught here: the entry is dropped and the query
+     * runs again unprepared, so a migration against a live connection
+     * recovers instead of failing every call from then on.
+     */
+    queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    /**
+     * The savepoint rollbackOnError calls for, or undefined when this call
+     * needs none: outside a transaction there is nothing to roll back to,
+     * and a statement that is itself a transaction command manages its own
+     * boundaries (wrapping COMMIT in a savepoint would be nonsense).
+     */
+    protected _inlineSavepointFor(sql: string, options: QueryOptions): Maybe<string>;
+    protected _queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint: Maybe<string>): Promise<QueryResult>;
+    /**
+     * Counts one more use of this SQL and says whether it has now been seen
+     * often enough to be worth preparing under a name.
+     */
+    protected _earnsAName(key: string): boolean;
+    /** Closes the least recently used statement once the cache is full. */
+    protected _evictPreparedIfFull(): Promise<void>;
+    /**
+     * Closes an evicted statement server-side. Close answers CloseComplete
+     * but no ReadyForQuery, so the Sync goes separately and both are awaited
+     * together - the same shape PreparedStatement._close() uses.
+     */
+    protected _closePreparedStatement(name: string): Promise<void>;
+    queryOnce(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint?: string): Promise<QueryResult>;
     /**
      * Parse+Describe(statement)+Sync as a single round trip - used by
      * PreparedStatement.prepare() instead of a separately-awaited Parse then
@@ -164,7 +239,47 @@ export declare class IntlConnection extends SafeEventEmitter {
      * the RowDescription fields prepareOnce() already fetched instead of
      * re-Describing a fresh portal on every call.
      */
-    executeReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    /**
+     * Parsers and wrapped field descriptions for a statement whose
+     * RowDescription prepare() already fetched, memoised per RowDescription
+     * so repeated executes of the same statement don't rebuild them.
+     * Shared by executeReused() and executeBatchReused().
+     */
+    protected _resolveReusedParsers(cachedFields: Protocol.RowDescription[], typeMap: DataTypeMap, options: QueryOptions): {
+        parsers: AnyParseFunction[];
+        resultFields: FieldInfo[];
+    };
+    /**
+     * Executes one prepared statement once per parameter set, as a single
+     * Bind/Execute stream closed by one Sync (see
+     * PgSocket.sendBatchBindExecuteMessages() for the wire shape and what
+     * the single Sync implies).
+     *
+     * Sets map to results positionally: the server answers each Execute with
+     * its own CommandComplete, and rows that arrive before one belong to the
+     * set it closes. When the server rejects a set, everything behind it is
+     * discarded unexecuted - the completed prefix is attached to the thrown
+     * error as `batchResults`, and the rejected set's index as `failedIndex`,
+     * so a caller can tell how far the batch actually got.
+     */
+    /**
+     * Runs several different statements as one Parse/Bind/Describe/Execute
+     * stream closed by a single Sync (see PgSocket.sendPipelineMessages() for
+     * the wire shape and what that framing implies).
+     *
+     * The counterpart to executeBatchReused(): that one runs a single
+     * prepared statement over many parameter sets, this one runs many
+     * statements once each. Results map to statements positionally - the
+     * server answers each Execute with its own CommandComplete, and any rows
+     * that arrive before one belong to the statement it closes.
+     */
+    executePipeline(requests: {
+        sql: string;
+        params?: any[];
+        paramTypes?: Maybe<OID>[];
+    }[], options: QueryOptions): Promise<QueryResult[]>;
+    executeBatchReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, paramSets: Maybe<any>[][], options: QueryOptions): Promise<BatchResult>;
+    executeReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint?: string): Promise<QueryResult>;
     emit(event: string | symbol, ...args: any[]): boolean;
     protected _onError(err: Error): void;
 }