@bastani/atomic-storage-postgres 0.0.0-stage → 0.9.88

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/postgres.js ADDED
@@ -0,0 +1,1183 @@
1
+ // @ts-check
2
+ import { connect as connectSocket } from "node:net";
3
+ import { join } from "node:path";
4
+ import {
5
+ createSqliteDatabase,
6
+ postgresDialect,
7
+ StorageAdapterLoadError,
8
+ StorageConfigError,
9
+ StorageError,
10
+ StorageUnavailableError,
11
+ } from "@bastani/atomic/storage";
12
+ import { createCloudPasswordProvider } from "./auth.js";
13
+ import { createPostgresListener } from "./listen.js";
14
+
15
+ /**
16
+ * @typedef {import("@bastani/atomic/storage").SqliteDriverResult} SqliteDriverResult
17
+ * @typedef {import("@bastani/atomic/storage").SqliteDriverTransientFailure} SqliteDriverTransientFailure
18
+ * @typedef {import("@bastani/atomic/storage").StorageFailureCause} StorageFailureCause
19
+ * @typedef {import("@bastani/atomic/storage").SqliteValue} SqliteValue
20
+ * @typedef {import("pg").PoolClient} PoolClient
21
+ * @typedef {"password" | "azure-entra" | "aws-iam" | "gcp-iam"} PostgresAuth
22
+ * @typedef {{
23
+ * url: string,
24
+ * password?: string | (() => Promise<string>),
25
+ * auth?: PostgresAuth,
26
+ * maxConnections?: number,
27
+ * statementTimeoutMs?: number,
28
+ * listenUrl?: string,
29
+ * schema?: string,
30
+ * sdkSearchPaths?: readonly string[],
31
+ * }} PostgresDatabaseOptions
32
+ */
33
+
34
+ /** Connections one database keeps open at most, per process. */
35
+ export const DEFAULT_MAX_CONNECTIONS = 8;
36
+ /** How long one statement may run on the server before it is cancelled, in milliseconds. */
37
+ export const DEFAULT_STATEMENT_TIMEOUT_MS = 30_000;
38
+ /** How long opening a connection, or waiting for a free one, may take. */
39
+ const CONNECT_TIMEOUT_MS = 10_000;
40
+ /** How long the listening connection stays idle before TCP keepalive probes start. */
41
+ const LISTEN_KEEPALIVE_IDLE_MS = 10_000;
42
+ /** An idle connection is closed after this long. */
43
+ const IDLE_TIMEOUT_MS = 10_000;
44
+ /**
45
+ * How much longer than the statement timeout a statement may take before the client gives up on its connection and
46
+ * asks the server to cancel it: the server cancels a statement itself at the statement timeout, so this bounds only a
47
+ * server or a network that stopped answering, and a statement that cannot run in a transaction block.
48
+ */
49
+ const CLIENT_TIMEOUT_GRACE_MS = 5_000;
50
+ /** The length and code of a protocol cancel request, which is sent on a connection of its own, without a startup. */
51
+ const CANCEL_REQUEST_LENGTH = 16;
52
+ const CANCEL_REQUEST_CODE = 80877102;
53
+ /** The advisory lock a serial transaction takes when it names no domain: the whole database's. */
54
+ const DATABASE_LOCK_SCOPE = "atomic";
55
+ /** The oldest server major version the adapter supports. */
56
+ const MINIMUM_SERVER_VERSION = 140000;
57
+ /**
58
+ * Node's codes for a server certificate that TLS verification refused: the same on every attempt, so never retried.
59
+ * @type {ReadonlySet<string>}
60
+ */
61
+ const TLS_VERIFICATION_CODES = new Set([
62
+ "ERR_TLS_CERT_ALTNAME_INVALID",
63
+ "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
64
+ "UNABLE_TO_GET_ISSUER_CERT",
65
+ "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
66
+ "SELF_SIGNED_CERT_IN_CHAIN",
67
+ "DEPTH_ZERO_SELF_SIGNED_CERT",
68
+ "CERT_HAS_EXPIRED",
69
+ "CERT_NOT_YET_VALID",
70
+ "CERT_UNTRUSTED",
71
+ "CERT_REJECTED",
72
+ "CERT_SIGNATURE_FAILURE",
73
+ "CERT_CHAIN_TOO_LONG",
74
+ "INVALID_CA",
75
+ "HOSTNAME_MISMATCH",
76
+ ]);
77
+
78
+ /**
79
+ * The permanent failure a connection refused by TLS verification is (#5218), with the reason and the fix: a host name
80
+ * the certificate names, or the CA in `sslrootcert`. Undefined for any other failure.
81
+ * @param {unknown} cause
82
+ * @returns {StorageError | undefined}
83
+ */
84
+ function tlsVerificationFailure(cause) {
85
+ /** @type {unknown} */
86
+ let current = cause;
87
+ for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof current === "object" && current !== null; depth++) {
88
+ const code = /** @type {{ code?: unknown }} */ (current).code;
89
+ if (typeof code === "string" && TLS_VERIFICATION_CODES.has(code)) {
90
+ const fix =
91
+ code === "ERR_TLS_CERT_ALTNAME_INVALID" || code === "HOSTNAME_MISMATCH"
92
+ ? "Connect by a host name the certificate names, or, for an address it does not name such as a private IP address, add sslmode=verify-ca with sslrootcert=<CA file> to the URL"
93
+ : "Add sslrootcert=<CA file> with the server's CA to the URL; see TLS in docs/storage.md";
94
+ return new StorageError(
95
+ `The server's TLS certificate was not accepted (${code}: ${/** @type {Error} */ (current).message}). ${fix}. It is not retried`,
96
+ { cause: /** @type {Error} */ (cause) },
97
+ );
98
+ }
99
+ current = /** @type {{ cause?: unknown }} */ (current).cause;
100
+ }
101
+ return undefined;
102
+ }
103
+
104
+ /** The SQLSTATEs of a refused password or token: `28P01`, and `28000`, which Azure sends for a malformed token. */
105
+ const REFUSED_TOKEN_SQLSTATES = new Set(["28P01", "28000"]);
106
+ /** The schema Atomic's tables, indexes, triggers and functions live in when the options name none (#5218). */
107
+ export const DEFAULT_SCHEMA = "atomic";
108
+ /**
109
+ * Where releases before #5218 created everything: the first schema of the default `search_path`. A database whose
110
+ * `public` holds Atomic's tables and that has no `atomic` schema yet keeps using it until `atomic storage migrate` moves
111
+ * them.
112
+ */
113
+ const LEGACY_SCHEMA = "public";
114
+ /** A table every release that used a database created in it: the migration ledger, the run journal, sessions, Intercom. */
115
+ const LEGACY_MARKERS = "(atomic_migrations|wf_runs|session_sessions|intercom_leases)$";
116
+ /**
117
+ * What the comment of each table `atomic storage migrate` leaves in `public` after moving the tables starts with (the
118
+ * coding agent's `postgres-schema.ts`): such a table fences an earlier release and holds nothing, so it never makes
119
+ * `public` the schema to use, as after the `atomic` schema was dropped to start over (#5218).
120
+ */
121
+ const MOVED_FENCE_COMMENT = "atomic-moved-fence:";
122
+ /** A schema name the adapter accepts: a lowercase identifier that needs no quotes. */
123
+ const SCHEMA_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
124
+
125
+ /**
126
+ * @param {string} field
127
+ * @param {string} reason
128
+ * @param {string} [hint]
129
+ */
130
+ function configError(field, reason, hint) {
131
+ return new StorageConfigError("sdk", field, reason, hint);
132
+ }
133
+
134
+ /**
135
+ * The failure of a statement the server refused for a missing privilege (SQLSTATE `42501`), as a configuration error
136
+ * that names the privilege and the fix (#5218): never retried, and never the server's bare message.
137
+ * @param {{ message: string }} cause
138
+ * @param {string} role
139
+ * @param {string} schema
140
+ * @param {string} database
141
+ * @param {string} [sql] The statement refused, when known.
142
+ */
143
+ function missingPrivilege(cause, role, schema, database, sql = "") {
144
+ const who = role === "" ? "This role" : `Role "${role}"`;
145
+ const denied = cause.message;
146
+ /** @type {string} */
147
+ let fix;
148
+ if (/must be owner of/.test(denied))
149
+ fix = `Changing Atomic's tables needs their owner: the schema is behind this version of Atomic. Run \`atomic storage migrate\` as the owner role (the role that owns schema ${schema}), then start again.`;
150
+ else if (/permission denied for database/.test(denied))
151
+ fix = `Creating schema ${schema} needs CREATE on the database: run \`atomic storage migrate\` as the owner role, or GRANT CREATE ON DATABASE ${database} TO <owner role>.`;
152
+ else if (/no schema has been selected/.test(denied))
153
+ fix = `The role cannot use schema ${schema}: grant it as the schema's owner, GRANT USAGE ON SCHEMA ${schema} TO "${role}"; with the table grants of a runtime role.`;
154
+ else if (/permission denied for schema/.test(denied) && /^\s*(CREATE|ALTER|DROP|COMMENT)\b/i.test(sql))
155
+ fix = `Creating or changing Atomic's tables in schema ${schema} needs the owner role: the schema is behind this version of Atomic. Run \`atomic storage migrate\` as the owner role, then start again.`;
156
+ else if (/permission denied for schema/.test(denied))
157
+ fix = `The role needs USAGE on schema ${schema}: GRANT USAGE ON SCHEMA ${schema} TO "${role}";`;
158
+ else if (/permission denied for (table|relation|sequence)/.test(denied))
159
+ fix = `A runtime role needs SELECT, INSERT, UPDATE and DELETE on every table in schema ${schema}: GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${schema} TO "${role}"; GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${schema} TO "${role}"; and ALTER DEFAULT PRIVILEGES as the owner for tables created later.`;
160
+ else if (/permission denied for function/.test(denied))
161
+ fix = `A runtime role needs EXECUTE on Atomic's trigger functions in schema ${schema}: GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA ${schema} TO "${role}";`;
162
+ else fix = `Grant the role the privilege, or run \`atomic storage migrate\` as the owner role.`;
163
+ return configError(
164
+ "privileges",
165
+ "missing-privilege",
166
+ `${who} lacks a privilege PostgreSQL requires: ${denied} (SQLSTATE ${/** @type {{ code?: string }} */ (cause).code ?? "42501"}). ${fix} See "Set up the database" in docs/storage.md`,
167
+ );
168
+ }
169
+
170
+ /** Whether `host` reaches this machine without a network: a socket directory, a loopback name or address. */
171
+ function isLocalHost(/** @type {string} */ host) {
172
+ const name = host.replace(/^\[|\]$/g, "").toLowerCase();
173
+ return (
174
+ name === "" ||
175
+ name.startsWith("/") ||
176
+ name === "localhost" ||
177
+ name === "::1" ||
178
+ /^127(?:\.\d{1,3}){3}$/.test(name)
179
+ );
180
+ }
181
+
182
+ /**
183
+ * The `sslmode` values libpq knows.
184
+ * @type {ReadonlySet<string>}
185
+ */
186
+ const SSL_MODES = new Set(["disable", "allow", "prefer", "require", "verify-ca", "verify-full"]);
187
+
188
+ /** Whether `name`, in lowercase, is a parameter that chooses or configures TLS. */
189
+ function isTlsParameter(/** @type {string} */ name) {
190
+ return name.startsWith("ssl") || name === "uselibpqcompat";
191
+ }
192
+
193
+ /**
194
+ * The URL pg connects with: a `postgres:` or `postgresql:` URL without a password, which gets `sslmode=verify-full`
195
+ * when it names none and its host is not this machine. A TLS parameter whose name is not lowercase, or an `sslmode`
196
+ * libpq does not know, is refused.
197
+ * @param {unknown} url
198
+ * @param {"url" | "listenUrl"} [field] The option that holds the URL, which a refusal names.
199
+ * @returns {string}
200
+ */
201
+ function connectionUrl(url, field = "url") {
202
+ /** @type {URL} */
203
+ let parsed;
204
+ try {
205
+ parsed = new URL(/** @type {string} */ (url));
206
+ } catch {
207
+ throw configError(field, "unsupported-url", "Use a postgres:// or postgresql:// URL");
208
+ }
209
+ if (parsed.protocol !== "postgres:" && parsed.protocol !== "postgresql:")
210
+ throw configError(field, "unsupported-url", "Use a postgres:// or postgresql:// URL");
211
+ const names = [...parsed.searchParams.keys()].map((name) => name.toLowerCase());
212
+ if (parsed.password !== "" || names.includes("password"))
213
+ throw configError(
214
+ field,
215
+ "credential-in-url",
216
+ "Remove the password from the URL and pass it through the storage secrets instead",
217
+ );
218
+ // pg reads parameter names exactly as written, as libpq does: `SSLMODE=verify-full` would be ignored, and the
219
+ // connection made without TLS.
220
+ for (const name of parsed.searchParams.keys())
221
+ if (name !== name.toLowerCase() && isTlsParameter(name.toLowerCase()))
222
+ throw configError("url", "tls-parameter-case", `Write the parameter ${name} in lowercase`);
223
+ const mode = parsed.searchParams.get("sslmode");
224
+ if (mode !== null && !SSL_MODES.has(mode))
225
+ throw configError("url", "unsupported-sslmode", `Use an sslmode of ${[...SSL_MODES].join(", ")}`);
226
+ if (mode !== null) return /** @type {string} */ (url);
227
+ const host = parsed.searchParams.get("host") ?? parsed.hostname;
228
+ if (isLocalHost(host)) return /** @type {string} */ (url);
229
+ parsed.searchParams.set("sslmode", "verify-full");
230
+ return parsed.href;
231
+ }
232
+
233
+ /**
234
+ * The `sslmode` values whose TLS options the adapter sets itself, as libpq reads them, rather than as pg does, which
235
+ * checks the host name for each of them: `verify-ca`, and `require` with an `sslrootcert`, check the certificate's CA
236
+ * but not its host name, and `prefer` and `allow` encrypt without checking the certificate (pg cannot fall back to an
237
+ * unencrypted connection, so neither does). `require` without an `sslrootcert` checks the certificate and its host
238
+ * name, as `verify-full` does: stricter than libpq, which checks neither.
239
+ * @type {ReadonlySet<string>}
240
+ */
241
+ const LIBPQ_SSL_MODES = new Set(["allow", "prefer", "require", "verify-ca"]);
242
+
243
+ /**
244
+ * The client configuration of `url`, with the TLS options its `sslmode` asks for. A URL with `uselibpqcompat` is left
245
+ * to pg, which reads `sslmode` as libpq does then.
246
+ * @param {typeof import("pg-connection-string").parseIntoClientConfig} parseUrl
247
+ * @param {string} url
248
+ */
249
+ function clientConfig(parseUrl, url) {
250
+ const parsed = new URL(url);
251
+ const mode = parsed.searchParams.get("sslmode");
252
+ if (mode === null || !LIBPQ_SSL_MODES.has(mode) || parsed.searchParams.has("uselibpqcompat")) return parseUrl(url);
253
+ // Parsed as verify-full, the TLS options pg builds for every mode here, without pg's warning that it checks them all.
254
+ parsed.searchParams.set("sslmode", "verify-full");
255
+ const connection = parseUrl(parsed.href);
256
+ const ssl = /** @type {import("node:tls").ConnectionOptions} */ (connection.ssl);
257
+ if (mode === "verify-ca" || (mode === "require" && parsed.searchParams.has("sslrootcert")))
258
+ ssl.checkServerIdentity = () => undefined;
259
+ else if (mode !== "require") ssl.rejectUnauthorized = false;
260
+ return connection;
261
+ }
262
+
263
+ /**
264
+ * @param {string} field
265
+ * @param {unknown} value
266
+ * @param {number} fallback
267
+ */
268
+ function positiveInteger(field, value, fallback) {
269
+ if (value === undefined) return fallback;
270
+ if (typeof value !== "number" || !Number.isInteger(value) || value <= 0)
271
+ throw configError(field, "positive-integer-required");
272
+ return value;
273
+ }
274
+
275
+ /**
276
+ * Whether `character` can continue an identifier, so a `$` or `'` after it does not start a literal. Like Postgres's
277
+ * lexer, any non-ASCII character counts; each UTF-16 code unit of one is at least U+0080.
278
+ */
279
+ function isWordCharacter(/** @type {string | undefined} */ character) {
280
+ return character !== undefined && /[A-Za-z0-9_$\u0080-\uffff]/.test(character);
281
+ }
282
+
283
+ /**
284
+ * `sql` with each positional `?` parameter replaced by `$1`, `$2`, ... in order. A `?` inside a string literal, a quoted
285
+ * identifier, a dollar-quoted string or a comment is text, not a parameter.
286
+ * @param {string} sql
287
+ */
288
+ export function numberPlaceholders(sql) {
289
+ if (!sql.includes("?")) return sql;
290
+ let numbered = "";
291
+ let copied = 0;
292
+ let count = 0;
293
+ let index = 0;
294
+ while (index < sql.length) {
295
+ const character = sql[index];
296
+ if (character === "?") {
297
+ // After an identifier character `$1` would continue the identifier, so a space keeps the parameter apart.
298
+ const separator = isWordCharacter(sql[index - 1]) ? " " : "";
299
+ numbered += `${sql.slice(copied, index)}${separator}$${++count}`;
300
+ copied = ++index;
301
+ } else if (character === "'") {
302
+ const escapes = /[eE]/.test(sql[index - 1] ?? "") && !isWordCharacter(sql[index - 2]);
303
+ index++;
304
+ // A doubled quote is a quote inside the same string, which keeps its backslash escapes.
305
+ while (index < sql.length) {
306
+ if (escapes && sql[index] === "\\") index += 2;
307
+ else if (sql[index] !== "'") index++;
308
+ else if (sql[index + 1] === "'") index += 2;
309
+ else break;
310
+ }
311
+ index++;
312
+ } else if (character === '"') {
313
+ index = sql.indexOf('"', index + 1);
314
+ index = index === -1 ? sql.length : index + 1;
315
+ } else if (character === "-" && sql[index + 1] === "-") {
316
+ index = sql.indexOf("\n", index);
317
+ if (index === -1) index = sql.length;
318
+ } else if (character === "/" && sql[index + 1] === "*") {
319
+ let depth = 1;
320
+ index += 2;
321
+ while (index < sql.length && depth > 0) {
322
+ if (sql.startsWith("/*", index)) {
323
+ depth++;
324
+ index += 2;
325
+ } else if (sql.startsWith("*/", index)) {
326
+ depth--;
327
+ index += 2;
328
+ } else index++;
329
+ }
330
+ } else if (character === "$" && !isWordCharacter(sql[index - 1])) {
331
+ // A tag starts with an ASCII letter, `_` or any non-ASCII character, and may continue with digits too.
332
+ const tag = /^\$(?:[A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/.exec(sql.slice(index))?.[0];
333
+ if (tag === undefined) index++;
334
+ else {
335
+ const end = sql.indexOf(tag, index + tag.length);
336
+ index = end === -1 ? sql.length : end + tag.length;
337
+ }
338
+ } else index++;
339
+ }
340
+ return numbered + sql.slice(copied);
341
+ }
342
+
343
+ /** The longest identifier Postgres keeps whole; it truncates a longer one. */
344
+ const IDENTIFIER_BYTES = 63;
345
+
346
+ /**
347
+ * `sql` with every unquoted identifier longer than Postgres keeps whole replaced by the name the storage dialect gives
348
+ * it (`postgresDialect.identifier`: its head and a hash of the whole name), in every statement, DDL and DML alike, and
349
+ * in the bodies of functions and `DO` blocks. Created objects, the statements that use them, and the dialect's catalog
350
+ * probes then always name one object by one identifier, whatever prefix a store was given, rather than Postgres
351
+ * truncating each occurrence on its own. Values are never changed: string literals, every other dollar-quoted string,
352
+ * quoted identifiers and comments (nested as Postgres nests them) are left as written.
353
+ * @param {string} sql
354
+ */
355
+ export function physicalIdentifiers(sql) {
356
+ if (!/[A-Za-z0-9_$]{64}/.test(sql)) return sql;
357
+ let mapped = "";
358
+ let copied = 0;
359
+ let index = 0;
360
+ // Where the current statement starts, after the last `;` outside quotes and comments.
361
+ let statement = 0;
362
+ while (index < sql.length) {
363
+ const character = /** @type {string} */ (sql[index]);
364
+ if (/[A-Za-z_]/.test(character) && !isWordCharacter(sql[index - 1])) {
365
+ let end = index + 1;
366
+ while (end < sql.length && isWordCharacter(sql[end])) end++;
367
+ const word = sql.slice(index, end);
368
+ if (word.length > IDENTIFIER_BYTES && /^[A-Za-z0-9_]+$/.test(word)) {
369
+ mapped += `${sql.slice(copied, index)}${postgresDialect.identifier(word)}`;
370
+ copied = end;
371
+ }
372
+ index = end;
373
+ } else if (character === "'") {
374
+ const escapes = /[eE]/.test(sql[index - 1] ?? "") && !isWordCharacter(sql[index - 2]);
375
+ index++;
376
+ while (index < sql.length) {
377
+ if (escapes && sql[index] === "\\") index += 2;
378
+ else if (sql[index] !== "'") index++;
379
+ else if (sql[index + 1] === "'") index += 2;
380
+ else break;
381
+ }
382
+ index++;
383
+ } else if (character === '"') {
384
+ index = sql.indexOf('"', index + 1);
385
+ index = index === -1 ? sql.length : index + 1;
386
+ } else if (character === "-" && sql[index + 1] === "-") {
387
+ index = sql.indexOf("\n", index);
388
+ if (index === -1) index = sql.length;
389
+ } else if (character === "/" && sql[index + 1] === "*") {
390
+ index = blockCommentEnd(sql, index);
391
+ } else if (character === "$" && !isWordCharacter(sql[index - 1])) {
392
+ const tag = /^\$(?:[A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/.exec(sql.slice(index))?.[0];
393
+ if (tag === undefined) index++;
394
+ else {
395
+ const start = index + tag.length;
396
+ const close = sql.indexOf(tag, start);
397
+ const end = close === -1 ? sql.length : close;
398
+ // A function's or `DO` block's body is SQL: its identifiers are mapped, its literals kept. Any other
399
+ // dollar-quoted string is a value, kept as written.
400
+ if (isRoutineBody(sql.slice(statement, index))) {
401
+ mapped += `${sql.slice(copied, start)}${physicalIdentifiers(sql.slice(start, end))}`;
402
+ copied = end;
403
+ }
404
+ index = close === -1 ? sql.length : close + tag.length;
405
+ }
406
+ } else {
407
+ if (character === ";") statement = index + 1;
408
+ index++;
409
+ }
410
+ }
411
+ return mapped + sql.slice(copied);
412
+ }
413
+
414
+ /** The index after the block comment that opens at `index`, which nests as Postgres nests comments. */
415
+ function blockCommentEnd(/** @type {string} */ sql, /** @type {number} */ index) {
416
+ let depth = 1;
417
+ let at = index + 2;
418
+ while (at < sql.length && depth > 0) {
419
+ if (sql.startsWith("/*", at)) {
420
+ depth++;
421
+ at += 2;
422
+ } else if (sql.startsWith("*/", at)) {
423
+ depth--;
424
+ at += 2;
425
+ } else at++;
426
+ }
427
+ return at;
428
+ }
429
+
430
+ /**
431
+ * Whether a dollar-quoted string after `before`, the text of its statement up to it, is the body of a routine: the
432
+ * string after `AS` in `CREATE [OR REPLACE] FUNCTION|PROCEDURE`, or after `DO [LANGUAGE …]`.
433
+ * @param {string} before
434
+ */
435
+ function isRoutineBody(before) {
436
+ let text = "";
437
+ for (let at = 0; at < before.length; ) {
438
+ if (before.startsWith("/*", at)) {
439
+ at = blockCommentEnd(before, at);
440
+ text += " ";
441
+ } else if (before.startsWith("--", at)) {
442
+ const end = before.indexOf("\n", at);
443
+ at = end === -1 ? before.length : end;
444
+ text += " ";
445
+ } else text += before[at++];
446
+ }
447
+ if (/^\s*DO(?:\s+LANGUAGE\s+\w+)?\s*$/i.test(text)) return true;
448
+ return /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE)\b[\s\S]*\bAS\s*$/i.test(text);
449
+ }
450
+
451
+ /** Whether `sql` is a single SQLite `PRAGMA` statement, which Postgres has no use for. */
452
+ function isPragma(/** @type {string} */ sql) {
453
+ return /^\s*PRAGMA\b[^;]*;?\s*$/i.test(sql);
454
+ }
455
+
456
+ const INT8 = 20;
457
+ const INT2 = 21;
458
+ const INT4 = 23;
459
+ const OID = 26;
460
+ const FLOAT4 = 700;
461
+ const FLOAT8 = 701;
462
+ const NUMERIC = 1700;
463
+ const BOOL = 16;
464
+ const BYTEA = 17;
465
+
466
+ /**
467
+ * Turns each column's text into a SQLite value: integers as numbers or `bigint`s (the facade turns safe ones into
468
+ * numbers), a whole `NUMERIC` (such as a `SUM` of `BIGINT`s, or `2.00`) as an integer, booleans as 1 or 0, `BYTEA` as bytes,
469
+ * and everything else, JSON and timestamps included, as its text.
470
+ * @param {typeof import("pg").types} pgTypes
471
+ */
472
+ function sqliteTypes(pgTypes) {
473
+ const bytea = pgTypes.getTypeParser(BYTEA, "text");
474
+ /** @type {(text: string) => string} */
475
+ const asText = (text) => text;
476
+ return {
477
+ /** @param {number} oid */
478
+ getTypeParser(oid) {
479
+ switch (oid) {
480
+ case INT8:
481
+ return (/** @type {string} */ text) => BigInt(text);
482
+ case INT2:
483
+ case INT4:
484
+ case OID:
485
+ case FLOAT4:
486
+ case FLOAT8:
487
+ return Number;
488
+ case NUMERIC:
489
+ return (/** @type {string} */ text) => {
490
+ const whole = /^(-?\d+)(?:\.0*)?$/.exec(text);
491
+ return whole === null ? Number(text) : BigInt(/** @type {string} */ (whole[1]));
492
+ };
493
+ case BOOL:
494
+ return (/** @type {string} */ text) => (text === "t" ? 1 : 0);
495
+ case BYTEA:
496
+ return bytea;
497
+ default:
498
+ return asText;
499
+ }
500
+ },
501
+ };
502
+ }
503
+
504
+ /**
505
+ * Why a driver call failed before or while it talked to the server, when the server did not say: `"connect"`, no
506
+ * connection could be had, so nothing was sent; `"lost"`, the connection broke or stopped answering during the call.
507
+ */
508
+ class PostgresConnectionFailure extends StorageError {
509
+ /**
510
+ * @param {"connect" | "lost"} phase
511
+ * @param {StorageFailureCause} cause
512
+ */
513
+ constructor(phase, cause) {
514
+ super(cause instanceof Error ? cause.message : String(cause), { cause });
515
+ this.phase = phase;
516
+ }
517
+ }
518
+
519
+ /** How far `transientFailure` follows `cause`. */
520
+ const MAX_CAUSE_DEPTH = 8;
521
+
522
+ /**
523
+ * SQLSTATEs of a failure that passes, with what it says of the request.
524
+ * @type {ReadonlyMap<string, SqliteDriverTransientFailure>}
525
+ */
526
+ const TRANSIENT_SQLSTATES = new Map([
527
+ // serialization_failure, deadlock_detected, lock_not_available: the server rolled the statement back.
528
+ ["40001", { code: "lock-conflict", outcome: "not-applied" }],
529
+ ["40P01", { code: "lock-conflict", outcome: "not-applied" }],
530
+ ["55P03", { code: "lock-conflict", outcome: "not-applied" }],
531
+ // query_canceled (statement_timeout) and idle_in_transaction_session_timeout: rolled back.
532
+ ["57014", { code: "transaction-timeout", outcome: "not-applied" }],
533
+ ["25P03", { code: "transaction-timeout", outcome: "not-applied" }],
534
+ // too_many_connections, cannot_connect_now (starting up or in recovery): no connection, nothing sent.
535
+ ["53300", { code: "connection-refused", outcome: "not-applied" }],
536
+ ["57P03", { code: "connection-refused", outcome: "not-applied" }],
537
+ ["08001", { code: "connection-refused", outcome: "not-applied" }],
538
+ ["08004", { code: "connection-refused", outcome: "not-applied" }],
539
+ // admin_shutdown, crash_shutdown, connection_exception, connection_does_not_exist, connection_failure: the
540
+ // connection ended while a request may have been applied.
541
+ ["57P01", { code: "connection-lost", outcome: "unknown" }],
542
+ ["57P02", { code: "connection-lost", outcome: "unknown" }],
543
+ ["08000", { code: "connection-lost", outcome: "unknown" }],
544
+ ["08003", { code: "connection-lost", outcome: "unknown" }],
545
+ ["08006", { code: "connection-lost", outcome: "unknown" }],
546
+ ]);
547
+
548
+ /**
549
+ * The failure, as one that passes, read from the server's SQLSTATE when the server answered, else from whether a
550
+ * connection could be had or broke during the call; never from a message.
551
+ * @param {typeof import("pg").DatabaseError} DatabaseError
552
+ * @returns {(failure: StorageFailureCause) => SqliteDriverTransientFailure | undefined}
553
+ */
554
+ function transientFailureOf(DatabaseError) {
555
+ return (failure) => {
556
+ /** @type {PostgresConnectionFailure | undefined} */
557
+ let connection;
558
+ /** @type {unknown} */
559
+ let current = failure;
560
+ for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof current === "object" && current !== null; depth++) {
561
+ if (current instanceof DatabaseError) return TRANSIENT_SQLSTATES.get(current.code ?? "");
562
+ if (current instanceof PostgresConnectionFailure) connection ??= current;
563
+ else if (current instanceof StorageError) return undefined;
564
+ current = /** @type {{ readonly cause?: unknown }} */ (current).cause;
565
+ }
566
+ if (connection === undefined) return undefined;
567
+ return connection.phase === "connect"
568
+ ? { code: "connection-refused", outcome: "not-applied" }
569
+ : { code: "connection-lost", outcome: "unknown" };
570
+ };
571
+ }
572
+
573
+ /**
574
+ * The advisory lock key of `scope`, as SQL.
575
+ * @param {string} scope
576
+ */
577
+ function lockKey(scope) {
578
+ return `hashtextextended(${literal(scope)}, 0)`;
579
+ }
580
+
581
+ /**
582
+ * Quotes `text` as a SQL string literal.
583
+ * @param {string} text
584
+ */
585
+ function literal(text) {
586
+ return `'${text.replaceAll("'", "''")}'`;
587
+ }
588
+
589
+ /**
590
+ * @param {PostgresDatabaseOptions} options
591
+ * @returns {Promise<import("@bastani/atomic/storage").SqliteDatabase>}
592
+ */
593
+ export async function openPostgresDatabase(options) {
594
+ const connectionString = connectionUrl(options.url);
595
+ const auth = options.auth ?? "password";
596
+ const cloud = auth === "azure-entra" || auth === "aws-iam" || auth === "gcp-iam" ? auth : undefined;
597
+ if (cloud === undefined && auth !== "password")
598
+ throw configError("auth", "unsupported-auth", 'Use "password", "azure-entra", "aws-iam" or "gcp-iam"');
599
+ if (cloud !== undefined && options.password !== undefined)
600
+ throw configError("auth", "conflicting-token", `Use either a password or ${cloud} auth, not both`);
601
+ const maxConnections = positiveInteger("maxConnections", options.maxConnections, DEFAULT_MAX_CONNECTIONS);
602
+ const statementTimeoutMs = positiveInteger(
603
+ "statementTimeoutMs",
604
+ options.statementTimeoutMs,
605
+ DEFAULT_STATEMENT_TIMEOUT_MS,
606
+ );
607
+ if (options.schema !== undefined && (typeof options.schema !== "string" || !SCHEMA_NAME.test(options.schema)))
608
+ throw configError("schema", "invalid-schema", "Use a lowercase identifier of letters, digits and _, such as atomic");
609
+ /**
610
+ * The schema every statement runs in, set with `SET LOCAL search_path` in each transaction so a transaction-mode
611
+ * pooler can serve it: the configured one, else `atomic`, or `public` for a database an earlier release set up there.
612
+ * Resolved when the database opens.
613
+ */
614
+ let schema = options.schema ?? DEFAULT_SCHEMA;
615
+ /** Whether `schema` exists; until it does, the first statement that creates something creates it first. */
616
+ let schemaReady = true;
617
+ /** Whether `schema` is `public` because an earlier release's tables were there when the database opened. */
618
+ let legacy = false;
619
+ /** @type {Promise<void> | undefined} */
620
+ let creatingSchema;
621
+ const searchPathSql = () => `SET LOCAL search_path TO "${schema}"`;
622
+ /** A lock or channel name of this schema's own: unchanged for `public`, so earlier releases there share them. */
623
+ const inSchema = (/** @type {string} */ name) => (schema === LEGACY_SCHEMA ? name : `${schema}:${name}`);
624
+
625
+ /** @type {Pick<typeof import("pg"), "Pool" | "Client" | "DatabaseError" | "types">} */
626
+ let pg;
627
+ /** @type {typeof import("pg-connection-string").parseIntoClientConfig} */
628
+ let parseUrl;
629
+ try {
630
+ pg = (await import("pg")).default;
631
+ ({ parseIntoClientConfig: parseUrl } = await import("pg-connection-string"));
632
+ } catch (cause) {
633
+ throw new StorageAdapterLoadError("pg", /** @type {StorageFailureCause} */ (cause));
634
+ }
635
+
636
+ // The URL is parsed here rather than passed as `connectionString`, whose empty password would replace `password`.
637
+ /** @param {string} url */
638
+ const parseConnection = (url) => {
639
+ const parsed = clientConfig(parseUrl, url);
640
+ delete parsed.password;
641
+ return parsed;
642
+ };
643
+ const connection = parseConnection(connectionString);
644
+ // Notifications reach only a session of their own: through a transaction pooler `listenUrl` names a direct endpoint.
645
+ const listenConnection =
646
+ options.listenUrl === undefined ? connection : parseConnection(connectionUrl(options.listenUrl, "listenUrl"));
647
+
648
+ /** The cloud token providers of the pool's and the listening connection's hosts. */
649
+ /** @type {Set<{ invalidate(): void }>} */
650
+ const tokenProviders = new Set();
651
+ /** Every password the pool was given, so the redactor can remove them from failures. */
652
+ const passwords = new Set(typeof options.password === "string" ? [options.password] : []);
653
+ /**
654
+ * The password function for connections to `target`: cloud IAM tokens are issued per host.
655
+ * @param {typeof connection} target
656
+ * @returns {(() => Promise<string>) | undefined}
657
+ */
658
+ const passwordFor = (target) => {
659
+ const provider =
660
+ cloud === undefined
661
+ ? undefined
662
+ : createCloudPasswordProvider({
663
+ auth: cloud,
664
+ host: target.host ?? "",
665
+ port: target.port ?? 5432,
666
+ user: target.user ?? "",
667
+ ...(options.sdkSearchPaths === undefined ? {} : { searchPaths: options.sdkSearchPaths }),
668
+ });
669
+ if (provider !== undefined) tokenProviders.add(provider);
670
+ const source = provider ?? options.password;
671
+ return source === undefined
672
+ ? undefined
673
+ : async () => {
674
+ const value = typeof source === "string" ? source : await source();
675
+ if (typeof value !== "string" || value === "")
676
+ throw configError("password", "empty-token", "The password source gave an empty password");
677
+ passwords.add(value);
678
+ return value;
679
+ };
680
+ };
681
+ const password = passwordFor(connection);
682
+
683
+ // pg leaves the socket of a connection that failed to start open, for instance when the password source failed while
684
+ // the server waited for the password; the server keeps that half-started backend until its authentication timeout,
685
+ // and meanwhile it holds up statements that wait for every backend, such as `DROP DATABASE`.
686
+ class ClosingClient extends pg.Client {
687
+ /** @param {(error: Error | undefined) => void} callback */
688
+ // @ts-expect-error pg-pool always passes a callback, so the promise form is left out.
689
+ connect(callback) {
690
+ super.connect((/** @type {Error | undefined} */ error) => {
691
+ if (error) this.connection.stream.destroy();
692
+ callback(error);
693
+ });
694
+ }
695
+ }
696
+ const pool = new pg.Pool({
697
+ Client: /** @type {typeof pg.Client} */ (/** @type {unknown} */ (ClosingClient)),
698
+ ...connection,
699
+ ...(password === undefined ? {} : { password }),
700
+ max: maxConnections,
701
+ connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
702
+ idleTimeoutMillis: IDLE_TIMEOUT_MS,
703
+ keepAlive: true,
704
+ // Queries are written without waiting for the answer to the one before, so a statement outside a transaction
705
+ // sends its `BEGIN` and `COMMIT` in the same round trip; each query still ends with its own sync.
706
+ pipeline: true,
707
+ application_name: "atomic",
708
+ types: sqliteTypes(pg.types),
709
+ });
710
+ /** Connections that broke: they are closed, never returned to the pool. */
711
+ const lost = new WeakSet();
712
+ // An idle connection that breaks emits `error` on the pool, which would end the process unheard.
713
+ pool.on("error", (_error, client) => lost.add(client));
714
+ pool.on("connect", (client) => client.on("error", () => lost.add(client)));
715
+
716
+ /** @returns {Promise<PoolClient>} */
717
+ const connect = async () => {
718
+ try {
719
+ return await pool.connect();
720
+ } catch (cause) {
721
+ // A cloud token the server refused (28P01, or Azure's 28000 for a malformed one) is dropped, and a fresh one
722
+ // tried once: a clock that runs behind can reuse a cached token past its expiry (#5218).
723
+ if (tokenProviders.size > 0 && cause instanceof pg.DatabaseError && REFUSED_TOKEN_SQLSTATES.has(cause.code ?? "")) {
724
+ for (const provider of tokenProviders) provider.invalidate();
725
+ try {
726
+ return await pool.connect();
727
+ } catch (retried) {
728
+ throw new PostgresConnectionFailure("connect", /** @type {StorageFailureCause} */ (retried));
729
+ }
730
+ }
731
+ const tls = tlsVerificationFailure(cause);
732
+ if (tls !== undefined) throw tls;
733
+ throw new PostgresConnectionFailure("connect", /** @type {StorageFailureCause} */ (cause));
734
+ }
735
+ };
736
+
737
+ /**
738
+ * Asks the server, on a connection of its own, to cancel the statement `client` runs, so a statement the client gave
739
+ * up on stops rather than runs on. Resolves once the server, or a pooler that passes the request on, closed that
740
+ * connection, or after `CLIENT_TIMEOUT_GRACE_MS` when it does not.
741
+ * @param {PoolClient} client
742
+ * @returns {Promise<void>}
743
+ */
744
+ const cancel = (client) => {
745
+ const { processID, secretKey } = /** @type {PoolClient & { processID: number, secretKey: number }} */ (client);
746
+ const request = Buffer.alloc(CANCEL_REQUEST_LENGTH);
747
+ request.writeInt32BE(CANCEL_REQUEST_LENGTH, 0);
748
+ request.writeInt32BE(CANCEL_REQUEST_CODE, 4);
749
+ request.writeInt32BE(processID, 8);
750
+ request.writeInt32BE(secretKey, 12);
751
+ const host = connection.host ?? "localhost";
752
+ const port = connection.port ?? 5432;
753
+ const socket = host.startsWith("/") ? connectSocket(`${host}/.s.PGSQL.${port}`) : connectSocket(port, host);
754
+ socket.setTimeout(CLIENT_TIMEOUT_GRACE_MS, () => socket.destroy());
755
+ socket.on("error", () => socket.destroy());
756
+ socket.end(request);
757
+ return new Promise((resolve) => socket.once("close", () => resolve()));
758
+ };
759
+
760
+ /**
761
+ * Runs `query` on `client`. When it has not finished after `timeoutMs`, the server is asked to cancel it, and the
762
+ * connection is closed, after the request because a pooler forgets the connection's cancel key once it closes; the
763
+ * call then fails as a lost connection, whatever the server answers late. A failure that was not the server's
764
+ * answer, once the connection broke, is reported as a lost connection too.
765
+ * @template T
766
+ * @param {PoolClient} client
767
+ * @param {() => Promise<T>} query
768
+ * @param {number} timeoutMs
769
+ * @param {string} [sql] The statement, which a missing privilege's message reads to name the fix.
770
+ * @returns {Promise<T>}
771
+ */
772
+ const watched = async (client, query, timeoutMs, sql = "") => {
773
+ let expired = false;
774
+ const timer = setTimeout(() => {
775
+ expired = true;
776
+ lost.add(client);
777
+ void cancel(client).then(() => client.connection.stream.destroy());
778
+ }, timeoutMs);
779
+ try {
780
+ return await query();
781
+ } catch (cause) {
782
+ if (expired)
783
+ throw new PostgresConnectionFailure("lost", new Error(`The server did not answer within ${timeoutMs} ms`));
784
+ // The server ends the connection after a FATAL error, and pg reports the end only later.
785
+ if (cause instanceof pg.DatabaseError && (cause.severity === "FATAL" || cause.severity === "PANIC"))
786
+ lost.add(client);
787
+ if (!(cause instanceof pg.DatabaseError) && lost.has(client))
788
+ throw new PostgresConnectionFailure("lost", /** @type {StorageFailureCause} */ (cause));
789
+ if (cause instanceof pg.DatabaseError && (cause.code === "42501" || cause.code === "3F000"))
790
+ throw Object.defineProperty(
791
+ missingPrivilege(cause, connection.user ?? "", schema, connection.database ?? "", sql),
792
+ "cause",
793
+ { value: cause, configurable: true },
794
+ );
795
+ throw cause;
796
+ } finally {
797
+ clearTimeout(timer);
798
+ }
799
+ };
800
+
801
+ /**
802
+ * @param {PoolClient} client
803
+ * @param {string} sql
804
+ * @param {readonly SqliteValue[]} params
805
+ */
806
+ const statement = (client, sql, params) =>
807
+ client.query({ text: numberPlaceholders(physicalIdentifiers(sql)), values: [...params], rowMode: "array" });
808
+
809
+ /**
810
+ * Creates `schema` when it does not exist yet and `sql` creates something, before `sql` runs: on a connection of its
811
+ * own, which commits at once, so the transaction `sql` runs in finds it. Opening a database, `atomic storage status`
812
+ * and `atomic storage join` create nothing; the first store that sets up its tables creates the schema too, under an
813
+ * advisory lock, so hosts that start together on a new database create it once.
814
+ * A database resolved to `public` because an earlier release's tables were there is checked again before each
815
+ * statement that creates something: once `atomic storage migrate` has moved them, this process must not create
816
+ * Atomic's tables in `public` again, apart from the moved ones (#5218).
817
+ * @param {PoolClient} client
818
+ * @param {string} sql
819
+ */
820
+ const schemaFor = async (client, sql) => {
821
+ if (!/(?:^|;)\s*CREATE\s/i.test(sql)) return;
822
+ // A statement that names `public` itself, as `atomic storage migrate` does for the fences it leaves there, or
823
+ // that creates a schema, is meant for where it says.
824
+ if (legacy && !/\bpublic\./i.test(sql) && !/^\s*CREATE\s+SCHEMA\b/i.test(sql)) {
825
+ const moved = await watched(
826
+ client,
827
+ () =>
828
+ client.query(
829
+ "SELECT count(*)::int AS ledgers FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relkind = 'r' AND c.relname ~ 'atomic_migrations$'",
830
+ [DEFAULT_SCHEMA],
831
+ ),
832
+ clientTimeoutMs,
833
+ );
834
+ if (Number(moved.rows[0]?.ledgers) > 0)
835
+ throw new StorageError(
836
+ `This database was upgraded since this process started: \`atomic storage migrate\` moved Atomic's tables from schema public to schema ${DEFAULT_SCHEMA}. Restart this process (#5218)`,
837
+ );
838
+ }
839
+ if (schemaReady) return;
840
+ creatingSchema ??= (async () => {
841
+ const client = new ClosingClient({
842
+ ...connection,
843
+ ...(password === undefined ? {} : { password }),
844
+ connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
845
+ application_name: "atomic",
846
+ });
847
+ client.on("error", () => {});
848
+ try {
849
+ await new Promise((resolve, reject) =>
850
+ client.connect((/** @type {Error | undefined} */ error) => (error ? reject(error) : resolve(undefined))),
851
+ );
852
+ } catch (cause) {
853
+ throw new PostgresConnectionFailure("connect", /** @type {StorageFailureCause} */ (cause));
854
+ }
855
+ try {
856
+ await watched(
857
+ /** @type {PoolClient} */ (/** @type {unknown} */ (client)),
858
+ () =>
859
+ client.query(
860
+ `BEGIN; ${setTimeoutSql}; SELECT pg_advisory_xact_lock(${lockKey(`schema:${schema}`)}); CREATE SCHEMA IF NOT EXISTS "${schema}"; COMMIT`,
861
+ ),
862
+ clientTimeoutMs,
863
+ );
864
+ schemaReady = true;
865
+ } finally {
866
+ await client.end().catch(() => {});
867
+ }
868
+ })().finally(() => {
869
+ creatingSchema = undefined;
870
+ });
871
+ await creatingSchema;
872
+ };
873
+
874
+ /**
875
+ * @param {import("pg").QueryResult<SqliteValue[]>} result
876
+ * @returns {SqliteDriverResult}
877
+ */
878
+ const driverResult = (result) => ({
879
+ columns: result.fields.map((field) => field.name),
880
+ rows: result.rows,
881
+ changes: result.rowCount ?? 0,
882
+ });
883
+
884
+ /**
885
+ * @param {PoolClient} client
886
+ * @param {string} sql
887
+ * @param {readonly SqliteValue[]} params
888
+ * @param {number} timeoutMs
889
+ * @returns {Promise<SqliteDriverResult>}
890
+ */
891
+ const execute = async (client, sql, params, timeoutMs) => {
892
+ await schemaFor(client, sql);
893
+ return driverResult(await watched(client, () => statement(client, sql, params), timeoutMs, sql));
894
+ };
895
+
896
+ /**
897
+ * @param {PoolClient} client
898
+ * @param {string} sql
899
+ * @param {number} timeoutMs
900
+ */
901
+ const executeMultiple = async (client, sql, timeoutMs) => {
902
+ if (isPragma(sql)) return;
903
+ await schemaFor(client, sql);
904
+ await watched(client, () => client.query(physicalIdentifiers(sql)), timeoutMs, sql);
905
+ };
906
+
907
+ /**
908
+ * Runs `body` on a pooled connection outside a transaction, and returns the connection, or closes it when it broke.
909
+ * @template T
910
+ * @param {(client: PoolClient) => Promise<T>} body
911
+ */
912
+ const autocommit = async (body) => {
913
+ const client = await connect();
914
+ try {
915
+ return await body(client);
916
+ } finally {
917
+ client.release(lost.has(client));
918
+ }
919
+ };
920
+ const clientTimeoutMs = statementTimeoutMs + CLIENT_TIMEOUT_GRACE_MS;
921
+ const setTimeoutSql = `SET LOCAL statement_timeout = ${statementTimeoutMs}`;
922
+
923
+ /**
924
+ * Runs `bounded`, which runs a statement in a transaction with the statement timeout, or, when the statement cannot
925
+ * run in a transaction block, `unbounded`, which runs it alone: the failed attempt rolled back without applying it.
926
+ * The timeout is set in a transaction rather than on the connection, so a transaction-mode pooler can serve it.
927
+ * @template T
928
+ * @param {() => Promise<T>} bounded
929
+ * @param {() => Promise<T>} unbounded
930
+ */
931
+ const withTimeout = async (bounded, unbounded) => {
932
+ try {
933
+ return await bounded();
934
+ } catch (error) {
935
+ // SQLSTATE active_sql_transaction: the statement, such as `VACUUM`, cannot run inside a transaction block.
936
+ if (!(error instanceof pg.DatabaseError) || error.code !== "25001") throw error;
937
+ return unbounded();
938
+ }
939
+ };
940
+
941
+ /**
942
+ * Runs `body`, a statement that cannot run in a transaction block, in the schema: the connection's `search_path` is
943
+ * set for it, and reset after.
944
+ * @template T
945
+ * @param {PoolClient} client
946
+ * @param {() => Promise<T>} body
947
+ */
948
+ const inSearchPath = async (client, body) => {
949
+ await watched(client, () => client.query(`SET search_path TO "${schema}"`), clientTimeoutMs);
950
+ try {
951
+ return await body();
952
+ } finally {
953
+ await watched(client, () => client.query("RESET search_path"), clientTimeoutMs).catch(() => lost.add(client));
954
+ }
955
+ };
956
+
957
+ /**
958
+ * Runs one statement on `client` in a transaction of its own, which the server cancels at the statement timeout. The
959
+ * pipelined connection writes the `BEGIN`, the statement and the `COMMIT` together, so this costs one round trip like
960
+ * the statement alone. A statement that fails aborts the transaction, which the `COMMIT` then rolls back.
961
+ * @param {PoolClient} client
962
+ * @param {string} sql
963
+ * @param {readonly SqliteValue[]} params
964
+ */
965
+ const executeAutocommit = (client, sql, params) =>
966
+ withTimeout(
967
+ async () => {
968
+ await schemaFor(client, sql);
969
+ const result = await watched(
970
+ client,
971
+ async () => {
972
+ // Every answer is awaited, so none is left to fail unheard; the first failure is the call's.
973
+ const answers = await Promise.allSettled([
974
+ client.query(`BEGIN; ${setTimeoutSql}; ${searchPathSql()}`),
975
+ statement(client, sql, params),
976
+ client.query("COMMIT"),
977
+ ]);
978
+ for (const answer of answers) if (answer.status === "rejected") throw answer.reason;
979
+ return /** @type {PromiseFulfilledResult<import("pg").QueryResult<SqliteValue[]>>} */ (answers[1]).value;
980
+ },
981
+ clientTimeoutMs,
982
+ sql,
983
+ );
984
+ return driverResult(result);
985
+ },
986
+ () => inSearchPath(client, () => execute(client, sql, params, clientTimeoutMs)),
987
+ );
988
+
989
+ /**
990
+ * Runs the statements of `sql` on `client`. Postgres runs several statements sent together in one transaction, which
991
+ * the timeout set first joins; the server cancels each statement at the statement timeout.
992
+ * @param {PoolClient} client
993
+ * @param {string} sql
994
+ */
995
+ const executeMultipleAutocommit = async (client, sql) => {
996
+ if (isPragma(sql)) return;
997
+ await withTimeout(
998
+ () => executeMultiple(client, `${setTimeoutSql}; ${searchPathSql()}; ${sql}`, clientTimeoutMs),
999
+ () => inSearchPath(client, () => executeMultiple(client, sql, clientTimeoutMs)),
1000
+ );
1001
+ };
1002
+
1003
+ const listenPassword = passwordFor(listenConnection);
1004
+ const listener = createPostgresListener({
1005
+ async connect() {
1006
+ const client = new ClosingClient({
1007
+ ...listenConnection,
1008
+ ...(listenPassword === undefined ? {} : { password: listenPassword }),
1009
+ connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
1010
+ // A short keepalive notices a peer that vanished without a reset sooner than the system's two hours; the
1011
+ // listener's own health probe catches the rest.
1012
+ keepAlive: true,
1013
+ keepAliveInitialDelayMillis: LISTEN_KEEPALIVE_IDLE_MS,
1014
+ application_name: "atomic-listen",
1015
+ });
1016
+ // An error before the listener attaches its own handler must not end the process unheard.
1017
+ client.on("error", () => {});
1018
+ await new Promise((resolve, reject) =>
1019
+ client.connect((/** @type {Error | undefined} */ error) => (error ? reject(error) : resolve(undefined))),
1020
+ );
1021
+ return client;
1022
+ },
1023
+ send: async (channel, payload) => {
1024
+ await autocommit((client) => client.query("SELECT pg_notify($1, $2)", [channel, payload]));
1025
+ },
1026
+ // Each schema's wake-ups are its own; `public` keeps the channels earlier releases listen on.
1027
+ channelName: (channel) =>
1028
+ postgresDialect.identifier(schema === LEGACY_SCHEMA ? channel : `${schema}_${channel}`),
1029
+ });
1030
+
1031
+ const database = createSqliteDatabase({
1032
+ descriptor: { adapter: "postgres", location: connectionString },
1033
+ redact: (text) => {
1034
+ let redacted = text;
1035
+ for (const secret of [...passwords].sort((first, second) => second.length - first.length))
1036
+ if (secret !== "") redacted = redacted.replaceAll(secret, "[redacted]");
1037
+ return redacted;
1038
+ },
1039
+ transientFailure: transientFailureOf(pg.DatabaseError),
1040
+ // Postgres's largest field is 1 GB less one byte (#4954).
1041
+ payloadLimits: { value: 1_073_741_823 },
1042
+ execute: (sql, params) => autocommit((client) => executeAutocommit(client, sql, params)),
1043
+ executeMultiple: (sql) => autocommit((client) => executeMultipleAutocommit(client, sql)),
1044
+ concurrentTransactions: true,
1045
+ // The connection is pipelined: a transaction's statements go out without waiting for the answers before them.
1046
+ pipelinedTransactions: true,
1047
+ dialect: postgresDialect,
1048
+ // The facade always says how the transaction excludes other writers.
1049
+ async beginTransaction(/** @type {import("@bastani/atomic/storage").SqliteDriverTransactionOptions} */ begin) {
1050
+ const { concurrency } = begin;
1051
+ const lockWaitMs = positiveInteger("lockWaitMs", begin.lockWaitMs, statementTimeoutMs);
1052
+ // A serial transaction takes its domain's advisory lock, which makes it the only writer of that domain as
1053
+ // `BEGIN IMMEDIATE` makes a SQLite transaction the only writer of its file; a fenced one locks its rows itself.
1054
+ // The locks nest: one without a domain holds the whole database's lock, and one with a domain holds that lock
1055
+ // shared, so it waits for and excludes whole-database transactions, but not those of other domains. The locks,
1056
+ // and every row lock after them, wait at most `lockWaitMs`; the statement timeout starts after them.
1057
+ const lock =
1058
+ concurrency.kind !== "serial"
1059
+ ? concurrency.excludesSerial === true
1060
+ ? `SELECT pg_advisory_xact_lock_shared(${lockKey(inSchema(DATABASE_LOCK_SCOPE))}); `
1061
+ : ""
1062
+ : concurrency.domain === undefined
1063
+ ? `SELECT pg_advisory_xact_lock(${lockKey(inSchema(DATABASE_LOCK_SCOPE))}); `
1064
+ : `SELECT pg_advisory_xact_lock_shared(${lockKey(inSchema(DATABASE_LOCK_SCOPE))}), pg_advisory_xact_lock(${lockKey(inSchema(concurrency.domain))}); `;
1065
+ const client = await connect();
1066
+ try {
1067
+ // One round trip, with nothing set outside the transaction, so a transaction-mode pooler can serve it.
1068
+ await watched(
1069
+ client,
1070
+ () =>
1071
+ client.query(
1072
+ `BEGIN; SET LOCAL lock_timeout = ${lockWaitMs}; ${lock}SET LOCAL statement_timeout = ${statementTimeoutMs}; ${searchPathSql()}`,
1073
+ ),
1074
+ lockWaitMs + clientTimeoutMs,
1075
+ );
1076
+ } catch (error) {
1077
+ // The transaction may be open, so the connection is closed rather than reused.
1078
+ client.release(true);
1079
+ throw error;
1080
+ }
1081
+ return {
1082
+ execute: (sql, params) => execute(client, sql, params, clientTimeoutMs),
1083
+ executeMultiple: (sql) => executeMultiple(client, sql, clientTimeoutMs),
1084
+ async commit() {
1085
+ const result = await watched(client, () => client.query("COMMIT"), clientTimeoutMs);
1086
+ // A transaction a failed statement aborted ends in a rollback when committed, without an error.
1087
+ if (result.command === "ROLLBACK")
1088
+ throw new StorageError("The transaction was rolled back because a statement in it failed");
1089
+ },
1090
+ async rollback() {
1091
+ // The server rolled back the transaction of a connection that broke.
1092
+ if (lost.has(client)) return;
1093
+ try {
1094
+ await watched(client, () => client.query("ROLLBACK"), clientTimeoutMs);
1095
+ } catch (error) {
1096
+ // The transaction may still be open, so the connection is closed rather than reused.
1097
+ lost.add(client);
1098
+ throw error;
1099
+ }
1100
+ },
1101
+ // The facade closes a transaction once, after its commit or rollback.
1102
+ close: () => client.release(lost.has(client)),
1103
+ };
1104
+ },
1105
+ notifications: listener,
1106
+ close: async () => {
1107
+ await listener.close();
1108
+ await pool.end();
1109
+ },
1110
+ });
1111
+ try {
1112
+ const row = await database.get("SELECT current_setting('server_version_num') AS version");
1113
+ const version = Number(row?.version);
1114
+ if (!(version >= MINIMUM_SERVER_VERSION))
1115
+ throw new StorageUnavailableError(
1116
+ database.descriptor,
1117
+ new StorageError(`PostgreSQL server version ${version} is older than 14`),
1118
+ "PostgreSQL 14 or newer is required",
1119
+ );
1120
+ // Which schema holds Atomic's tables, read without creating anything (#5218).
1121
+ const found = await database.get(
1122
+ `SELECT (SELECT count(*) FROM pg_catalog.pg_namespace WHERE nspname = ?) AS present,
1123
+ (SELECT count(*) FROM pg_catalog.pg_namespace WHERE nspname = ?) AS preferred,
1124
+ (SELECT count(*) FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
1125
+ WHERE n.nspname = ? AND c.relkind = 'r' AND c.relname ~ ?
1126
+ AND coalesce(obj_description(c.oid, 'pg_class'), '') NOT LIKE ?) AS legacy`,
1127
+ schema,
1128
+ DEFAULT_SCHEMA,
1129
+ LEGACY_SCHEMA,
1130
+ LEGACY_MARKERS,
1131
+ `${MOVED_FENCE_COMMENT}%`,
1132
+ );
1133
+ if (options.schema === undefined && Number(found?.preferred) === 0 && Number(found?.legacy) > 0)
1134
+ {
1135
+ schema = LEGACY_SCHEMA;
1136
+ legacy = true;
1137
+ }
1138
+ else schemaReady = Number(found?.present) > 0;
1139
+ return database;
1140
+ } catch (error) {
1141
+ await database
1142
+ .close()
1143
+ .catch((cleanupCause) =>
1144
+ Object.defineProperty(/** @type {Error} */ (error), "cleanupCause", { value: cleanupCause, configurable: true }),
1145
+ );
1146
+ throw error;
1147
+ }
1148
+ }
1149
+
1150
+ /** @satisfies {import("@bastani/atomic/storage").StorageAdapterModule} */
1151
+ const adapter = {
1152
+ atomicStorageAdapter: 1,
1153
+ liveSecrets: /** @type {readonly string[]} */ (["password"]),
1154
+ /**
1155
+ * @param {import("@bastani/atomic/storage").AdapterOptions} options
1156
+ * @param {import("@bastani/atomic/storage").StorageOpenContext} context
1157
+ */
1158
+ openDatabase(options, context) {
1159
+ if (typeof options.url !== "string" || options.url === "")
1160
+ return Promise.reject(configError("url", "unsupported-url", "Use a postgres:// or postgresql:// URL"));
1161
+ const { secret } = context;
1162
+ // Cloud IAM auth issues its own password; a selection carries no password secret for it.
1163
+ const cloud = typeof options.auth === "string" && options.auth !== "password";
1164
+ return openPostgresDatabase({
1165
+ url: options.url,
1166
+ ...(cloud
1167
+ ? {}
1168
+ : secret !== undefined
1169
+ ? { password: () => secret("password") }
1170
+ : typeof options.password === "string"
1171
+ ? { password: options.password }
1172
+ : {}),
1173
+ ...(typeof options.auth === "string" ? { auth: /** @type {PostgresAuth} */ (options.auth) } : {}),
1174
+ ...(typeof options.maxConnections === "number" ? { maxConnections: options.maxConnections } : {}),
1175
+ ...(typeof options.statementTimeoutMs === "number" ? { statementTimeoutMs: options.statementTimeoutMs } : {}),
1176
+ ...(typeof options.listenUrl === "string" ? { listenUrl: options.listenUrl } : {}),
1177
+ ...(options.schema === undefined ? {} : { schema: /** @type {string} */ (options.schema) }),
1178
+ // A cloud SDK `atomic install` put in the user packages, for an adapter installed from a local path (#5218).
1179
+ ...(cloud ? { sdkSearchPaths: [join(context.agentDir, "npm")] } : {}),
1180
+ });
1181
+ },
1182
+ };
1183
+ export default adapter;