@n8io/baseline-postgres 4.0.0 → 5.1.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 CHANGED
@@ -8,10 +8,10 @@ pnpm add @n8io/baseline-postgres
8
8
 
9
9
  ## Exports
10
10
 
11
- - `postgresPoolCreate({ databaseUrl, max?, connectTimeoutMs?, vendor? })`: the process's one pool (10 connections, 3 s connect timeout). `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.
11
+ - `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.
12
12
  - `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.
13
- - `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).
14
- - `postgresMigrate({ databaseUrl, migrationsFolder, vendor? })`: applies pending Drizzle migrations under an advisory lock, so concurrent starts apply each one once. `vendor` takes pg's settings for its one connection, under the same rules as the pool's.
13
+ - `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).
14
+ - `postgresMigrate({ databaseUrl, migrationsFolder, 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 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.
15
15
  - `postgresIdColumnCreate(prefix)`: a Drizzle `uuid` column that reads and writes `Id<prefix>`.
16
16
  - `postgresUniqueViolationIs(error, constraint)`: true when a unique violation on that constraint is anywhere in the `cause` chain.
17
17
 
@@ -34,20 +34,27 @@ export const fooTable = pgTable("foo", {
34
34
 
35
35
  const pgPool = postgresPoolCreate({ databaseUrl: ENV.DATABASE_URL });
36
36
 
37
- const result = await postgresTransactionRun(pgPool, async (pgClient) => {
38
- const rows = await drizzle({ client: pgClient })
39
- .insert(fooTable)
40
- .values(foo)
41
- .returning();
42
- return rows[0] ? ok(rows[0]) : err({ type: "FooNotCreated" as const });
37
+ const result = await postgresTransactionRun({
38
+ pgPool,
39
+ work: async (pgClient) => {
40
+ const rows = await drizzle({ client: pgClient })
41
+ .insert(fooTable)
42
+ .values(foo)
43
+ .returning();
44
+ return rows[0] ? ok(rows[0]) : err({ type: "FooNotCreated" as const });
45
+ },
43
46
  });
44
47
  ```
45
48
 
46
49
  ## Needs
47
50
 
48
51
  - Peers: `pg`, `drizzle-orm` (`1.0.0-rc.5`, pinned until 1.0 is out) and, for types, `@types/pg`.
49
- - Env, by the template's convention: `DATABASE_URL` (`postgres://` or `postgresql://`). Transactions use `transaction_timeout`, so Postgres 17 or newer.
52
+ - Env, by the template's convention: `DATABASE_URL` (`postgres://` or `postgresql://`), `DATABASE_POOL_MAX` for `max`, and `DATABASE_MIGRATE_URL` for `postgresMigrate` where `DATABASE_URL` goes through a pooler. Transactions use `transaction_timeout`, so Postgres 17 or newer.
53
+
54
+ ## Sizing the pool
55
+
56
+ Every process opens up to `max` connections, and Postgres refuses new ones past its `max_connections`. Keep the sum over every process (`max` times the number of processes, counting the extra ones a rollout starts) under that limit, with a few left for migrate and for people. Behind a pooler, keep it under the pooler's limit instead.
50
57
 
51
58
  ## Tests
52
59
 
53
- `pnpm test` needs Docker: it starts a Postgres container.
60
+ `pnpm test` needs Docker: it starts a Postgres container and, for the migrate tests, PgBouncer.
package/dist/index.d.ts CHANGED
@@ -25,6 +25,8 @@ type PostgresVendorOwnedKey = keyof typeof postgresVendorOwnedKeys;
25
25
  type PostgresMigrateVendorOptions = Omit<pg.ClientConfig, PostgresVendorOwnedKey>;
