@mistriwork/engine 1.0.0-rc.39 → 1.0.0-rc.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -51,58 +51,11 @@ export declare class PostgresAdapter implements Adapter {
51
51
  /** Each replica's state, when the connection names any (replicas.ts). */
52
52
  replicaHealth(): ReturnType<PgConnectionManager['replicaHealth']>;
53
53
  private conn;
54
- /**
55
- * Run a statement the user wrote.
56
- *
57
- * The session already carries `default_transaction_read_only = on`, and for
58
- * everything else in this adapter that is enough, because every statement is
59
- * one this file built. It is **not** enough here: `SET
60
- * default_transaction_read_only = off` is itself a statement, and a user who
61
- * typed it followed by a `DELETE` would get both.
62
- *
63
- * `BEGIN READ ONLY` is the version that holds, for one statement. Postgres
64
- * refuses `SET TRANSACTION READ WRITE` once the transaction has taken its
65
- * first snapshot, and one statement takes it before it runs. It does not hold
66
- * against several: `COMMIT; BEGIN READ WRITE; DELETE …` ends the read-only
67
- * transaction and opens a writable one. So the text goes on the extended
68
- * protocol (`queryMode: 'extended'`), where Postgres itself refuses a second
69
- * statement; refuseStacked is the earlier, clearer refusal, not the guard.
70
- * (node-postgres sends a query with an empty `values` on the simple protocol,
71
- * which runs every statement in the string.) The `ROLLBACK` afterwards also
72
- * discards any session state the statement set, so one run cannot change what
73
- * the next one means.
74
- *
75
- * The rollback runs in a `finally`: a statement that errors has still opened
76
- * a transaction, and leaving it open would leave the connection in an aborted
77
- * state where every later query fails with "current transaction is aborted".
78
- *
79
- * `write: true` is the other half, and it is a different request rather than
80
- * a relaxation of this one: a separate handle, no READ ONLY transaction, and
81
- * a decision made further up about whether this connection may write at all.
82
- * The two paths share the statement text and nothing else.
83
- */
54
+ /** Run a statement the user wrote; runPostgresSql says how it is held read-only. */
84
55
  runSql(request: SqlRequest): Promise<SqlResult>;
85
- /**
86
- * EXPLAIN, plain — never the analysing variant that executes to time.
87
- *
88
- * `runSql`'s bounding wrap is precisely wrong here: a statement made a
89
- * derived table is a different statement, with a different plan. The text
90
- * goes to the planner as written, inside the same READ ONLY transaction
91
- * every user statement gets — so even a smuggled write is only ever
92
- * planned, and an execution attempt is the transaction's to refuse, not a
93
- * string check's.
94
- */
56
+ /** EXPLAIN, plain, never the analysing variant (explainPostgresSql). */
95
57
  explainSql(request: ExplainRequest): Promise<ExplainResult>;
96
- /**
97
- * The planner's own statistics, read rather than computed.
98
- *
99
- * `pg_stats` already holds the null share, the distinct estimate, the most
100
- * common values with their frequencies, and the histogram — ANALYZE paid
101
- * for them, reading them touches no user table. The numbers are
102
- * sample-based and stale until the next ANALYZE, which is what
103
- * `source: 'statistics'` tells the caller; a column ANALYZE has never
104
- * visited simply has no numbers, which beats invented ones.
105
- */
58
+ /** The planner's own statistics, read rather than computed (profilePostgresTable). */
106
59
  profile(table: string): Promise<ProfileResult>;
107
60
  introspect(): Promise<DatabaseSchema>;
108
61
  private introspectNow;
@@ -11,7 +11,7 @@ import { isProxy } from 'node:util/types';
11
11
  import { inlineRows } from '../shared/anyRows.js';
12
12
  import { asksAboutRows } from '../shared/filter.js';
13
13
  import { qualifiedTable } from '../shared/sqlRelation.js';
14
- import { POSTGRES_STYLE, buildWhere, clampLimit, boundStatement, dedupe, looksWrappable, refuseStacked, trimStatement, clampOffset, Refusal, WriteConflict, TransactionOperations, queueRecordLock, recordLockFilter, TransactionOutcomeUnknown, refuseAnalyze, countStatement, countEachStatement, countEachRows, countsTogether, orderClause, lanesStatement, withoutLaneRow, refuseUpdateMatches, } from './adapter.js';
14
+ import { POSTGRES_STYLE, buildWhere, clampLimit, clampOffset, Refusal, WriteConflict, TransactionOperations, queueRecordLock, recordLockFilter, TransactionOutcomeUnknown, countStatement, countEachStatement, countEachRows, countsTogether, orderClause, lanesStatement, withoutLaneRow, refuseUpdateMatches, } from './adapter.js';
15
15
  import { compileAggregate } from '../shared/aggregate.js';
16
16
  import { coerceForColumn } from '../shared/schema.js';
17
17
  import { buildUpdateGuard } from './scoped/updateGuard.js';
@@ -21,13 +21,13 @@ import { postgresTriggerAnalyzer, postgresTriggersByTable, postgresTriggerStatem
21
21
  import { captureScopeCatalog, mapScopeCatalog } from '../shared/scopeCatalog.js';
22
22
  import { createPinnedPostgresReadOwner } from './postgresReadCatalog.js';
23
23
  import { batchesThrough, gatheredBatches, insertPlanned, updatePlanned } from './postgresBatchWrites.js';
24
- import { isRuntimeRelation, qualified, redact, valueSafe, withBytes, toJsonSafe } from './postgresValues.js';
24
+ import { isRuntimeRelation, qualified, redact, withBytes, toJsonSafe } from './postgresValues.js';
25
25
  import { beginWriteCapture, capturesWrites, committedWriteCapture, finishWriteCapture } from './writeCapture.js';
26
26
  import { lendStoreHost, } from './storeHost.js';
27
27
  import { compileView, compileViewCount } from '../shared/view.js';
28
28
  import { compileBreakdown, compileBreakdownCount } from '../shared/breakdown.js';
29
29
  import { PgConnectionManager, sharedPgConnections } from './postgresPool.js';
30
- import { aheadReport, beforeCommit, behindWrite, generationOf, redoWithoutAhead, sendsAhead, waitsAhead, RolledBackAtCommit, transactionHandle, attestedOn, keepAttestedOn, forgetAttestations, noteCatalogVersion, readsCatalogVersion, suspectsStores, } from './postgresTransactionHandle.js';
30
+ import { aheadReport, beforeCommit, behindWrite, generationOf, heldAhead, redoWithoutAhead, sendsAhead, waitsAhead, RolledBackAtCommit, transactionHandle, attestedOn, keepAttestedOn, forgetAttestations, noteCatalogVersion, readsCatalogVersion, suspectsStores, } from './postgresTransactionHandle.js';
31
31
  import { snapshotRead, withoutSnapshotRead } from './snapshotRead.js';
32
32
  import { SCOPED_SESSION, beginOf, snapshotHandles, verifierPin } from './postgresTransactionOpening.js';
33
33
  import { withoutWriteAhead, writeAhead } from './writeAhead.js';
@@ -43,11 +43,11 @@ import { captureRowScope, snapshotRowScope } from '../shared/rowScope.js';
43
43
  import { createScopedReads } from './scoped/scopedReads.js';
44
44
  import { scopedCommandInvoker } from './scoped/scopedCommandOperations.js';
45
45
  import { postgresPrivileges } from './rolePrivileges.js';
46
- import { RESERVED_SCHEMAS, refusePostgresReserved, refuseReservedPlan, refuseReservedText } from './reservedSql.js';
47
- import { statementCap } from './statementControl.js';
46
+ import { RESERVED_SCHEMAS } from './reservedSql.js';
48
47
  import { WriteLanes, keyedLane, lockTimedOut } from './writeLanes.js';
49
48
  import { primaryReads } from './replicas.js';
50
49
  import { readSnapshotOn } from './postgresReadSnapshot.js';
50
+ import { explainPostgresSql, profilePostgresTable, runPostgresSql } from './postgresSql.js';
51
51
  const pinnedReaders = new WeakMap();
52
52
  /** Constructor-issued source identity, checked without reading receiver data. */
53
53
  export const isPostgresVerifiedCommandSource = (value) => !!value && typeof value === 'object' && !isProxy(value) && pinnedReaders.has(value);
@@ -171,233 +171,18 @@ export class PostgresAdapter {
171
171
  conn() {
172
172
  return this.connections.read();
173
173
  }
174
- /**
175
- * Run a statement the user wrote.
176
- *
177
- * The session already carries `default_transaction_read_only = on`, and for
178
- * everything else in this adapter that is enough, because every statement is
179
- * one this file built. It is **not** enough here: `SET
180
- * default_transaction_read_only = off` is itself a statement, and a user who
181
- * typed it followed by a `DELETE` would get both.
182
- *
183
- * `BEGIN READ ONLY` is the version that holds, for one statement. Postgres
184
- * refuses `SET TRANSACTION READ WRITE` once the transaction has taken its
185
- * first snapshot, and one statement takes it before it runs. It does not hold
186
- * against several: `COMMIT; BEGIN READ WRITE; DELETE …` ends the read-only
187
- * transaction and opens a writable one. So the text goes on the extended
188
- * protocol (`queryMode: 'extended'`), where Postgres itself refuses a second
189
- * statement; refuseStacked is the earlier, clearer refusal, not the guard.
190
- * (node-postgres sends a query with an empty `values` on the simple protocol,
191
- * which runs every statement in the string.) The `ROLLBACK` afterwards also
192
- * discards any session state the statement set, so one run cannot change what
193
- * the next one means.
194
- *
195
- * The rollback runs in a `finally`: a statement that errors has still opened
196
- * a transaction, and leaving it open would leave the connection in an aborted
197
- * state where every later query fails with "current transaction is aborted".
198
- *
199
- * `write: true` is the other half, and it is a different request rather than
200
- * a relaxation of this one: a separate handle, no READ ONLY transaction, and
201
- * a decision made further up about whether this connection may write at all.
202
- * The two paths share the statement text and nothing else.
203
- */
204
- async runSql(request) {
205
- const stacked = refuseStacked(request.text, 'postgres');
206
- if (stacked)
207
- throw new Error(stacked);
208
- if (request.refuseReserved)
209
- refusePostgresReserved(request.text, request.write);
210
- const limit = clampLimit(request.limit);
211
- /* A write is never wrapped in a bounding subquery: `UPDATE … RETURNING`
212
- inside `SELECT * FROM (…)` is a different statement, and one Postgres
213
- refuses outright. The caller asked for this text; it runs as typed. */
214
- const bounded = !request.write && looksWrappable(request.text);
215
- const text = bounded ? boundStatement(request.text, limit) : trimStatement(request.text);
216
- if (request.write) {
217
- /* On the write handle, and outside the READ ONLY transaction every other
218
- statement here gets — which is the whole difference. Whether this is
219
- allowed at all was decided before the request arrived: the connection
220
- has to be marked writable in the config, and that check does not live
221
- in the adapter.
222
-
223
- No wrapper transaction of our own. One statement is already atomic in
224
- Postgres, and a BEGIN/COMMIT around it would only add a way to leave a
225
- transaction open on a connection that outlives the request. */
226
- return this.writes.run('all', () => this.connections.withWriteClient(async (write) => {
227
- const started = performance.now();
228
- // Extended protocol: one statement, as on the read path below.
229
- const result = await write.query({ text, values: [], rowMode: 'array', queryMode: 'extended' });
230
- return {
231
- /* A write that returns rows — `RETURNING` — is worth showing, and one
232
- that does not returns an empty grid rather than a fabricated one.
233
- Array rows, so two columns of one name keep both values. */
234
- columns: dedupe(result.fields?.map((f) => f.name) ?? []),
235
- rows: (result.rows ?? []).map((row) => row.map(valueSafe)),
236
- ms: Math.round(performance.now() - started),
237
- truncated: false,
238
- bounded: false,
239
- affected: Number(result.rowCount ?? 0),
240
- sql: { text, params: [] },
241
- };
242
- }, true));
243
- }
244
- return this.connections.withReadClient(async (db) => {
245
- const started = performance.now();
246
- /* The statement's cap, set where it dies with the transaction, so the
247
- session's own is untouched — and statementCap's floor stops a caller
248
- asking for a timeout so low that even the fast path loses races to it. */
249
- const cap = statementCap(request.timeoutMs);
250
- const begin = () => db.query('BEGIN READ ONLY').then(() => db.query(`SET LOCAL statement_timeout = ${cap}`));
251
- await begin();
252
- try {
253
- if (request.refuseReserved)
254
- await refuseReservedPlan(db, request.text, []);
255
- /* `rowMode: 'array'` so two output columns of the same name keep both
256
- values; the default object rows would let the second overwrite the
257
- first. `queryMode: 'extended'` is what carries exactly one statement:
258
- an empty `values` alone leaves node-postgres on the simple protocol,
259
- which would run a stacked COMMIT and a write after it. */
260
- let wrapped = bounded;
261
- const result = await db.query({ text, values: [], rowMode: 'array', queryMode: 'extended' }).catch(async (err) => {
262
- /* The wrap is an optimisation that is allowed to fail — not every
263
- legal statement survives being made a derived table. Run as
264
- written and reported as unbounded. The transaction has to be
265
- restarted: a failed statement aborts it, and every later query in
266
- it would fail with "current transaction is aborted". A statement
267
- that was stopped — cancelled, or past its cap (57014) — is not a
268
- wrap that failed, and running it again would spend the cap twice. */
269
- if (!bounded || err.code === '57014')
270
- throw err;
271
- wrapped = false;
272
- await db.query('ROLLBACK');
273
- await begin();
274
- return db.query({ text: trimStatement(request.text), values: [], rowMode: 'array', queryMode: 'extended' });
275
- });
276
- const truncated = result.rows.length > limit;
277
- return {
278
- columns: dedupe(result.fields.map((f) => f.name)),
279
- rows: (truncated ? result.rows.slice(0, limit) : result.rows).map((row) => row.map(valueSafe)),
280
- ms: Math.round(performance.now() - started),
281
- truncated,
282
- bounded: wrapped,
283
- sql: { text: wrapped ? text : trimStatement(request.text), params: [] },
284
- };
285
- }
286
- finally {
287
- await db.query('ROLLBACK').catch(() => {
288
- /* The connection is already unusable if this fails; the original error
289
- is the one worth reporting. */
290
- });
291
- }
292
- }, true);
174
+ /** Run a statement the user wrote; runPostgresSql says how it is held read-only. */
175
+ runSql(request) {
176
+ return runPostgresSql(this.connections, this.writes, request);
293
177
  }
294
- /**
295
- * EXPLAIN, plain — never the analysing variant that executes to time.
296
- *
297
- * `runSql`'s bounding wrap is precisely wrong here: a statement made a
298
- * derived table is a different statement, with a different plan. The text
299
- * goes to the planner as written, inside the same READ ONLY transaction
300
- * every user statement gets — so even a smuggled write is only ever
301
- * planned, and an execution attempt is the transaction's to refuse, not a
302
- * string check's.
303
- */
304
- async explainSql(request) {
305
- const stacked = refuseStacked(request.text, 'postgres');
306
- if (stacked)
307
- throw new Error(stacked);
308
- const analyze = refuseAnalyze(request.text);
309
- if (analyze)
310
- throw new Error(analyze);
311
- if (request.refuseReserved)
312
- refuseReservedText(request.text, 'postgres');
313
- return this.connections.withReadClient(async (db) => {
314
- const started = performance.now();
315
- await db.query('BEGIN READ ONLY');
316
- try {
317
- /* Planning runs nothing, but planning a wide join still takes time. */
318
- await db.query(`SET LOCAL statement_timeout = ${statementCap()}`);
319
- if (request.refuseReserved)
320
- await refuseReservedPlan(db, request.text, (request.params ?? []));
321
- const result = await db.query({
322
- text: `EXPLAIN ${trimStatement(request.text)}`,
323
- values: (request.params ?? []),
324
- rowMode: 'array',
325
- // One statement, whether or not there are parameters: see runSql.
326
- queryMode: 'extended',
327
- });
328
- return {
329
- plan: result.rows.map((r) => String(r[0])),
330
- ms: Math.round(performance.now() - started),
331
- };
332
- }
333
- finally {
334
- await db.query('ROLLBACK').catch(() => { });
335
- }
336
- }, true);
178
+ /** EXPLAIN, plain, never the analysing variant (explainPostgresSql). */
179
+ explainSql(request) {
180
+ return explainPostgresSql(this.connections, request);
337
181
  }
338
- /**
339
- * The planner's own statistics, read rather than computed.
340
- *
341
- * `pg_stats` already holds the null share, the distinct estimate, the most
342
- * common values with their frequencies, and the histogram — ANALYZE paid
343
- * for them, reading them touches no user table. The numbers are
344
- * sample-based and stale until the next ANALYZE, which is what
345
- * `source: 'statistics'` tells the caller; a column ANALYZE has never
346
- * visited simply has no numbers, which beats invented ones.
347
- */
182
+ /** The planner's own statistics, read rather than computed (profilePostgresTable). */
348
183
  async profile(table) {
349
184
  const { schema, name } = await this.readTable(table);
350
- const db = await this.conn();
351
- const started = performance.now();
352
- const rel = await db.query(`SELECT CASE WHEN c.reltuples < 0 THEN NULL ELSE c.reltuples END AS approx_rows
353
- FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
354
- WHERE n.nspname = $1 AND c.relname = $2`, [schema, name]);
355
- const approx = rel.rows[0]?.approx_rows;
356
- const rows = postgresRowEstimate(approx);
357
- /* Every live column, with its stats row where ANALYZE has made one.
358
- `most_common_vals` and `histogram_bounds` are `anyarray`, which the
359
- driver has no parser for; the ::text::text[] two-step turns them into
360
- the text array it can parse. */
361
- const stats = await db.query(`SELECT a.attname::text AS column,
362
- format_type(a.atttypid, a.atttypmod) AS type,
363
- s.null_frac,
364
- s.n_distinct,
365
- s.most_common_vals::text::text[] AS common_values,
366
- s.most_common_freqs AS common_freqs,
367
- s.histogram_bounds::text::text[] AS bounds
368
- FROM pg_attribute a
369
- JOIN pg_class c ON c.oid = a.attrelid
370
- JOIN pg_namespace n ON n.oid = c.relnamespace
371
- LEFT JOIN pg_stats s ON s.schemaname = n.nspname AND s.tablename = c.relname AND s.attname = a.attname
372
- WHERE n.nspname = $1 AND c.relname = $2 AND a.attnum > 0 AND NOT a.attisdropped
373
- ORDER BY a.attnum`, [schema, name]);
374
- const columns = stats.rows.map((r) => {
375
- /* Negative n_distinct is a ratio — "-0.3 of the rows are distinct" —
376
- which only converts when a row estimate exists to multiply by. */
377
- const distinct = r.n_distinct == null
378
- ? undefined
379
- : Number(r.n_distinct) >= 0
380
- ? Math.round(Number(r.n_distinct))
381
- : rows === undefined
382
- ? undefined
383
- : Math.round(-Number(r.n_distinct) * rows);
384
- const common = r.common_values?.length && r.common_freqs?.length
385
- ? r.common_values.map((v, i) => ({ value: v, frac: Number(r.common_freqs?.[i] ?? 0) }))
386
- : undefined;
387
- return {
388
- column: r.column,
389
- type: r.type,
390
- nullFrac: r.null_frac == null ? undefined : Number(r.null_frac),
391
- distinct,
392
- /* The histogram's outer edges, as text from the sample. A column too
393
- uniform to earn a histogram gets no min/max — its common values
394
- sorted lexically would call 9 larger than 10. */
395
- min: r.bounds?.length ? r.bounds[0] : undefined,
396
- max: r.bounds?.length ? r.bounds[r.bounds.length - 1] : undefined,
397
- common,
398
- };
399
- });
400
- return { table, rows, columns, source: 'statistics', ms: Math.round(performance.now() - started) };
185
+ return profilePostgresTable(table, schema, name, await this.conn());
401
186
  }
402
187
  /* The catalog is the primary's, whatever route asks for it first: a
403
188
  replica a migration has not reached yet would describe the old one, and
@@ -1547,8 +1332,8 @@ export class PostgresAdapter {
1547
1332
  the identical statement once when the transaction asks it, and a
1548
1333
  target's row answers its reads by key (keyRows.ts). */
1549
1334
  const keyRows = new KeyRows(() => generationOf(write));
1550
- // The rows whose locks were sent ahead, held from the moment their answers came back (sendWriteAhead).
1551
- const lockedAhead = new Set();
1335
+ // The rows whose locks were sent ahead, held from the moment their answers came back (sendWriteAhead), with what each lock said.
1336
+ const lockedAhead = new Map();
1552
1337
  let aheads = [];
1553
1338
  const opening = { lock: pinned, pin, digest: true, session: SCOPED_SESSION };
1554
1339
  let opened = await this.openWrite(write, {
@@ -1599,7 +1384,12 @@ export class PostgresAdapter {
1599
1384
  const holds = (table, key) => {
1600
1385
  const pk = table.columns.filter((column) => column.primaryKey).map((column) => column.name);
1601
1386
  const at = rowLockKey(table, { groups: [pk.map((column) => ({ column, op: '=', value: key[column] }))] });
1602
- return held.get(at) === 'UPDATE' || lockedAhead.has(at);
1387
+ if (held.get(at) === 'UPDATE')
1388
+ return true;
1389
+ const ahead = lockedAhead.get(at);
1390
+ if (ahead)
1391
+ heldAhead(write, ahead);
1392
+ return !!ahead;
1603
1393
  };
1604
1394
  const executor = (guard) => async (sql, hint) => {
1605
1395
  const started = performance.now();
@@ -1641,17 +1431,31 @@ export class PostgresAdapter {
1641
1431
  const text = `SELECT 1 FROM ${qualified(table)}${where.text} FOR ${mode}`;
1642
1432
  /* Sent ahead behind the BEGIN and granted, its answer since dropped by a write of the transaction's own:
1643
1433
  the row is held all the same, to the transaction's end. While that answer still waits, asking takes it. */
1644
- if (lockedAhead.has(at) && !waitsAhead(write, { text, values: where.params })) {
1434
+ const ahead = lockedAhead.get(at);
1435
+ if (ahead && !waitsAhead(write, { text, values: where.params })) {
1436
+ heldAhead(write, ahead);
1645
1437
  held.set(at, 'UPDATE');
1646
1438
  return;
1647
1439
  }
1648
1440
  await write.query(text, where.params);
1649
1441
  held.set(at, mode);
1650
1442
  };
1443
+ /* The capture's read of the row it keeps a before image of, unscoped as an unscoped transaction's: answered
1444
+ from the whole row sent ahead for it (sendWriteAhead) while nothing has moved since, else in its turn. */
1445
+ const captureAsked = new WeakMap();
1446
+ const captureReads = keyRows.over({ query: (request) => this.queryOn(captureAsked.get(request) ?? request, write) }, PLAIN_SCOPE, catalog.schema, (request) => plainStatement(request), (row, request) => (request.binary ? withBytes : toJsonSafe)(row), false).query;
1651
1447
  const writes = this.historyWrites(write, {
1652
1448
  insert: (r) => this.insertNow(r, write, write, true),
1653
1449
  remove: (r) => this.removeNow(r, write, write),
1654
1450
  update: (r) => this.updateNow(r, write, write),
1451
+ },
1452
+ // Filed under the table's id, as the rows sent ahead are; a read asked in its turn is sent as it was asked.
1453
+ (request) => {
1454
+ if (typeof request?.table !== 'string' || catalogId(request.table) === request.table)
1455
+ return captureReads(request);
1456
+ const named = { ...request, table: catalogId(request.table) };
1457
+ captureAsked.set(named, request);
1458
+ return captureReads(named);
1655
1459
  });
1656
1460
  // The tables whose validation-only triggers a write of this transaction fired: their proof is read again before COMMIT.
1657
1461
  const relied = new Set();
@@ -0,0 +1,63 @@
1
+ /**
2
+ * The three statements a person writes or asks about rather than the ones this
3
+ * adapter builds: raw SQL (read-only by transaction, or on the write handle),
4
+ * EXPLAIN, and the planner's statistics. They share nothing with the adapter's
5
+ * catalog or write caches, only its connection pools, so they live apart from
6
+ * postgres.ts, which had outgrown a file a person can hold.
7
+ */
8
+ import { type ExplainRequest, type ExplainResult, type ProfileResult, type SqlRequest, type SqlResult } from './adapter.js';
9
+ import type { PgConnectionManager, PgQuery } from './postgresPool.js';
10
+ import type { WriteLanes } from './writeLanes.js';
11
+ /**
12
+ * Run a statement the user wrote.
13
+ *
14
+ * The session already carries `default_transaction_read_only = on`, and for
15
+ * everything else in this adapter that is enough, because every statement is
16
+ * one this file built. It is **not** enough here: `SET
17
+ * default_transaction_read_only = off` is itself a statement, and a user who
18
+ * typed it followed by a `DELETE` would get both.
19
+ *
20
+ * `BEGIN READ ONLY` is the version that holds, for one statement. Postgres
21
+ * refuses `SET TRANSACTION READ WRITE` once the transaction has taken its
22
+ * first snapshot, and one statement takes it before it runs. It does not hold
23
+ * against several: `COMMIT; BEGIN READ WRITE; DELETE …` ends the read-only
24
+ * transaction and opens a writable one. So the text goes on the extended
25
+ * protocol (`queryMode: 'extended'`), where Postgres itself refuses a second
26
+ * statement; refuseStacked is the earlier, clearer refusal, not the guard.
27
+ * (node-postgres sends a query with an empty `values` on the simple protocol,
28
+ * which runs every statement in the string.) The `ROLLBACK` afterwards also
29
+ * discards any session state the statement set, so one run cannot change what
30
+ * the next one means.
31
+ *
32
+ * The rollback runs in a `finally`: a statement that errors has still opened
33
+ * a transaction, and leaving it open would leave the connection in an aborted
34
+ * state where every later query fails with "current transaction is aborted".
35
+ *
36
+ * `write: true` is the other half, and it is a different request rather than
37
+ * a relaxation of this one: a separate handle, no READ ONLY transaction, and
38
+ * a decision made further up about whether this connection may write at all.
39
+ * The two paths share the statement text and nothing else.
40
+ */
41
+ export declare function runPostgresSql(connections: PgConnectionManager, writes: WriteLanes, request: SqlRequest): Promise<SqlResult>;
42
+ /**
43
+ * EXPLAIN, plain — never the analysing variant that executes to time.
44
+ *
45
+ * `runSql`'s bounding wrap is precisely wrong here: a statement made a
46
+ * derived table is a different statement, with a different plan. The text
47
+ * goes to the planner as written, inside the same READ ONLY transaction
48
+ * every user statement gets — so even a smuggled write is only ever
49
+ * planned, and an execution attempt is the transaction's to refuse, not a
50
+ * string check's.
51
+ */
52
+ export declare function explainPostgresSql(connections: PgConnectionManager, request: ExplainRequest): Promise<ExplainResult>;
53
+ /**
54
+ * The planner's own statistics, read rather than computed.
55
+ *
56
+ * `pg_stats` already holds the null share, the distinct estimate, the most
57
+ * common values with their frequencies, and the histogram — ANALYZE paid
58
+ * for them, reading them touches no user table. The numbers are
59
+ * sample-based and stale until the next ANALYZE, which is what
60
+ * `source: 'statistics'` tells the caller; a column ANALYZE has never
61
+ * visited simply has no numbers, which beats invented ones.
62
+ */
63
+ export declare function profilePostgresTable(table: string, schema: string, name: string, db: PgQuery): Promise<ProfileResult>;