@n8io/baseline-postgres 5.4.0 → 5.5.0
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/README.md +23 -23
- package/dist/index.d.ts +27 -6
- package/dist/index.js +74 -46
- package/dist/testing.d.ts +2 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -74,29 +74,29 @@ Test a race with `postgresTestInterleave` from `@n8io/baseline-postgres/testing`
|
|
|
74
74
|
|
|
75
75
|
<details><summary><b>Exports</b></summary>
|
|
76
76
|
|
|
77
|
-
| Export | Does
|
|
78
|
-
| -------------------------------------------------------------------------------------------------- |
|
|
79
|
-
| `postgresPoolCreate({ databaseUrl, max?, connectTimeoutMs?, queryTimeoutMs?, vendor? })` | The process's one pool (10 connections, 3 s connect timeout). A query that takes longer than `queryTimeoutMs` (default 15 s, `null` for no limit) rejects with `Query read timeout`, so a server that stops answering cannot hold a request or a pool slot forever. The pool closes that connection; inside `postgresTransactionRun` it is closed once the rollback has been tried, which can take one more `queryTimeoutMs`. The timer runs in this process and sends no cancel: a server that is slow, not gone, may still finish the query, a write included, so treat the rejection as "unknown", not "did not happen". The limit is per query, inside a transaction too. An idle connection is probed after 10 s (TCP keep-alive). `vendor` takes pg's own pool settings, such as `ssl` or `idleTimeoutMillis`, and passes them through. The named options win: `vendor` throws on the keys they set, on `host`, `port`, `database`, `user` and `password` (pg lets the URL win, so put them in `databaseUrl`), and on `ssl` when the URL carries an `ssl*` parameter. It is outside the contract: nothing in it is tested here, and moving off pg deletes it.
|
|
80
|
-
| `PostgresPool`, `PostgresClient` | The pool and a checked-out connection. `await using` calls the pool's `end()` when its block ends. Name these in your own signatures, not `pg`'s types. They are pg's own pool and client, because Drizzle's `drizzle({ client })` needs the real ones.
|
|
81
|
-
| `postgresTransactionRun({ pgPool, work, timeoutMs? })` | Runs `work(pgClient)` in one transaction; COMMIT on `ok`, ROLLBACK on `err` or a throw. It ends after `timeoutMs` (default 5 s).
|
|
82
|
-
| `postgresMigrate({ databaseUrl, migrationsFolder, lockWaitMs?, vendor? })`
|
|
83
|
-
| `PostgresPoolOptions` | What `postgresPoolCreate` takes.
|
|
84
|
-
| `PostgresPoolVendorOptions` | The `vendor` option of `postgresPoolCreate`: pg's own pool settings, outside the contract.
|
|
85
|
-
| `PostgresMigrateOptions` | What `postgresMigrate` takes.
|
|
86
|
-
| `PostgresMigrateVendorOptions` | The `vendor` option of `postgresMigrate`: pg's settings for its one connection, outside the contract.
|
|
87
|
-
| `PostgresTransactionRunOptions` | What `postgresTransactionRun` takes.
|
|
88
|
-
| `PostgresKeysetKind` | How the sort column compares: `"text"`, `"date"`, `"integer"` or `"number"`.
|
|
89
|
-
| `PostgresKeysetOptions` | What `postgresKeysetCreate` takes.
|
|
90
|
-
| `PostgresUniqueViolation` | What `postgresUniqueViolationRead` returns: `{ constraint, columns, values }`.
|
|
91
|
-
| `PostgresExecutor` | Anything with Drizzle's `execute`, which `postgresAdvisoryLockTake` takes as `db`.
|
|
92
|
-
| `@n8io/baseline-postgres/testing`: `postgresTestInterleave({ first, second, pgPool, timeoutMs? })` | Forces the interleaving a race test needs (see Race tests below). Import it from tests only.
|
|
93
|
-
| `@n8io/baseline-postgres/testing`: `PostgresTestInterleaveOptions` | What `postgresTestInterleave` takes.
|
|
94
|
-
| `@n8io/baseline-postgres/testing`: `PostgresTestInterleavePool` | The pool the helper watches `pg_stat_activity` through; a `PostgresPool` fits.
|
|
95
|
-
| `postgresIdColumnCreate(prefix)` | A Drizzle `uuid` column that reads and writes `Id<prefix>`.
|
|
96
|
-
| `postgresUniqueViolationIs(error, constraint)` | True when a unique violation on that constraint is anywhere in the `cause` chain.
|
|
97
|
-
| `postgresUniqueViolationRead(error)` | The first unique violation in the `cause` chain as `{ constraint, columns, values }`, or `undefined`. `columns` and `values` come from Postgres's detail (`Key (league_id, name)=(7, Eagles)`), so a value is text as Postgres printed it. Postgres quotes nothing there, so when a key of two or more columns holds a value with `", "` in it, both lists are empty rather than misaligned; an expression key such as `lower(name)` comes back as Postgres printed it, and one with `", "` inside may not split cleanly. Read `constraint` when you need certainty.
|
|
98
|
-
| `postgresKeysetCreate({ after?, descending, idColumn, kind, sortColumn })` | Keyset paging on `(sortColumn, idColumn)`. Returns `{ where, orderBy }` for a Drizzle `select`; `where` is `undefined` on the first page. `after` is the last row of the previous page, `{ id, value }`, with `id` written through `idColumn` (a prefixed id works). `kind` says how the sort compares: `text` by byte order (`COLLATE "C"`, the same in every locale, so give the column a `COLLATE "C"` index); `number` as the column's own type, so its index is used (for `integer`, `real` and `double precision` columns; a `numeric` or `bigint` column reads as a string or a bigint and is not supported); `integer` the same, for an `integer` or `serial` column only (any other column throws), taking only a whole number from -2147483648 to 2147483647; `date` as an instant, with `value` an ISO string with an offset (`toISOString()`). The sort column must be `NOT NULL`, because a NULL never compares, and a `date` column must hold no more than milliseconds (`timestamp({ precision: 3, withTimezone: true })`, or written only from a JS `Date`): a cursor made from a `Date` drops the microseconds a `now()` default stores, and pages would repeat or skip rows. A `value` of the wrong type for `kind`, a date that is not an ISO instant, or a number an `integer` or `smallint` sort column cannot hold (a fraction, or past its range), throws a `TypeError`: decode and check a cursor before you pass it. |
|
|
99
|
-
| `postgresAdvisoryLockTake(db, key)` | Waits for and takes a transaction-scoped advisory lock on the string `key`; Postgres drops it at COMMIT or ROLLBACK. Use it to serialize work that has no row to lock, such as counting a League's Teams before inserting one. `db` is anything with Drizzle's `execute` (`PostgresExecutor`). Call it inside `postgresTransactionRun`: outside a transaction the lock ends with the statement.
|
|
77
|
+
| Export | Does |
|
|
78
|
+
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
|
+
| `postgresPoolCreate({ databaseUrl, max?, connectTimeoutMs?, queryTimeoutMs?, vendor? })` | The process's one pool (10 connections, 3 s connect timeout). A query that takes longer than `queryTimeoutMs` (default 15 s, `null` for no limit) rejects with `Query read timeout`, so a server that stops answering cannot hold a request or a pool slot forever. The pool closes that connection; inside `postgresTransactionRun` it is closed once the rollback has been tried, which can take one more `queryTimeoutMs`. The timer runs in this process and sends no cancel: a server that is slow, not gone, may still finish the query, a write included, so treat the rejection as "unknown", not "did not happen". The limit is per query, inside a transaction too. An idle connection is probed after 10 s (TCP keep-alive). `vendor` takes pg's own pool settings, such as `ssl` or `idleTimeoutMillis`, and passes them through. The named options win: `vendor` throws on the keys they set, on `host`, `port`, `database`, `user` and `password` (pg lets the URL win, so put them in `databaseUrl`), and on `ssl` when the URL carries an `ssl*` parameter. It is outside the contract: nothing in it is tested here, and moving off pg deletes it. Throws a `TypeError` at the call on a `databaseUrl` that is not a Postgres URL, a `vendor` key the named options or the URL already set, or a `connectTimeoutMs`, `max` or `queryTimeoutMs` that is not a positive integer or, for the two durations, is over 2147483647. |
|
|
80
|
+
| `PostgresPool`, `PostgresClient` | The pool and a checked-out connection. `await using` calls the pool's `end()` when its block ends. Name these in your own signatures, not `pg`'s types. They are pg's own pool and client, because Drizzle's `drizzle({ client })` needs the real ones. |
|
|
81
|
+
| `postgresTransactionRun({ pgPool, work, timeoutMs? })` | Runs `work(pgClient)` in one transaction; COMMIT on `ok`, ROLLBACK on `err` or a throw. It ends after `timeoutMs` (default 5 s). Throws a `TypeError` at the call on a `timeoutMs` that is not a positive integer or is over 2147483647. |
|
|
82
|
+
| `postgresMigrate({ databaseUrl, migrationsFolder, connectTimeoutMs?, lockWaitMs?, vendor? })` | Applies pending Drizzle migrations under an advisory lock, so concurrent starts apply each one once. A run waits up to `lockWaitMs` (default 60 s) for the lock, then fails with an error that names it; the connect gives up after `connectTimeoutMs` (default 3 s). The lock belongs to the session, so `databaseUrl` must reach Postgres itself: through a connection pooler such as PgBouncer the run refuses before it changes anything. Queries here have no time limit. `vendor` takes pg's settings for its one connection, under the same rules as the pool's. Throws a `TypeError` at the call on a `databaseUrl` that is not a Postgres URL, a `vendor` key the named options or the URL already set, or a `connectTimeoutMs` or `lockWaitMs` that is not a positive integer or is over 2147483647. |
|
|
83
|
+
| `PostgresPoolOptions` | What `postgresPoolCreate` takes. |
|
|
84
|
+
| `PostgresPoolVendorOptions` | The `vendor` option of `postgresPoolCreate`: pg's own pool settings, outside the contract. |
|
|
85
|
+
| `PostgresMigrateOptions` | What `postgresMigrate` takes. |
|
|
86
|
+
| `PostgresMigrateVendorOptions` | The `vendor` option of `postgresMigrate`: pg's settings for its one connection, outside the contract. |
|
|
87
|
+
| `PostgresTransactionRunOptions` | What `postgresTransactionRun` takes. |
|
|
88
|
+
| `PostgresKeysetKind` | How the sort column compares: `"text"`, `"date"`, `"integer"` or `"number"`. |
|
|
89
|
+
| `PostgresKeysetOptions` | What `postgresKeysetCreate` takes. |
|
|
90
|
+
| `PostgresUniqueViolation` | What `postgresUniqueViolationRead` returns: `{ constraint, columns, values }`. |
|
|
91
|
+
| `PostgresExecutor` | Anything with Drizzle's `execute`, which `postgresAdvisoryLockTake` takes as `db`. |
|
|
92
|
+
| `@n8io/baseline-postgres/testing`: `postgresTestInterleave({ first, second, pgPool, timeoutMs? })` | Forces the interleaving a race test needs (see Race tests below). Import it from tests only. |
|
|
93
|
+
| `@n8io/baseline-postgres/testing`: `PostgresTestInterleaveOptions` | What `postgresTestInterleave` takes. |
|
|
94
|
+
| `@n8io/baseline-postgres/testing`: `PostgresTestInterleavePool` | The pool the helper watches `pg_stat_activity` through; a `PostgresPool` fits. |
|
|
95
|
+
| `postgresIdColumnCreate(prefix)` | A Drizzle `uuid` column that reads and writes `Id<prefix>`. Writing an id of another prefix throws a `TypeError`. |
|
|
96
|
+
| `postgresUniqueViolationIs(error, constraint)` | True when a unique violation on that constraint is anywhere in the `cause` chain. |
|
|
97
|
+
| `postgresUniqueViolationRead(error)` | The first unique violation in the `cause` chain as `{ constraint, columns, values }`, or `undefined`. `columns` and `values` come from Postgres's detail (`Key (league_id, name)=(7, Eagles)`), so a value is text as Postgres printed it. Postgres quotes nothing there, so when a key of two or more columns holds a value with `", "` in it, both lists are empty rather than misaligned; an expression key such as `lower(name)` comes back as Postgres printed it, and one with `", "` inside may not split cleanly. Read `constraint` when you need certainty. |
|
|
98
|
+
| `postgresKeysetCreate({ after?, descending, idColumn, kind, sortColumn })` | Keyset paging on `(sortColumn, idColumn)`. Returns `{ where, orderBy }` for a Drizzle `select`; `where` is `undefined` on the first page. `after` is the last row of the previous page, `{ id, value }`, with `id` written through `idColumn` (a prefixed id works). `kind` says how the sort compares: `text` by byte order (`COLLATE "C"`, the same in every locale, so give the column a `COLLATE "C"` index); `number` as the column's own type, so its index is used (for `integer`, `real` and `double precision` columns; a `numeric` or `bigint` column reads as a string or a bigint and is not supported); `integer` the same, for an `integer` or `serial` column only (any other column throws), taking only a whole number from -2147483648 to 2147483647; `date` as an instant, with `value` an ISO string with an offset (`toISOString()`). The sort column must be `NOT NULL`, because a NULL never compares, and a `date` column must hold no more than milliseconds (`timestamp({ precision: 3, withTimezone: true })`, or written only from a JS `Date`): a cursor made from a `Date` drops the microseconds a `now()` default stores, and pages would repeat or skip rows. A `value` of the wrong type for `kind`, a date that is not an ISO instant, or a number an `integer` or `smallint` sort column cannot hold (a fraction, or past its range), throws a `TypeError`: decode and check a cursor before you pass it. Throws a `TypeError` at the call on a `kind` that is none of the four. |
|
|
99
|
+
| `postgresAdvisoryLockTake(db, key)` | Waits for and takes a transaction-scoped advisory lock on the string `key`; Postgres drops it at COMMIT or ROLLBACK. Use it to serialize work that has no row to lock, such as counting a League's Teams before inserting one. `db` is anything with Drizzle's `execute` (`PostgresExecutor`). Call it inside `postgresTransactionRun`: outside a transaction the lock ends with the statement. |
|
|
100
100
|
|
|
101
101
|
</details>
|
|
102
102
|
|
package/dist/index.d.ts
CHANGED
|
@@ -18,7 +18,10 @@ type PostgresIdColumnBuilder<P extends string> = PgCustomColumnBuilder<{
|
|
|
18
18
|
dataType: "custom";
|
|
19
19
|
driverParam: string;
|
|
20
20
|
}>;
|
|
21
|
-
/**
|
|
21
|
+
/**
|
|
22
|
+
* A `uuid` column in the database that reads and writes prefixed ids (`foo_…`) in code. Writing
|
|
23
|
+
* an id of another prefix throws a TypeError.
|
|
24
|
+
*/
|
|
22
25
|
export declare const postgresIdColumnCreate: <P extends string>(prefix: P) => ((name?: string) => PostgresIdColumnBuilder<P>);
|
|
23
26
|
/**
|
|
24
27
|
* How the sort column compares: `text` by byte order (`COLLATE "C"`), `date` as an instant,
|
|
@@ -32,23 +35,27 @@ type PostgresKeysetOptions = {
|
|
|
32
35
|
id: string;
|
|
33
36
|
value: string | number;
|
|
34
37
|
} | null;
|
|
38
|
+
/** Whether the newest or largest comes first. */
|
|
35
39
|
descending: boolean;
|
|
36
40
|
/** The tie-breaker, unique per row. The cursor's id goes through its encoder. */
|
|
37
41
|
idColumn: AnyColumn;
|
|
42
|
+
/** How the sort column compares. */
|
|
38
43
|
kind: PostgresKeysetKind;
|
|
44
|
+
/** The column the page is sorted by; it must be NOT NULL. */
|
|
39
45
|
sortColumn: AnyColumn;
|
|
40
46
|
};
|
|
41
47
|
/**
|
|
42
48
|
* Keyset ("seek") paging on (sort, id): the rows after `after` in the order of `orderBy`. The sort
|
|
43
49
|
* column must be NOT NULL (a NULL never compares), and a `date` column must hold no more than
|
|
44
50
|
* milliseconds, the precision of the JS Date a cursor is written from. Decode and check the
|
|
45
|
-
* cursor before calling
|
|
51
|
+
* cursor before calling. Throws a TypeError at the call on a `kind` that is none of the four, a
|
|
52
|
+
* value of the wrong type for `kind`, a number an integer or smallint
|
|
46
53
|
* sort column cannot hold, or kind `integer` on another column type, throws a TypeError.
|
|
47
54
|
* A number is bound untyped so Postgres reads it as the column's own type: a `::numeric` cast
|
|
48
55
|
* would turn an integer column's index condition into a filter over the whole index.
|
|
49
56
|
*/
|
|
50
57
|
export declare const postgresKeysetCreate: ({ after, descending, idColumn, kind, sortColumn }: PostgresKeysetOptions) => {
|
|
51
|
-
orderBy: SQL[];
|
|
58
|
+
orderBy: readonly SQL[];
|
|
52
59
|
where: SQL | undefined;
|
|
53
60
|
};
|
|
54
61
|
declare const postgresVendorOwnedKeys: {
|
|
@@ -69,9 +76,13 @@ type PostgresVendorOwnedKey = keyof typeof postgresVendorOwnedKeys;
|
|
|
69
76
|
type PostgresMigrateVendorOptions = Omit<pg.ClientConfig, PostgresVendorOwnedKey>;
|
|
70
77
|
/** What `postgresMigrate` takes. */
|
|
71
78
|
type PostgresMigrateOptions = {
|
|
79
|
+
/** The Postgres URL, `postgres://` or `postgresql://`; it must reach Postgres, not a pooler. */
|
|
72
80
|
databaseUrl: string;
|
|
81
|
+
/** How long the connect may take. Default 3 s. */
|
|
82
|
+
connectTimeoutMs?: number | null;
|
|
73
83
|
/** How long to wait for another run to release the lock. Default 60 s. */
|
|
74
84
|
lockWaitMs?: number | null;
|
|
85
|
+
/** The folder of Drizzle migrations to apply. */
|
|
75
86
|
migrationsFolder: string;
|
|
76
87
|
/** Settings only pg has, such as `ssl`: the same ones the pool takes. */
|
|
77
88
|
vendor?: PostgresMigrateVendorOptions | null;
|
|
@@ -80,6 +91,9 @@ type PostgresMigrateOptions = {
|
|
|
80
91
|
* Applies pending Drizzle migrations under an advisory lock, so concurrent runs (several
|
|
81
92
|
* containers starting at once) apply each migration once: a second run waits, then finds nothing.
|
|
82
93
|
* The lock belongs to the session, so the connection must reach Postgres itself, not a pooler.
|
|
94
|
+
* Throws a TypeError at the call on a `databaseUrl` that is not a Postgres URL, a `vendor` key the
|
|
95
|
+
* named options or the URL already set, or a `connectTimeoutMs` or `lockWaitMs` that is not a
|
|
96
|
+
* positive integer or is over 2147483647.
|
|
83
97
|
*/
|
|
84
98
|
export declare const postgresMigrate: (options: PostgresMigrateOptions) => Promise<void>;
|
|
85
99
|
/**
|
|
@@ -97,6 +111,7 @@ type PostgresClient = pg.PoolClient;
|
|
|
97
111
|
type PostgresPoolVendorOptions = Omit<pg.PoolConfig, PostgresVendorOwnedKey | "max" | "query_timeout">;
|
|
98
112
|
/** What `postgresPoolCreate` takes. */
|
|
99
113
|
type PostgresPoolOptions = {
|
|
114
|
+
/** The Postgres URL, `postgres://` or `postgresql://`. */
|
|
100
115
|
databaseUrl: string;
|
|
101
116
|
/** How long a connect may take. Default 3 s. */
|
|
102
117
|
connectTimeoutMs?: number | null;
|
|
@@ -113,28 +128,34 @@ type PostgresPoolOptions = {
|
|
|
113
128
|
};
|
|
114
129
|
/**
|
|
115
130
|
* The process's one Postgres pool. pg 8.23 ignores `?connect_timeout=` in the URL, so the
|
|
116
|
-
* settings live here.
|
|
131
|
+
* settings live here. Throws a TypeError at the call on a `databaseUrl` that is not a Postgres URL,
|
|
132
|
+
* a `vendor` key the named options or the URL already set, a `connectTimeoutMs`, `max` or
|
|
133
|
+
* `queryTimeoutMs` that is not a positive integer, or a duration over 2147483647.
|
|
117
134
|
*/
|
|
118
135
|
export declare const postgresPoolCreate: (options: PostgresPoolOptions) => PostgresPool;
|
|
119
136
|
/** What `postgresTransactionRun` takes. */
|
|
120
137
|
type PostgresTransactionRunOptions<T, E> = {
|
|
138
|
+
/** The pool to check one client out of. */
|
|
121
139
|
pgPool: PostgresPool;
|
|
122
140
|
/** How long the transaction may run before Postgres ends it. Default 5 s. */
|
|
123
141
|
timeoutMs?: number | null;
|
|
142
|
+
/** Runs on the transaction's client; an ok Result commits, an err Result rolls back. */
|
|
124
143
|
work: (pgClient: PostgresClient) => Promise<Result<T, E>>;
|
|
125
144
|
};
|
|
126
145
|
/**
|
|
127
146
|
* Runs `work` in one transaction on one checked-out client: COMMIT on ok, ROLLBACK on err or a
|
|
128
147
|
* throw. transaction_timeout (Postgres 17+) ends a transaction that runs longer than timeoutMs.
|
|
148
|
+
* Throws a TypeError at the call on a `timeoutMs` that is not a positive integer or is over
|
|
149
|
+
* 2147483647.
|
|
129
150
|
*/
|
|
130
151
|
export declare const postgresTransactionRun: <T, E>({ pgPool, timeoutMs: timeoutMsGiven, work }: PostgresTransactionRunOptions<T, E>) => Promise<Result<T, E>>;
|
|
131
152
|
/** A unique violation as data: the constraint, and the key's columns and values as Postgres printed them. */
|
|
132
153
|
type PostgresUniqueViolation = {
|
|
133
154
|
/** The key's columns, or expressions for an expression index. Empty when Postgres sent no detail. */
|
|
134
|
-
columns: string[];
|
|
155
|
+
columns: readonly string[];
|
|
135
156
|
constraint: string;
|
|
136
157
|
/** The clashing values as Postgres printed them, in column order. Empty when unreadable. */
|
|
137
|
-
values: string[];
|
|
158
|
+
values: readonly string[];
|
|
138
159
|
};
|
|
139
160
|
/** True when `error` or any error in its `.cause` chain is a unique violation on `constraint`. */
|
|
140
161
|
export declare const postgresUniqueViolationIs: (error: unknown, constraint: string) => boolean;
|
package/dist/index.js
CHANGED
|
@@ -16,19 +16,28 @@ const postgresAdvisoryLockTake = async (db, key) => {
|
|
|
16
16
|
await db.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
|
|
17
17
|
};
|
|
18
18
|
// src/postgres-id-column.ts
|
|
19
|
-
/**
|
|
19
|
+
/**
|
|
20
|
+
* A `uuid` column in the database that reads and writes prefixed ids (`foo_…`) in code. Writing
|
|
21
|
+
* an id of another prefix throws a TypeError.
|
|
22
|
+
*/
|
|
20
23
|
const postgresIdColumnCreate = (prefix) => {
|
|
21
24
|
const column = customType({
|
|
22
25
|
dataType: () => "uuid",
|
|
23
26
|
fromDriver: (value) => idFromUuid(prefix, value),
|
|
24
27
|
toDriver: (value) => {
|
|
25
|
-
if (!value.startsWith(`${prefix}_`)) throw new TypeError(`
|
|
28
|
+
if (!value.startsWith(`${prefix}_`)) throw new TypeError(`postgresIdColumnCreate: value must be a ${prefix} id`);
|
|
26
29
|
return idToUuid(value);
|
|
27
30
|
}
|
|
28
31
|
});
|
|
29
32
|
return (name) => name === void 0 ? column() : column(name);
|
|
30
33
|
};
|
|
31
34
|
// src/postgres-keyset.ts
|
|
35
|
+
const postgresKeysetKinds = [
|
|
36
|
+
"date",
|
|
37
|
+
"integer",
|
|
38
|
+
"number",
|
|
39
|
+
"text"
|
|
40
|
+
];
|
|
32
41
|
const isoInstantPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$/;
|
|
33
42
|
const isoInstantIs = (value) => {
|
|
34
43
|
if (!isoInstantPattern.test(value) || Number.isNaN(Date.parse(value))) return false;
|
|
@@ -45,23 +54,25 @@ const integerRanges = {
|
|
|
45
54
|
};
|
|
46
55
|
const integerKindAssert = (sortColumn) => {
|
|
47
56
|
const type = sortColumn.getSQLType();
|
|
48
|
-
if (integerRanges[type] !== int4Range) throw new TypeError(`postgresKeysetCreate: sortColumn: an integer keyset needs an integer or serial column,
|
|
57
|
+
if (integerRanges[type] !== int4Range) throw new TypeError(`postgresKeysetCreate: sortColumn: an integer keyset needs an integer or serial column, found ${type}`);
|
|
49
58
|
};
|
|
50
59
|
const afterValueAssert = ({ kind, sortColumn, value }) => {
|
|
51
60
|
const numeric = kind === "integer" || kind === "number";
|
|
52
61
|
const range = numeric ? integerRanges[sortColumn.getSQLType()] : void 0;
|
|
53
|
-
if (!(numeric ? typeof value === "number" && (range ? Number.isInteger(value) && value >= range[0] && value <= range[1] : Number.isFinite(value)) : typeof value === "string" && (kind === "text" || isoInstantIs(value)))) throw new TypeError(`postgresKeysetCreate: after.value: ${kind === "integer" ? "an" : "a"} ${kind} keyset needs ${range ? `an integer from ${range[0]} to ${range[1]}` : kind === "number" ? "a finite number" : kind === "date" ? "an ISO instant such as 2026-01-01T00:00:00.000Z" : "a string"},
|
|
62
|
+
if (!(numeric ? typeof value === "number" && (range ? Number.isInteger(value) && value >= range[0] && value <= range[1] : Number.isFinite(value)) : typeof value === "string" && (kind === "text" || isoInstantIs(value)))) throw new TypeError(`postgresKeysetCreate: after.value: ${kind === "integer" ? "an" : "a"} ${kind} keyset needs ${range ? `an integer from ${range[0]} to ${range[1]}` : kind === "number" ? "a finite number" : kind === "date" ? "an ISO instant such as 2026-01-01T00:00:00.000Z" : "a string"}, found ${JSON.stringify(value)}`);
|
|
54
63
|
};
|
|
55
64
|
/**
|
|
56
65
|
* Keyset ("seek") paging on (sort, id): the rows after `after` in the order of `orderBy`. The sort
|
|
57
66
|
* column must be NOT NULL (a NULL never compares), and a `date` column must hold no more than
|
|
58
67
|
* milliseconds, the precision of the JS Date a cursor is written from. Decode and check the
|
|
59
|
-
* cursor before calling
|
|
68
|
+
* cursor before calling. Throws a TypeError at the call on a `kind` that is none of the four, a
|
|
69
|
+
* value of the wrong type for `kind`, a number an integer or smallint
|
|
60
70
|
* sort column cannot hold, or kind `integer` on another column type, throws a TypeError.
|
|
61
71
|
* A number is bound untyped so Postgres reads it as the column's own type: a `::numeric` cast
|
|
62
72
|
* would turn an integer column's index condition into a filter over the whole index.
|
|
63
73
|
*/
|
|
64
74
|
const postgresKeysetCreate = ({ after, descending, idColumn, kind, sortColumn }) => {
|
|
75
|
+
if (!postgresKeysetKinds.includes(kind)) throw new TypeError(`postgresKeysetCreate: kind must be "date", "integer", "number" or "text", found ${JSON.stringify(kind)}`);
|
|
65
76
|
if (kind === "integer") integerKindAssert(sortColumn);
|
|
66
77
|
const sortBy = kind === "text" ? sql`${sortColumn} COLLATE "C"` : sql`${sortColumn}`;
|
|
67
78
|
const direction = descending ? sql`DESC` : sql`ASC`;
|
|
@@ -130,6 +141,54 @@ const postgresVendorAssert = ({ caller, databaseUrl, owned, vendor }) => {
|
|
|
130
141
|
const sslParam = postgresUrlSslParams.find((name) => urlParams.has(name));
|
|
131
142
|
if ("ssl" in vendor && sslParam !== void 0) throw new TypeError(`${caller}: vendor.ssl is not allowed with ${sslParam} in databaseUrl: pg lets the URL win; set TLS in one place`);
|
|
132
143
|
};
|
|
144
|
+
// src/postgres-pool.ts
|
|
145
|
+
const postgresDurationMax = 2147483647;
|
|
146
|
+
/**
|
|
147
|
+
* Whether a duration in milliseconds is a positive integer a timer or a Postgres setting can hold.
|
|
148
|
+
* For the other modules of this Package only.
|
|
149
|
+
*/
|
|
150
|
+
const postgresDurationIs = (value) => Number.isSafeInteger(value) && value > 0 && value <= postgresDurationMax;
|
|
151
|
+
/** The limit `postgresDurationIs` applies, for the messages that name it. */
|
|
152
|
+
const postgresDurationMessage = `a positive integer, ${postgresDurationMax} at most`;
|
|
153
|
+
const postgresPositiveIntegerIs = (value) => Number.isSafeInteger(value) && value > 0;
|
|
154
|
+
/**
|
|
155
|
+
* The process's one Postgres pool. pg 8.23 ignores `?connect_timeout=` in the URL, so the
|
|
156
|
+
* settings live here. Throws a TypeError at the call on a `databaseUrl` that is not a Postgres URL,
|
|
157
|
+
* a `vendor` key the named options or the URL already set, a `connectTimeoutMs`, `max` or
|
|
158
|
+
* `queryTimeoutMs` that is not a positive integer, or a duration over 2147483647.
|
|
159
|
+
*/
|
|
160
|
+
const postgresPoolCreate = (options) => {
|
|
161
|
+
const { databaseUrl, queryTimeoutMs = 15e3 } = options;
|
|
162
|
+
const connectTimeoutMs = options.connectTimeoutMs ?? 3e3;
|
|
163
|
+
const max = options.max ?? 10;
|
|
164
|
+
const vendor = options.vendor ?? {};
|
|
165
|
+
postgresUrlAssert(databaseUrl, "postgresPoolCreate");
|
|
166
|
+
postgresVendorAssert({
|
|
167
|
+
caller: "postgresPoolCreate",
|
|
168
|
+
databaseUrl,
|
|
169
|
+
owned: {
|
|
170
|
+
max: "max",
|
|
171
|
+
query_timeout: "queryTimeoutMs"
|
|
172
|
+
},
|
|
173
|
+
vendor
|
|
174
|
+
});
|
|
175
|
+
if (!postgresDurationIs(connectTimeoutMs)) throw new TypeError(`postgresPoolCreate: connectTimeoutMs must be ${postgresDurationMessage}, found ${connectTimeoutMs}`);
|
|
176
|
+
if (!postgresPositiveIntegerIs(max)) throw new TypeError(`postgresPoolCreate: max must be a positive integer, found ${max}`);
|
|
177
|
+
if (queryTimeoutMs !== null && !postgresDurationIs(queryTimeoutMs)) throw new TypeError(`postgresPoolCreate: queryTimeoutMs must be ${postgresDurationMessage} or null, found ${queryTimeoutMs}`);
|
|
178
|
+
const pgPool = new pg.Pool({
|
|
179
|
+
keepAlive: true,
|
|
180
|
+
keepAliveInitialDelayMillis: 1e4,
|
|
181
|
+
...vendor,
|
|
182
|
+
connectionString: databaseUrl,
|
|
183
|
+
connectionTimeoutMillis: connectTimeoutMs,
|
|
184
|
+
max,
|
|
185
|
+
...queryTimeoutMs === null ? {} : { query_timeout: queryTimeoutMs }
|
|
186
|
+
});
|
|
187
|
+
pgPool.on("error", (error) => {
|
|
188
|
+
logger.error({ err: error }, "Postgres idle client error");
|
|
189
|
+
});
|
|
190
|
+
return Object.assign(pgPool, { [Symbol.asyncDispose]: () => pgPool.end() });
|
|
191
|
+
};
|
|
133
192
|
// src/postgres-migrate.ts
|
|
134
193
|
/** A fixed 64-bit advisory lock key: the first 8 bytes of SHA-256("baseline:migrate"). */
|
|
135
194
|
const postgresMigrateLockKey = createHash("sha256").update("baseline:migrate").digest().readBigInt64BE(0).toString();
|
|
@@ -138,6 +197,9 @@ const lockNotAvailable = "55P03";
|
|
|
138
197
|
* Applies pending Drizzle migrations under an advisory lock, so concurrent runs (several
|
|
139
198
|
* containers starting at once) apply each migration once: a second run waits, then finds nothing.
|
|
140
199
|
* The lock belongs to the session, so the connection must reach Postgres itself, not a pooler.
|
|
200
|
+
* Throws a TypeError at the call on a `databaseUrl` that is not a Postgres URL, a `vendor` key the
|
|
201
|
+
* named options or the URL already set, or a `connectTimeoutMs` or `lockWaitMs` that is not a
|
|
202
|
+
* positive integer or is over 2147483647.
|
|
141
203
|
*/
|
|
142
204
|
const postgresMigrate = async (options) => {
|
|
143
205
|
postgresUrlAssert(options.databaseUrl, "postgresMigrate");
|
|
@@ -146,12 +208,14 @@ const postgresMigrate = async (options) => {
|
|
|
146
208
|
databaseUrl: options.databaseUrl,
|
|
147
209
|
vendor: options.vendor ?? {}
|
|
148
210
|
});
|
|
211
|
+
const connectTimeoutMs = options.connectTimeoutMs ?? 3e3;
|
|
212
|
+
if (!postgresDurationIs(connectTimeoutMs)) throw new TypeError(`postgresMigrate: connectTimeoutMs must be ${postgresDurationMessage}, found ${connectTimeoutMs}`);
|
|
149
213
|
const lockWaitMs = options.lockWaitMs ?? 6e4;
|
|
150
|
-
if (!
|
|
214
|
+
if (!postgresDurationIs(lockWaitMs)) throw new TypeError(`postgresMigrate: lockWaitMs must be ${postgresDurationMessage}, found ${lockWaitMs}`);
|
|
151
215
|
const pgClient = new pg.Client({
|
|
152
216
|
...options.vendor,
|
|
153
217
|
connectionString: options.databaseUrl,
|
|
154
|
-
connectionTimeoutMillis:
|
|
218
|
+
connectionTimeoutMillis: connectTimeoutMs
|
|
155
219
|
});
|
|
156
220
|
await pgClient.connect();
|
|
157
221
|
try {
|
|
@@ -171,44 +235,6 @@ const postgresMigrate = async (options) => {
|
|
|
171
235
|
await pgClient.end();
|
|
172
236
|
}
|
|
173
237
|
};
|
|
174
|
-
// src/postgres-pool.ts
|
|
175
|
-
const postgresPositiveIntegerIs = (value) => Number.isSafeInteger(value) && value > 0;
|
|
176
|
-
/**
|
|
177
|
-
* The process's one Postgres pool. pg 8.23 ignores `?connect_timeout=` in the URL, so the
|
|
178
|
-
* settings live here.
|
|
179
|
-
*/
|
|
180
|
-
const postgresPoolCreate = (options) => {
|
|
181
|
-
const { databaseUrl, queryTimeoutMs = 15e3 } = options;
|
|
182
|
-
const connectTimeoutMs = options.connectTimeoutMs ?? 3e3;
|
|
183
|
-
const max = options.max ?? 10;
|
|
184
|
-
const vendor = options.vendor ?? {};
|
|
185
|
-
postgresUrlAssert(databaseUrl, "postgresPoolCreate");
|
|
186
|
-
postgresVendorAssert({
|
|
187
|
-
caller: "postgresPoolCreate",
|
|
188
|
-
databaseUrl,
|
|
189
|
-
owned: {
|
|
190
|
-
max: "max",
|
|
191
|
-
query_timeout: "queryTimeoutMs"
|
|
192
|
-
},
|
|
193
|
-
vendor
|
|
194
|
-
});
|
|
195
|
-
if (!postgresPositiveIntegerIs(connectTimeoutMs)) throw new TypeError("postgresPoolCreate: connectTimeoutMs must be a positive integer");
|
|
196
|
-
if (!postgresPositiveIntegerIs(max)) throw new TypeError("postgresPoolCreate: max must be a positive integer");
|
|
197
|
-
if (queryTimeoutMs !== null && !postgresPositiveIntegerIs(queryTimeoutMs)) throw new TypeError("postgresPoolCreate: queryTimeoutMs must be a positive integer or null");
|
|
198
|
-
const pgPool = new pg.Pool({
|
|
199
|
-
keepAlive: true,
|
|
200
|
-
keepAliveInitialDelayMillis: 1e4,
|
|
201
|
-
...vendor,
|
|
202
|
-
connectionString: databaseUrl,
|
|
203
|
-
connectionTimeoutMillis: connectTimeoutMs,
|
|
204
|
-
max,
|
|
205
|
-
...queryTimeoutMs === null ? {} : { query_timeout: queryTimeoutMs }
|
|
206
|
-
});
|
|
207
|
-
pgPool.on("error", (error) => {
|
|
208
|
-
logger.error({ err: error }, "Postgres idle client error");
|
|
209
|
-
});
|
|
210
|
-
return Object.assign(pgPool, { [Symbol.asyncDispose]: () => pgPool.end() });
|
|
211
|
-
};
|
|
212
238
|
// src/postgres-transaction-run.ts
|
|
213
239
|
const clientGuard = (pgClient, isOpen) => new Proxy(pgClient, { get(target, property) {
|
|
214
240
|
if (!isOpen()) throw new Error("Postgres client used after its transaction ended; keep every query inside the callback");
|
|
@@ -218,10 +244,12 @@ const clientGuard = (pgClient, isOpen) => new Proxy(pgClient, { get(target, prop
|
|
|
218
244
|
/**
|
|
219
245
|
* Runs `work` in one transaction on one checked-out client: COMMIT on ok, ROLLBACK on err or a
|
|
220
246
|
* throw. transaction_timeout (Postgres 17+) ends a transaction that runs longer than timeoutMs.
|
|
247
|
+
* Throws a TypeError at the call on a `timeoutMs` that is not a positive integer or is over
|
|
248
|
+
* 2147483647.
|
|
221
249
|
*/
|
|
222
250
|
const postgresTransactionRun = async ({ pgPool, timeoutMs: timeoutMsGiven, work }) => {
|
|
223
251
|
const timeoutMs = timeoutMsGiven ?? 5e3;
|
|
224
|
-
if (!
|
|
252
|
+
if (!postgresDurationIs(timeoutMs)) throw new TypeError(`postgresTransactionRun: timeoutMs must be ${postgresDurationMessage}, found ${timeoutMs}`);
|
|
225
253
|
const pgClient = await pgPool.connect();
|
|
226
254
|
let broken = false;
|
|
227
255
|
let open = true;
|
package/dist/testing.d.ts
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
/** The pool the helper watches `pg_stat_activity` through: a `PostgresPool` fits. */
|
|
2
2
|
type PostgresTestInterleavePool = {
|
|
3
3
|
query(text: string): Promise<{
|
|
4
|
-
rows: unknown[];
|
|
4
|
+
rows: readonly unknown[];
|
|
5
5
|
}>;
|
|
6
6
|
};
|
|
7
7
|
/** What `postgresTestInterleave` takes. */
|
|
8
8
|
type PostgresTestInterleaveOptions<A, B> = {
|
|
9
9
|
/** Runs until it awaits `pause()`, typically right after it took a lock. */
|
|
10
10
|
first: (pause: () => Promise<void>) => Promise<A>;
|
|
11
|
+
/** The pool whose `pg_stat_activity` the helper polls for a lock wait. */
|
|
11
12
|
pgPool: PostgresTestInterleavePool;
|
|
12
13
|
/** Starts once `first` paused. */
|
|
13
14
|
second: () => Promise<B>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@n8io/baseline-postgres",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.5.0",
|
|
4
4
|
"description": "One pool, transactions that follow your Result and migrations that run once however many processes start, plus prefixed-id columns and keyset paging.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
34
|
"@n8io/baseline-id": "^3.0.2",
|
|
35
|
-
"@n8io/baseline-logger": "^3.1.
|
|
35
|
+
"@n8io/baseline-logger": "^3.1.3",
|
|
36
36
|
"@n8io/baseline-result": "^1.1.4"
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
@@ -54,6 +54,6 @@
|
|
|
54
54
|
"build": "tsdown",
|
|
55
55
|
"check": "tsc --noEmit && pnpm pack --out dist/package.tgz && publint dist/package.tgz --strict && attw dist/package.tgz --profile esm-only",
|
|
56
56
|
"test": "vitest run",
|
|
57
|
-
"test:unit": "vitest run --project unit
|
|
57
|
+
"test:unit": "vitest run --project unit"
|
|
58
58
|
}
|
|
59
59
|
}
|