@vibeorm/adapter-pg 5.0.1 → 5.1.0

package/README.md

@@ -98,6 +98,16 @@ Behind any other transaction-mode pooler (PgBouncer before 1.21 or with `max_pre
 
 One case stays silent with every naming scheme: a statement prepared before DDL **shadows** a table. If a migration creates a table with the same name in a schema that comes earlier in the unchanged `search_path`, the prepared statement keeps reading the table it was parsed against until the connection is recycled. (A changed `search_path` itself is safe: PostgreSQL re-parses the statement.) Recycle connections after such a migration, as for the result-shape changes below.
 
+### Named raw statements
+
+The raw path takes a caller-chosen statement name: `executeUnsafe({ text, values, name })`, which the runtime exposes as `$queryRawUnsafe({ text, values, name })` / `$executeRawUnsafe(…)`, `commitWith: { query, name }` and `commitQuery({ query, name })`. The name is honoured whatever `preparedStatements` says; without one, nothing is named.
+
+- **Parse once per connection.** A plain query is sent as `{ name, text, values }`, so node-postgres parses it the first time on each connection. In a one-Sync batch (pipelined statements, the opening, the statement that rides with `COMMIT`) the step writes `Parse` with the name only when this connection has not prepared it, then `Bind` / `Execute` against the name. Both paths keep ONE record: node-postgres' own `parsedStatements` / `submittedNamedStatements`. A name counts as prepared only after its `ParseComplete` arrived; a Parse the server refused or skipped is forgotten. A statement prepared by a protocol Parse stays prepared when its transaction rolls back, and the record keeps it.
+- **One text per name.** The first text a name is used with is its text for the pool's lifetime; a different text is refused before it is sent (`VIBE_VALIDATION`, `meta.reason: "statement-name-reused"`). Names are a fixed set: each one is prepared on every connection that runs it.
+- **Name rules.** Not empty, at most 63 UTF-8 bytes (PostgreSQL truncates longer names), no NUL character (`VIBE_VALIDATION`).
+- **Poolers.** A named statement must reach the backend that prepared it. Behind a transaction-mode pooler without prepared-statement support the call fails with `26000` / `42P05`, with the pooler hint above. Send no name there.
+- **Schema changes.** A DDL change of a named statement's result shape answers `0A000`, as described next; recycle the connections.
+
 ### Schema changes with prepared statements
 
 **Recycle backend connections after a migration changes a prepared query's result shape.** PostgreSQL can reject the retained plan with SQLSTATE `0A000` (`cached plan must not change result type`), for example after changing the type of a selected column. `SELECT *` can also be affected by adding a column. `planCacheMode: "force_custom_plan"` does not prevent result-descriptor invalidation.

package/dist/batch.d.ts

@@ -20,11 +20,28 @@
  * so parameters serialize exactly as `client.query` serializes them. Rows are
  * decoded HERE, with the adapter's query-local type parsers — never through
  * node-postgres' internal `lib/result.js`.
+ *
+ * Named steps (throughput request 1): a step with a `name` is parsed under
+ * that name only when this connection has not prepared it yet, and bound to
+ * the name either way. The record of prepared names is node-postgres' OWN
+ * (`connection.parsedStatements` / `submittedNamedStatements`, the objects its
+ * `Query` reads), kept exactly as `Query` keeps it: a name is "submitted" when
+ * its Parse is written, "parsed" only when its ParseComplete arrives (the
+ * connection's `parseComplete` event, counted per Parse this batch wrote), and
+ * forgotten when the server refused or skipped its Parse. So a name a plain
+ * query prepared is never parsed again here, and the other way round.
  */
 /** One statement of a batch. Values are the adapter's already-serialized params. */
 export type BatchStep = {
     readonly text: string;
     readonly values?: readonly unknown[];
+    /**
+     * A caller-chosen prepared-statement name (raw path, throughput request 1):
+     * parsed under it once per connection, bound to it every time. A text that
+     * differs from the one this connection already holds is refused before any
+     * step or bookkeeping change.
+     */
+    readonly name?: string;
     /**
      * Nobody reads this step's rows (statement-count pass EPIC 5: the final
      * statement that rides with COMMIT): they are not decoded, so no type parser
@@ -58,6 +75,16 @@ export type BatchOutcome = {
      * server did with the batch is unknown; `steps` lists only what was seen.
      */
     readonly transportError?: unknown;
+    /**
+     * With `transportError`: PROVABLY no byte of this batch reached the socket,
+     * so the server received none of its statements. Either node-postgres never
+     * submitted the batch (a client already not queryable or ending answers
+     * `query()` with `handleError` and never calls `submit`; a client that fails
+     * errors its queued queries the same way), or its stream was no longer
+     * writable when it was (node-postgres' `Connection._send` writes nothing to a
+     * stream that is not writable, and a socket never becomes writable again).
+     */
+    readonly unsent?: true;
 };
 /** The query-local type parser surface (the adapter's `EXACT_TYPES`). */
 export type BatchTypeParsers = {
@@ -93,6 +120,10 @@ export declare function prepareBatchValues(params: {
  * The Submittable. Construct with steps whose values are already prepared
  * ({@link prepareBatchValues}); pass to `client.query(batch)`; await
  * {@link PgBatch.done}.
+ *
+ * It has NO `name` property on purpose: node-postgres' own ParseComplete and
+ * ErrorResponse handlers record `activeQuery.name`, and a batch's names are
+ * recorded per step here instead.
  */
 export declare class PgBatch {
     /** Settles once: at the batch's ReadyForQuery, at its first server error, or at a transport failure. */
@@ -113,12 +144,35 @@ export declare class PgBatch {
     private rowError;
     private settled;
     private resolve;
+    /** The connection's statement record while a named Parse of this batch may still be answered. */
+    private book;
+    /** Every Parse this batch wrote, in order: the k-th ParseComplete answers the k-th entry. */
+    private parses;
+    private parsesAnswered;
+    private stopParseTracking;
+    /** Whether `submit` wrote this batch's messages to a writable stream ({@link BatchOutcome.unsent} otherwise). */
+    private written;
     constructor(params: {
         steps: readonly BatchStep[];
         types: BatchTypeParsers;
     });
-    /** Called by node-postgres when the batch reaches the head of the client's queue. */
-    submit(connection: unknown): void;
+    /**
+     * Called by node-postgres when the batch reaches the head of the client's
+     * queue. Returns an error, with nothing written, when a statement name
+     * conflicts or the stream is no longer writable. node-postgres then calls
+     * `handleError`, as for its own `Query.submit` refusals; `null` once written.
+     */
+    submit(connection: unknown): Error | null;
+    /** One ParseComplete: the oldest unanswered Parse of this batch succeeded — its name is prepared now. */
+    private answerParse;
+    /**
+     * No more ParseComplete can come for this batch (its ReadyForQuery, or a
+     * server error: the server skips every message up to the Sync). A Parse
+     * still unanswered was refused or skipped, so its name is NOT prepared:
+     * forget it, as node-postgres' `_handleErrorMessage` forgets a query's
+     * submitted name. Recording it would answer 26000 on its next use.
+     */
+    private endParseTracking;
     handleRowDescription(message: {
         fields: readonly RowDescriptionField[];
     }): void;