@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.
- package/dist/adapters/postgres.d.ts +3 -50
- package/dist/adapters/postgres.js +36 -232
- package/dist/adapters/postgresSql.d.ts +63 -0
- package/dist/adapters/postgresSql.js +238 -0
- package/dist/adapters/postgresTransactionHandle.d.ts +13 -1
- package/dist/adapters/postgresTransactionHandle.js +36 -0
- package/dist/adapters/postgresWriteAhead.d.ts +4 -1
- package/dist/adapters/postgresWriteAhead.js +14 -6
- package/dist/server/clientHttp.d.ts +9 -0
- package/dist/server/clientHttp.js +9 -0
- package/dist/server/devclient.d.ts +18 -0
- package/dist/server/devclient.js +44 -0
- package/dist/shared/addressParams.d.ts +6 -0
- package/dist/shared/addressParams.js +17 -0
- package/dist/shared/appLinks.d.ts +15 -3
- package/dist/shared/appLinks.js +24 -7
- package/dist/shared/computedParse.js +4 -0
- package/dist/shared/listEmpty.d.ts +4 -1
- package/dist/shared/listEmpty.js +13 -4
- package/dist/shared/listPresentations.d.ts +2 -1
- package/dist/shared/model.d.ts +9 -0
- package/dist/shared/model.js +35 -3
- package/dist/shared/page.js +12 -2
- package/dist/shared/pageAnatomy.d.ts +2 -0
- package/dist/shared/pageAnatomy.js +20 -9
- package/dist/shared/pageConfig.js +14 -6
- package/dist/shared/pageModel.d.ts +2 -0
- package/package.json +1 -1
- package/schema/model.d.ts +3 -1
|
@@ -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,
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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>;
|