26
26
  export declare const postgresMigrate: (options: {
27
27
  databaseUrl: string;
28
+ /** How long to wait for another run to release the lock. Default 60 s. */
29
+ lockWaitMs?: number | null;
28
30
  migrationsFolder: string;
29
31
  /** Settings only pg has, such as `ssl`: the same ones the pool takes. */
30
32
  vendor?: PostgresMigrateVendorOptions;
@@ -41,19 +43,26 @@ type PostgresClient = pg.PoolClient;
41
43
  * here is tested, and moving off pg deletes it. The keys the named options and the URL set are
42
44
  * refused.
43
45
  */
44
- type PostgresPoolVendorOptions = Omit<pg.PoolConfig, PostgresVendorOwnedKey | "max">;
46
+ type PostgresPoolVendorOptions = Omit<pg.PoolConfig, PostgresVendorOwnedKey | "max" | "query_timeout">;
45
47
  type PostgresPoolOptions = {
46
48
  databaseUrl: string;
47
49
  /** How long a connect may take. Default 3 s. */
48
50
  connectTimeoutMs?: number;
49
51
  /** The most connections the pool opens. Default 10. */
50
52
  max?: number;
53
+ /**
54
+ * How long the caller waits for one query before it rejects. Default 15 s; `null` turns it off.
55
+ * The pool closes that connection; the server may still finish the query.
56
+ */
57
+ queryTimeoutMs?: number | null;
51
58
  /** Settings only pg has, such as `ssl` or `idleTimeoutMillis`. */
52
59
  vendor?: PostgresPoolVendorOptions;
53
60
  };
54
- export declare const postgresPoolCreate: ({ connectTimeoutMs, databaseUrl, max, vendor }: PostgresPoolOptions) => PostgresPool;
55
- export declare const postgresTransactionRun: <T, E>(pgPool: PostgresPool, work: (pgClient: PostgresClient) => Promise<Result<T, E>>, options?: {
56
- timeoutMs?: number;
61
+ export declare const postgresPoolCreate: ({ connectTimeoutMs, databaseUrl, max, queryTimeoutMs, vendor }: PostgresPoolOptions) => PostgresPool;
62
+ export declare const postgresTransactionRun: <T, E>({ pgPool, timeoutMs: timeoutMsGiven, work }: {
63
+ pgPool: PostgresPool;
64
+ timeoutMs?: number | null;
65
+ work: (pgClient: PostgresClient) => Promise<Result<T, E>>;
57
66
  }) => Promise<Result<T, E>>;
58
67
  export declare const postgresUniqueViolationIs: (error: unknown, constraint: string) => boolean;
59
68
  export type { PostgresClient, PostgresMigrateVendorOptions, PostgresPool, PostgresPoolOptions, PostgresPoolVendorOptions };
package/dist/index.js CHANGED
@@ -41,7 +41,7 @@ const postgresUrlSslParams = [
41
41
  "sslmode",
42
42
  "sslrootcert"
43
43
  ];
44
- const postgresVendorAssert = (vendor, databaseUrl, owned = {}) => {
44
+ const postgresVendorAssert = ({ databaseUrl, owned = {}, vendor }) => {
45
45
  for (const [key, option] of Object.entries({
46
46
  ...postgresVendorOwnedKeys,
47
47
  ...owned
@@ -52,9 +52,15 @@ const postgresVendorAssert = (vendor, databaseUrl, owned = {}) => {
52
52
  };
53
53
  // src/postgres-migrate.ts
54
54
  const postgresMigrateLockKey = createHash("sha256").update("baseline:migrate").digest().readBigInt64BE(0).toString();
55
+ const lockNotAvailable = "55P03";
55
56
  const postgresMigrate = async (options) => {
56
57
  postgresUrlAssert(options.databaseUrl);
57
- postgresVendorAssert(options.vendor ?? {}, options.databaseUrl);
58
+ postgresVendorAssert({
59
+ vendor: options.vendor ?? {},
60
+ databaseUrl: options.databaseUrl
61
+ });
62
+ const lockWaitMs = options.lockWaitMs ?? 6e4;
63
+ if (!Number.isSafeInteger(lockWaitMs) || lockWaitMs <= 0) throw new TypeError("lockWaitMs must be a positive integer");
58
64
  const pgClient = new pg.Client({
59
65
  ...options.vendor,
60
66
  connectionString: options.databaseUrl,
@@ -62,8 +68,16 @@ const postgresMigrate = async (options) => {
62
68
  });
63
69
  await pgClient.connect();
64
70
  try {
71
+ const { rows } = await pgClient.query("SELECT pg_backend_pid() AS pid");
72
+ if (rows[0]?.pid !== pgClient.processID) throw new Error("postgresMigrate needs a direct connection to Postgres: databaseUrl goes through a connection pooler, which can hand the migrate lock to another session and keep it after this run ends. Use a URL that reaches Postgres itself");
65
73
  await pgClient.query("SET statement_timeout = 0");
66
- await pgClient.query("SELECT pg_advisory_lock($1::bigint)", [postgresMigrateLockKey]);
74
+ await pgClient.query(`SET lock_timeout = '${lockWaitMs}ms'`);
75
+ try {
76
+ await pgClient.query("SELECT pg_advisory_lock($1::bigint)", [postgresMigrateLockKey]);
77
+ } catch (error) {
78
+ if (error.code !== lockNotAvailable) throw error;
79
+ throw new Error(`postgresMigrate waited ${lockWaitMs} ms for the migrate lock (advisory lock ${postgresMigrateLockKey}) and gave up: another migrate is still running, or one that ran through a connection pooler left the lock on a pooled connection. Find the holder in pg_locks (locktype 'advisory') and end that session`, { cause: error });
80
+ }
67
81
  await pgClient.query("SET lock_timeout = '5s'");
68
82
  await migrate(drizzle({ client: pgClient }), { migrationsFolder: options.migrationsFolder });
69
83
  } finally {
@@ -71,15 +85,25 @@ const postgresMigrate = async (options) => {
71
85
  }
72
86
  };
73
87
  // src/postgres-pool.ts
74
- const postgresPoolCreate = ({ connectTimeoutMs = 3e3, databaseUrl, max = 10, vendor = {} }) => {
88
+ const postgresPoolCreate = ({ connectTimeoutMs = 3e3, databaseUrl, max = 10, queryTimeoutMs = 15e3, vendor = {} }) => {
75
89
  postgresUrlAssert(databaseUrl);
76
- postgresVendorAssert(vendor, databaseUrl, { max: "max" });
90
+ postgresVendorAssert({
91
+ vendor,
92
+ databaseUrl,
93
+ owned: {
94
+ max: "max",
95
+ query_timeout: "queryTimeoutMs"
96
+ }
97
+ });
98
+ if (queryTimeoutMs !== null && (!Number.isSafeInteger(queryTimeoutMs) || queryTimeoutMs <= 0)) throw new TypeError("queryTimeoutMs must be a positive integer or null");
77
99
  const pgPool = new pg.Pool({
78
100
  keepAlive: true,
101
+ keepAliveInitialDelayMillis: 1e4,
79
102
  ...vendor,
80
103
  connectionString: databaseUrl,
81
104
  connectionTimeoutMillis: connectTimeoutMs,
82
- max
105
+ max,
106
+ ...queryTimeoutMs === null ? {} : { query_timeout: queryTimeoutMs }
83
107
  });
84
108
  pgPool.on("error", (error) => {
85
109
  logger.error({ err: error }, "Postgres idle client error");
@@ -92,8 +116,8 @@ const clientGuard = (pgClient, isOpen) => new Proxy(pgClient, { get(target, prop
92
116
  const value = Reflect.get(target, property, target);
93
117
  return typeof value === "function" ? value.bind(target) : value;
94
118
  } });
95
- const postgresTransactionRun = async (pgPool, work, options = {}) => {
96
- const timeoutMs = options.timeoutMs ?? 5e3;
119
+ const postgresTransactionRun = async ({ pgPool, timeoutMs: timeoutMsGiven, work }) => {
120
+ const timeoutMs = timeoutMsGiven ?? 5e3;
97
121
  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new TypeError("timeoutMs must be a positive integer");
98
122
  const pgClient = await pgPool.connect();
99
123
  let broken = false;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@n8io/baseline-postgres",
3
- "version": "4.0.0",
3
+ "version": "5.1.0",
4
4
  "description": "Postgres pool, Result-aware transactions, migrations and prefixed-id columns on pg and Drizzle.",
5
5
  "type": "module",
6
6
  "license": "MIT",