postgrejs 2.23.1 → 3.0.2

package/connection/connection.d.ts

@@ -9,15 +9,18 @@ import type { DatabaseError } from '../protocol/database-error.js';
 import type { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import type { Maybe } from '../types.js';
+import { QueryRequest } from '../util/sql-tag.js';
+import type { CopyFromStream, CopyToStream } from './copy-stream.js';
 import { IntlConnection } from './intl-connection.js';
+import { LargeObject } from './large-object.js';
 import type { Pool } from './pool.js';
 import { PreparedStatement } from './prepared-statement.js';
 export type NotificationMessage = Protocol.NotificationResponseMessage;
 export type NotificationCallback = (msg: NotificationMessage) => any;
 export declare class Connection extends SafeEventEmitter implements AsyncDisposable {
-    protected readonly _pool?: Pool;
-    protected readonly _intlCon: IntlConnection;
-    protected readonly _notificationListeners: SafeEventEmitter;
+    protected _pool?: Pool;
+    protected _intlCon: IntlConnection;
+    protected _notificationListeners?: SafeEventEmitter;
     protected _closing: boolean;
     constructor(pool: Pool, intlCon: IntlConnection);
     constructor(config?: ConnectionConfiguration | string);
@@ -26,25 +29,26 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      */
     get config(): ConnectionConfiguration;
     /**
-     * Returns true if connection is in a transaction
+     * Returns true if the connection is in a transaction
      */
     get inTransaction(): boolean;
     /**
-     * Returns current state of the connection
+     * Returns the current state of the connection
      */
     get state(): ConnectionState;
     /**
-     * Returns processId of current session
+     * Returns processId of the current session
      */
     get processID(): Maybe<number>;
     /**
-     * Returns information parameters for current session
+     * Returns information parameters for the current session
      */
     get sessionParameters(): Record<string, string>;
     /**
-     * Returns secret key of current session
+     * Returns the secret key of the current session
      */
     get secretKey(): Maybe<number>;
+    get runningQueryCount(): number;
     /**
      * Connects to the server
      */
@@ -52,7 +56,7 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
     /**
      * Closes connection. You can define how long time the connection will
      * wait for active queries before terminating the connection.
-     * On the end of the given time, it forces to close the socket and than emits `terminate` event.
+     * At the end of the given time, it forces to close the socket and then emits the ` terminate ` event.
      *
      * @param terminateWait {number} - Determines how long the connection will wait for active queries before terminating.
      */
@@ -63,47 +67,196 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * @param sql {string} - SQL script that will be executed
      * @param options {ScriptExecuteOptions} - Execute options
      */
-    execute(sql: string, options?: ScriptExecuteOptions): Promise<ScriptResult>;
-    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    execute(sql: string | QueryRequest, options?: ScriptExecuteOptions): Promise<ScriptResult>;
+    query(sql: string | QueryRequest, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Runs a `COPY ... TO STDOUT` and returns its output as a stream of the
+     * raw bytes the server sends - text, CSV or binary, whichever the
+     * statement asked for. Nothing is decoded and nothing is copied.
+     *
+     * Resolves as soon as the server accepts the copy, so a large export is
+     * never held in memory; a consumer that falls behind pauses the socket
+     * rather than buffering. `rowCount` is set before the stream ends.
+     *
+     * ```ts
+     * const out = await connection.copyTo(`COPY users TO STDOUT (FORMAT csv)`);
+     * await pipeline(out, fs.createWriteStream('users.csv'));
+     * console.log(out.rowCount);
+     * ```
+     *
+     * The stream must be consumed or destroyed: until the copy finishes the
+     * connection is still mid-statement.
+     *
+     * @param sql {string} - A COPY ... TO STDOUT statement
+     */
+    copyTo(sql: string): Promise<CopyToStream>;
+    /**
+     * Runs a `COPY ... FROM STDIN` and returns a stream to feed it. Whatever
+     * is written is forwarded verbatim, so the statement's own FORMAT decides
+     * the encoding.
+     *
+     * ```ts
+     * const inp = await connection.copyFrom(`COPY users FROM STDIN (FORMAT csv)`);
+     * await pipeline(fs.createReadStream('users.csv'), inp);
+     * console.log(inp.rowCount);
+     * ```
+     *
+     * 'finish' means the server accepted the copy, not merely that the last
+     * byte was written. If the source fails, `pipeline()` destroys the stream
+     * and a CopyFail is sent, so the connection stays usable.
+     *
+     * @param sql {string} - A COPY ... FROM STDIN statement
+     */
+    copyFrom(sql: string): Promise<CopyFromStream>;
     /**
      * Creates a PreparedStatement instance
      * @param sql {string} - SQL script that will be executed
      * @param options {StatementPrepareOptions} - Options
      */
     prepare(sql: string, options?: StatementPrepareOptions): Promise<PreparedStatement>;
+    /**
+     * Creates a large object and opens it for reading and writing.
+     *
+     * A large object holds binary data outside any row, reachable a piece at
+     * a time instead of whole the way a `bytea` column is - which is what it
+     * is for, along with a 4TB ceiling rather than roughly 1GB.
+     *
+     * ```ts
+     * const lo = await connection.createLargeObject();
+     * await pipeline(fs.createReadStream('video.mp4'), lo.writable());
+     * await lo.close();
+     * await table.insert({ videoOid: lo.oid });
+     * ```
+     *
+     * Nothing links the object to the row that names it: dropping the row
+     * leaves the data behind, so unlinkLargeObject() has to be called when it
+     * is no longer wanted. PostgreSQL ships `vacuumlo` for finding the ones
+     * that were not.
+     */
+    createLargeObject(mode?: 393216): Promise<LargeObject>;
+    /**
+     * Opens an existing large object by its OID. See createLargeObject() for
+     * how the transaction is handled.
+     */
+    openLargeObject(oid: number, mode?: 262144): Promise<LargeObject>;
+    /** Deletes a large object and its data. */
+    unlinkLargeObject(oid: number): Promise<void>;
+    /**
+     * Asks the server to cancel whatever this connection is currently running.
+     *
+     * Travels on its own short-lived connection, since a backend busy with a
+     * query is not reading its own socket. It is a request, not a guarantee -
+     * the statement may finish first - and the cancelled call reports the
+     * outcome itself, rejecting with SQLSTATE 57014 if the server acted on it.
+     * Prefer the per-call `signal` option, which does this and reports the
+     * abort to the right caller.
+     */
+    cancel(): Promise<void>;
     /**
      * Starts a transaction
      */
     startTransaction(): Promise<void>;
     /**
-     * Commits current transaction
+     * Commits current transaction.
+     * @param immediate - Commits right away, ignoring how many nested
+     *   startTransaction() calls are still unmatched by a commit().
      */
-    commit(): Promise<void>;
+    commit(immediate?: boolean): Promise<void>;
     /**
      * Rolls back current transaction
      */
     rollback(): Promise<void>;
+    /**
+     * Ends the current transaction as a prepared one, for two-phase commit.
+     *
+     * The transaction stops belonging to this session and waits under `name`
+     * until it is finished by commitPrepared() or rollbackPrepared() - which
+     * may run on another connection, in another process, after this one is
+     * gone. That is the point: it lets several databases agree to commit
+     * before any of them actually does.
+     *
+     * ```ts
+     * await connection.startTransaction();
+     * await connection.query(sql`insert into t values (${1})`);
+     * await connection.prepareTransaction('tx1');
+     * // ...later, anywhere:
+     * await other.commitPrepared('tx1');
+     * ```
+     *
+     * PostgreSQL ships with `max_prepared_transactions` at zero, so this
+     * fails until the server is configured for it.
+     */
+    prepareTransaction(name: string): Promise<void>;
+    /**
+     * Commits a transaction left waiting by prepareTransaction(), by name.
+     * Runs outside any transaction and needs no connection to the session
+     * that prepared it.
+     */
+    commitPrepared(name: string): Promise<void>;
+    /** Discards a transaction left waiting by prepareTransaction(), by name. */
+    rollbackPrepared(name: string): Promise<void>;
     /**
      * Starts transaction and creates a savepoint
      * @param name {string} - Name of the savepoint
      */
     savepoint(name: string): Promise<void>;
     /**
-     * Rolls back current transaction to given savepoint
+     * Rolls back the current transaction to given savepoint
      * @param name {string} - Name of the savepoint
      */
     rollbackToSavepoint(name: string): Promise<void>;
     /**
      * Releases savepoint
      * @param name {string} - Name of the savepoint
+     * @param immediate - Releases right away, ignoring how many nested
+     *   savepoint() calls under this name are still unmatched by a
+     *   releaseSavepoint().
      */
-    releaseSavepoint(name: string): Promise<void>;
+    releaseSavepoint(name: string, immediate?: boolean): Promise<void>;
     listen(channel: string, callback: NotificationCallback): Promise<void>;
     unListen(channel: string): Promise<void>;
     unListenAll(): Promise<void>;
+    protected _query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * A large object's descriptor is only valid inside the transaction that
+     * opened it. One is started here when there is none, and reported so that
+     * close() commits only what it started - a transaction the caller opened
+     * stays theirs. Mirrors what savepoint() already does.
+     */
+    protected _beginForLargeObject(): Promise<boolean>;
+    protected _openLargeObject(oid: number, mode: number, ownsTransaction: boolean): Promise<LargeObject>;
     protected _handleNotification(msg: NotificationMessage): void;
     protected _close(): Promise<void>;
     protected _handleError(err: DatabaseError, script: string): DatabaseError;
-    protected _captureErrorStack<T>(promise: Promise<T>): Promise<T>;
+    /**
+     * Remembers where a call came from, so the error it may reject with points
+     * at the caller instead of at an internal async frame.
+     *
+     * `entry` is the public method to cut the trace at: everything from it
+     * inwards is this library's own plumbing and is dropped, which matters
+     * because the captured depth is deliberately small - spending four of five
+     * frames on our own call chain would leave one for the caller, and any
+     * helper of theirs would push the real call site off the end.
+     *
+     * Skippable via `asyncErrorHandling: false` - capturing costs a real,
+     * measurable slice of CPU time once many calls are in flight at once
+     * (a pipelined burst on one connection), where it has to compete with
+     * every other call for the same core instead of hiding behind network
+     * wait the way it does for a single sequential call.
+     *
+     * `asyncErrorHandling` is the per-call override (execute()/query()'s own
+     * option of the same name); when omitted, the connection's own
+     * `DatabaseConnectionParams.asyncErrorHandling` decides.
+     *
+     * Not `async` itself, deliberately: every branch below already returns a
+     * promise directly (`promise` itself, or `promise.catch(...)`'s own
+     * derived one) with no `await` in between, so there is nothing here that
+     * needs the function to be a coroutine. Marking it `async` anyway would
+     * still be correct, but the spec requires wrapping whatever an async
+     * function returns through a promise-resolve step, a genuine extra
+     * microtask tick on top of the one `promise`/`.catch()` already goes
+     * through - paid on every single query this wraps, disabled or not.
+     */
+    protected _captureErrorStack<T>(promise: Promise<T>, entry?: (...args: any[]) => any, asyncErrorHandling?: boolean): Promise<T>;
     [Symbol.asyncDispose](): Promise<void>;
 }