@owlmeans/postgres 0.1.18-rc.44 → 0.1.18-rc.45

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.
Files changed (40) hide show
  1. package/README.md +5 -4
  2. package/agent-meta/manifest.json +2 -2
  3. package/agent-meta/skills/postgres/SKILL.md +1 -1
  4. package/build/bootstrap.d.ts.map +1 -1
  5. package/build/bootstrap.js +4 -3
  6. package/build/bootstrap.js.map +1 -1
  7. package/build/index.d.ts +2 -0
  8. package/build/index.d.ts.map +1 -1
  9. package/build/index.js.map +1 -1
  10. package/build/service.d.ts.map +1 -1
  11. package/build/service.js +13 -8
  12. package/build/service.js.map +1 -1
  13. package/build/utils/config/types.d.ts +30 -0
  14. package/build/utils/config/types.d.ts.map +1 -0
  15. package/build/utils/config/types.js +2 -0
  16. package/build/utils/config/types.js.map +1 -0
  17. package/build/utils/config.d.ts +4 -24
  18. package/build/utils/config.d.ts.map +1 -1
  19. package/build/utils/config.js +74 -87
  20. package/build/utils/config.js.map +1 -1
  21. package/build/utils/connection/types.d.ts +17 -0
  22. package/build/utils/connection/types.d.ts.map +1 -0
  23. package/build/utils/connection/types.js +2 -0
  24. package/build/utils/connection/types.js.map +1 -0
  25. package/build/utils/connection.d.ts +2 -13
  26. package/build/utils/connection.d.ts.map +1 -1
  27. package/build/utils/connection.js +31 -37
  28. package/build/utils/connection.js.map +1 -1
  29. package/package.json +8 -8
  30. package/src/bootstrap.ts +4 -5
  31. package/src/index.ts +2 -0
  32. package/src/service.ts +14 -9
  33. package/src/utils/config/types.ts +28 -0
  34. package/src/utils/config.ts +80 -89
  35. package/src/utils/connection/types.ts +17 -0
  36. package/src/utils/connection.ts +33 -36
  37. package/tests/context.ts +3 -3
  38. package/tests/criteria.spec.ts +2 -2
  39. package/tests/migration.spec.ts +3 -3
  40. package/tests/sync.spec.ts +3 -3
@@ -1,4 +1,4 @@
1
- import { pgErrorToResourceError, PostgresConnectionError, quoteIdent } from '@owlmeans/postgres-resource';
1
+ import { pgErrorHelper, pgNameHelper, PostgresConnectionError } from '@owlmeans/postgres-resource';
2
2
  import { logger } from '@owlmeans/log';
3
3
  import { DEF_RETRIES, DEF_RETRY_DELAY, TERMINAL_CONNECT_CODES } from '../consts.js';
4
4
  const log = logger('postgres');
@@ -14,45 +14,39 @@ const isTransient = (error) => {
14
14
  }
15
15
  return !TERMINAL_CONNECT_CODES.includes(code);
16
16
  };
17
- /**
18
- * Wait for the server to answer a query, not merely to accept a socket.
19
- *
20
- * Postgres binds its port before it finishes recovery, so a sidecar or an operator managed
21
- * instance routinely accepts a connection and then refuses to run anything. Every OwlMeans
22
- * deployment grew its own copy of this loop; this is the one.
23
- *
24
- * @throws {PostgresConnectionError}
25
- */
26
- export const probe = async (pool, meta, location) => {
27
- const retries = Math.max(1, meta.retries ?? DEF_RETRIES);
28
- const delay = meta.retryDelayMillis ?? DEF_RETRY_DELAY;
29
- let last;
30
- for (let attempt = 1; attempt <= retries; ++attempt) {
17
+ export const makePgConnectionHelper = (pool) => {
18
+ const { pgErrorToResourceError } = pgErrorHelper;
19
+ const probe = async (meta, location) => {
20
+ const retries = Math.max(1, meta.retries ?? DEF_RETRIES);
21
+ const delay = meta.retryDelayMillis ?? DEF_RETRY_DELAY;
22
+ let last;
23
+ for (let attempt = 1; attempt <= retries; ++attempt) {
24
+ try {
25
+ await pool.query('SELECT 1');
26
+ return;
27
+ }
28
+ catch (error) {
29
+ last = error;
30
+ if (attempt === retries || !isTransient(error)) {
31
+ break;
32
+ }
33
+ log.debug('Postgres not ready, retrying', { location, attempt, retries, delay });
34
+ await new Promise(resolve => setTimeout(resolve, delay));
35
+ }
36
+ }
37
+ const translated = pgErrorToResourceError(last);
38
+ const failure = new PostgresConnectionError(`unreachable:${location}:${translated.message}`);
39
+ failure.cause = last;
40
+ throw failure;
41
+ };
42
+ const ensureSchema = async (schema) => {
31
43
  try {
32
- await pool.query('SELECT 1');
33
- return;
44
+ await pool.query(`CREATE SCHEMA IF NOT EXISTS ${pgNameHelper.quoteIdent(schema)}`);
34
45
  }
35
46
  catch (error) {
36
- last = error;
37
- if (attempt === retries || !isTransient(error)) {
38
- break;
39
- }
40
- log.debug('Postgres not ready, retrying', { location, attempt, retries, delay });
41
- await new Promise(resolve => setTimeout(resolve, delay));
47
+ throw pgErrorToResourceError(error);
42
48
  }
43
- }
44
- const translated = pgErrorToResourceError(last);
45
- const failure = new PostgresConnectionError(`unreachable:${location}:${translated.message}`);
46
- failure.cause = last;
47
- throw failure;
48
- };
49
- /** `CREATE SCHEMA IF NOT EXISTS` on a pooled connection. */
50
- export const ensureSchema = async (pool, schema) => {
51
- try {
52
- await pool.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`);
53
- }
54
- catch (error) {
55
- throw pgErrorToResourceError(error);
56
- }
49
+ };
50
+ return { probe, ensureSchema };
57
51
  };
58
52
  //# sourceMappingURL=connection.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAEzG,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAGtC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAEnF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;AAE9B;;;;GAIG;AACH,MAAM,WAAW,GAAG,CAAC,KAAc,EAAW,EAAE;IAC9C,MAAM,IAAI,GAAI,KAAkC,EAAE,IAAI,CAAA;IACtD,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,CAAC,sBAAsB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;AAC/C,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,EAAE,IAAU,EAAE,IAAkB,EAAE,QAAgB,EAAiB,EAAE;IAC7F,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,IAAI,WAAW,CAAC,CAAA;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,IAAI,eAAe,CAAA;IACtD,IAAI,IAAa,CAAA;IAEjB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;YAE5B,OAAM;QACR,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,GAAG,KAAK,CAAA;YACZ,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/C,MAAK;YACP,CAAC;YACD,GAAG,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;YAChF,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;QAC1D,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAA;IAC/C,MAAM,OAAO,GAAG,IAAI,uBAAuB,CAAC,eAAe,QAAQ,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,CAAA;IAC5F,OAAO,CAAC,KAAK,GAAG,IAAI,CAAA;IAEpB,MAAM,OAAO,CAAA;AACf,CAAC,CAAA;AAED,4DAA4D;AAC5D,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAAE,IAAU,EAAE,MAAc,EAAiB,EAAE;IAC9E,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,KAAK,CAAC,+BAA+B,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC;AACH,CAAC,CAAA"}
1
+ {"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAElG,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAGtC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAGnF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;AAE9B;;;;GAIG;AACH,MAAM,WAAW,GAAG,CAAC,KAAc,EAAW,EAAE;IAC9C,MAAM,IAAI,GAAI,KAAkC,EAAE,IAAI,CAAA;IACtD,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,CAAC,sBAAsB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;AAC/C,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,IAAU,EAAsB,EAAE;IACvE,MAAM,EAAE,sBAAsB,EAAE,GAAG,aAAa,CAAA;IAEhD,MAAM,KAAK,GAAG,KAAK,EAAE,IAAkB,EAAE,QAAgB,EAAiB,EAAE;QAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,IAAI,WAAW,CAAC,CAAA;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,IAAI,eAAe,CAAA;QACtD,IAAI,IAAa,CAAA;QAEjB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC;YACpD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;gBAE5B,OAAM;YACR,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,GAAG,KAAK,CAAA;gBACZ,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC/C,MAAK;gBACP,CAAC;gBACD,GAAG,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;gBAChF,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;YAC1D,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAA;QAC/C,MAAM,OAAO,GAAG,IAAI,uBAAuB,CAAC,eAAe,QAAQ,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,CAAA;QAC5F,OAAO,CAAC,KAAK,GAAG,IAAI,CAAA;QAEpB,MAAM,OAAO,CAAA;IACf,CAAC,CAAA;IAED,MAAM,YAAY,GAAG,KAAK,EAAE,MAAc,EAAiB,EAAE;QAC3D,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,+BAA+B,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACpF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAA;QACrC,CAAC;IACH,CAAC,CAAA;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAA;AAChC,CAAC,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@owlmeans/postgres",
3
- "version": "0.1.18-rc.44",
3
+ "version": "0.1.18-rc.45",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -22,18 +22,18 @@
22
22
  }
23
23
  },
24
24
  "dependencies": {
25
- "@owlmeans/basic-keys": "^0.1.18-rc.47",
26
- "@owlmeans/context": "^0.1.18-rc.33",
27
- "@owlmeans/postgres-resource": "^0.1.18-rc.42",
28
- "@owlmeans/resource": "^0.1.18-rc.39",
29
- "@owlmeans/server-context": "^0.1.18-rc.42",
30
- "@owlmeans/log": "^0.1.18-rc.1",
25
+ "@owlmeans/basic-keys": "^0.1.18-rc.48",
26
+ "@owlmeans/context": "^0.1.18-rc.34",
27
+ "@owlmeans/postgres-resource": "^0.1.18-rc.43",
28
+ "@owlmeans/resource": "^0.1.18-rc.40",
29
+ "@owlmeans/server-context": "^0.1.18-rc.43",
30
+ "@owlmeans/log": "^0.1.18-rc.2",
31
31
  "drizzle-orm": "~0.45.3",
32
32
  "pg": "^8.23.1"
33
33
  },
34
34
  "devDependencies": {
35
35
  "@owlmeans/dep-config": "workspace:*",
36
- "@owlmeans/test-integration": "^0.1.18-rc.32",
36
+ "@owlmeans/test-integration": "^0.1.18-rc.33",
37
37
  "@types/bun": "^1.4.2",
38
38
  "@types/node": "^26.6.4",
39
39
  "@types/pg": "^8.23.1",
package/src/bootstrap.ts CHANGED
@@ -1,12 +1,10 @@
1
- import {
2
- assertSqlIdentifier, PostgresBootstrapError, quoteIdent, quoteLiteral
3
- } from '@owlmeans/postgres-resource'
1
+ import { pgNameHelper, PostgresBootstrapError } from '@owlmeans/postgres-resource'
4
2
  import { logger } from '@owlmeans/log'
5
3
  import { Pool } from 'pg'
6
4
  import type { PoolClient } from 'pg'
7
5
 
8
6
  import type { BootstrapOptions, BootstrapReport, PostgresService } from './types.js'
9
- import { prepareConfig } from './utils/config.js'
7
+ import { pgConfigHelper } from './utils/config.js'
10
8
 
11
9
  const log = logger('postgres')
12
10
 
@@ -32,6 +30,7 @@ const exists = async (client: PoolClient, text: string, value: string): Promise<
32
30
  export const bootstrapDb = async (
33
31
  service: PostgresService, configAlias: string, opts: BootstrapOptions
34
32
  ): Promise<BootstrapReport> => {
33
+ const { assertSqlIdentifier, quoteIdent, quoteLiteral } = pgNameHelper
35
34
  const role = assertSqlIdentifier(opts.role, 'role')
36
35
  const database = assertSqlIdentifier(opts.database ?? opts.role, 'database')
37
36
  const schema = opts.schema != null ? assertSqlIdentifier(opts.schema, 'schema') : null
@@ -83,7 +82,7 @@ export const bootstrapDb = async (
83
82
  client.release()
84
83
  }
85
84
 
86
- const target = new Pool(prepareConfig(config, { database, max: 1 }))
85
+ const target = new Pool(pgConfigHelper.prepareConfig(config, { database, max: 1 }))
87
86
  try {
88
87
  if (schema != null) {
89
88
  /**
package/src/index.ts CHANGED
@@ -4,4 +4,6 @@ export * from './bootstrap.js'
4
4
  export * from './middleware.js'
5
5
  export * from './service.js'
6
6
  export * from './utils/config.js'
7
+ export type * from './utils/config/types.js'
7
8
  export * from './utils/connection.js'
9
+ export type * from './utils/connection/types.js'
package/src/service.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { makeKeyPairModel } from '@owlmeans/basic-keys'
2
2
  import { assertContext } from '@owlmeans/context'
3
- import { makeTx, pgErrorToResourceError, pgIdentifier, refOf, resolvePlaceholders, type PostgresDb, type PostgresMeta } from '@owlmeans/postgres-resource'
3
+ import { makeTx, pgErrorHelper, pgNameHelper, pgPlaceholdersOf, type PostgresDb, type PostgresMeta } from '@owlmeans/postgres-resource'
4
4
  import { logThrottle, logger } from '@owlmeans/log'
5
5
  import { createDbService } from '@owlmeans/resource'
6
6
  import { drizzle, type NodePgDatabase } from 'drizzle-orm/node-postgres'
@@ -10,8 +10,8 @@ import { DEFAULT_ALIAS } from './consts.js'
10
10
  import { bootstrapDb } from './bootstrap.js'
11
11
  import { drainMiddleware } from './middleware.js'
12
12
  import type { PostgresService } from './types.js'
13
- import { poolDatabase, prepareConfig } from './utils/config.js'
14
- import { ensureSchema, probe } from './utils/connection.js'
13
+ import { pgConfigHelper } from './utils/config.js'
14
+ import { makePgConnectionHelper } from './utils/connection.js'
15
15
  import type { Config, Context } from './types.local.js'
16
16
 
17
17
  const log = logger('postgres')
@@ -19,6 +19,9 @@ const log = logger('postgres')
19
19
 
20
20
  export const makePostgresDbService = (alias: string = DEFAULT_ALIAS): PostgresService => {
21
21
  const location = `postgres:${alias}`
22
+ const { pgErrorToResourceError } = pgErrorHelper
23
+ const { pgIdentifier } = pgNameHelper
24
+ const { poolDatabase, prepareConfig } = pgConfigHelper
22
25
 
23
26
  /**
24
27
  * Handles are cached per config alias rather than rebuilt per call: `db()` runs on every
@@ -62,6 +65,7 @@ export const makePostgresDbService = (alias: string = DEFAULT_ALIAS): PostgresSe
62
65
 
63
66
  const meta = (config.meta ?? {}) as PostgresMeta
64
67
  const pool = new Pool(prepareConfig(config))
68
+ const connection = makePgConnectionHelper(pool)
65
69
 
66
70
  /**
67
71
  * Not optional: node-postgres emits `error` on *idle* clients when the server closes
@@ -75,7 +79,7 @@ export const makePostgresDbService = (alias: string = DEFAULT_ALIAS): PostgresSe
75
79
  })
76
80
 
77
81
  try {
78
- await probe(pool, meta, location)
82
+ await connection.probe(meta, location)
79
83
  } catch (error) {
80
84
  await pool.end().catch(() => undefined)
81
85
  throw error
@@ -95,7 +99,7 @@ export const makePostgresDbService = (alias: string = DEFAULT_ALIAS): PostgresSe
95
99
  * from the service alias would leave an empty `postgres` schema behind on every boot.
96
100
  */
97
101
  if (config.schema != null) {
98
- await ensureSchema(pool, pgIdentifier(service.name(configAlias)))
102
+ await connection.ensureSchema(pgIdentifier(service.name(configAlias)))
99
103
  }
100
104
  },
101
105
 
@@ -107,7 +111,7 @@ export const makePostgresDbService = (alias: string = DEFAULT_ALIAS): PostgresSe
107
111
  qualify: resourceAlias => {
108
112
  const context = assertContext<Config, Context>(service.ctx as Context, location)
109
113
 
110
- return refOf(context, null, resourceAlias)
114
+ return pgPlaceholdersOf(context).refOf(null, resourceAlias)
111
115
  },
112
116
 
113
117
  query: async <Row extends QueryResultRow = QueryResultRow>(
@@ -117,7 +121,7 @@ export const makePostgresDbService = (alias: string = DEFAULT_ALIAS): PostgresSe
117
121
  const context = assertContext<Config, Context>(service.ctx as Context, location)
118
122
  try {
119
123
  const result = await db.pool.query<Row>(
120
- resolvePlaceholders(text, context, null), params as never[]
124
+ pgPlaceholdersOf(context).resolvePlaceholders(text, null), params as never[]
121
125
  )
122
126
 
123
127
  return result.rows
@@ -129,13 +133,14 @@ export const makePostgresDbService = (alias: string = DEFAULT_ALIAS): PostgresSe
129
133
  transaction: async (fn, configAlias) => {
130
134
  const db = await service.db(configAlias)
131
135
  const context = assertContext<Config, Context>(service.ctx as Context, location)
136
+ const placeholders = pgPlaceholdersOf(context)
132
137
  const client = await db.pool.connect()
133
138
  try {
134
139
  await client.query('BEGIN')
135
140
  const result = await fn(makeTx(
136
141
  client,
137
- text => resolvePlaceholders(text, context, null),
138
- resourceAlias => refOf(context, null, resourceAlias)
142
+ text => placeholders.resolvePlaceholders(text, null),
143
+ resourceAlias => placeholders.refOf(null, resourceAlias)
139
144
  ))
140
145
  await client.query('COMMIT')
141
146
 
@@ -0,0 +1,28 @@
1
+ import type { DbConfig } from '@owlmeans/resource'
2
+ import type { PoolConfig } from 'pg'
3
+
4
+ /** A db config entry as the `pg` pool configuration it describes. */
5
+ export interface PgConfigHelper {
6
+ /**
7
+ * Split a `postgres://` URL into pool fields.
8
+ *
9
+ * node-postgres accepts a `connectionString` directly, but the parsed values *override*
10
+ * every sibling field — so `{ connectionString, database }` silently ignores the
11
+ * database. Parsing here instead keeps overriding possible, which the admin path needs
12
+ * to reach both the maintenance database and the target one over the same credentials.
13
+ *
14
+ * @throws {PostgresConnectionError}
15
+ */
16
+ parseUrl: (url: string) => PoolConfig
17
+ /**
18
+ * Turn a {@link DbConfig} into a `pg` pool configuration.
19
+ *
20
+ * Values that start with `/` have already been read from disk by the `fileConfigReader`
21
+ * middleware, so a file mounted secret and a literal one are indistinguishable here —
22
+ * which is what lets a deployment move from env vars to mounted files without a code
23
+ * change.
24
+ */
25
+ prepareConfig: (config: DbConfig, overrides?: PoolConfig) => PoolConfig
26
+ /** Effective database of an open pool, as `pg` resolved it. */
27
+ poolDatabase: (pool: { options?: PoolConfig }) => string
28
+ }
@@ -4,106 +4,97 @@ import type { DbConfig } from '@owlmeans/resource'
4
4
  import type { PoolConfig } from 'pg'
5
5
 
6
6
  import { DEF_POOL_SIZE, DEF_PORT } from '../consts.js'
7
+ import type { PgConfigHelper } from './config/types.js'
7
8
 
8
- /**
9
- * Split a `postgres://` URL into pool fields.
10
- *
11
- * node-postgres accepts a `connectionString` directly, but the parsed values *override*
12
- * every sibling field — so `{ connectionString, database }` silently ignores the
13
- * database. Parsing here instead keeps overriding possible, which the admin path needs
14
- * to reach both the maintenance database and the target one over the same credentials.
15
- *
16
- * @throws {PostgresConnectionError}
17
- */
18
- export const parseUrl = (url: string): PoolConfig => {
19
- let parsed: URL
20
- try {
21
- parsed = new URL(url)
22
- } catch {
23
- throw new PostgresConnectionError('malformed-url')
24
- }
25
- if (!/^postgres(ql)?:$/.test(parsed.protocol)) {
26
- throw new PostgresConnectionError(`unexpected-protocol:${parsed.protocol.replace(':', '')}`)
27
- }
9
+ export const createPgConfigHelper = (): PgConfigHelper => {
10
+ const parseUrl = (url: string): PoolConfig => {
11
+ let parsed: URL
12
+ try {
13
+ parsed = new URL(url)
14
+ } catch {
15
+ throw new PostgresConnectionError('malformed-url')
16
+ }
17
+ if (!/^postgres(ql)?:$/.test(parsed.protocol)) {
18
+ throw new PostgresConnectionError(`unexpected-protocol:${parsed.protocol.replace(':', '')}`)
19
+ }
28
20
 
29
- const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''))
30
- /** IPv6 literals arrive bracketed from `URL`; `pg` wants the bare address. */
31
- const host = decodeURIComponent(parsed.hostname).replace(/^\[|\]$/g, '')
32
- const mode = parsed.searchParams.get('sslmode')
21
+ const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''))
22
+ /** IPv6 literals arrive bracketed from `URL`; `pg` wants the bare address. */
23
+ const host = decodeURIComponent(parsed.hostname).replace(/^\[|\]$/g, '')
24
+ const mode = parsed.searchParams.get('sslmode')
33
25
 
34
- const config: PoolConfig = {
35
- host,
36
- port: parsed.port !== '' ? parseInt(parsed.port, 10) : DEF_PORT
37
- }
38
- if (parsed.username !== '') {
39
- config.user = decodeURIComponent(parsed.username)
40
- }
41
- if (parsed.password !== '') {
42
- config.password = decodeURIComponent(parsed.password)
43
- }
44
- if (database !== '') {
45
- config.database = database
46
- }
47
- if (mode != null && mode !== 'disable') {
48
- /**
49
- * `no-verify` is what a self signed in-cluster certificate needs, and is the only
50
- * mode that may skip verification — anything else keeps the chain checked.
51
- */
52
- config.ssl = mode === 'no-verify' ? { rejectUnauthorized: false } : true
26
+ const config: PoolConfig = {
27
+ host,
28
+ port: parsed.port !== '' ? parseInt(parsed.port, 10) : DEF_PORT
29
+ }
30
+ if (parsed.username !== '') {
31
+ config.user = decodeURIComponent(parsed.username)
32
+ }
33
+ if (parsed.password !== '') {
34
+ config.password = decodeURIComponent(parsed.password)
35
+ }
36
+ if (database !== '') {
37
+ config.database = database
38
+ }
39
+ if (mode != null && mode !== 'disable') {
40
+ /**
41
+ * `no-verify` is what a self signed in-cluster certificate needs, and is the only
42
+ * mode that may skip verification — anything else keeps the chain checked.
43
+ */
44
+ config.ssl = mode === 'no-verify' ? { rejectUnauthorized: false } : true
45
+ }
46
+
47
+ return config
53
48
  }
54
49
 
55
- return config
56
- }
50
+ const prepareConfig = (config: DbConfig, overrides?: PoolConfig): PoolConfig => {
51
+ const meta = (config.meta ?? {}) as PostgresMeta
57
52
 
58
- /**
59
- * Turn a {@link DbConfig} into a `pg` pool configuration.
60
- *
61
- * Values that start with `/` have already been read from disk by the `fileConfigReader`
62
- * middleware, so a file mounted secret and a literal one are indistinguishable here —
63
- * which is what lets a deployment move from env vars to mounted files without a code
64
- * change.
65
- */
66
- export const prepareConfig = (config: DbConfig, overrides?: PoolConfig): PoolConfig => {
67
- const meta = (config.meta ?? {}) as PostgresMeta
53
+ /**
54
+ * `DbConfig.host` is an array for Mongo's replica sets. Postgres has no client side
55
+ * equivalent — multi-host failover is the pooler's job — so only the first is used.
56
+ */
57
+ const host = Array.isArray(config.host) ? config.host[0] : config.host
68
58
 
69
- /**
70
- * `DbConfig.host` is an array for Mongo's replica sets. Postgres has no client side
71
- * equivalent — multi-host failover is the pooler's job — so only the first is used.
72
- */
73
- const host = Array.isArray(config.host) ? config.host[0] : config.host
59
+ const base: PoolConfig = meta.url != null
60
+ ? parseUrl(meta.url)
61
+ : {
62
+ host,
63
+ port: config.port ?? DEF_PORT,
64
+ ...(config.user != null ? { user: config.user } : {}),
65
+ ...(config.secret != null ? { password: config.secret } : {}),
66
+ /** Absent, libpq falls back to the connection user's name. */
67
+ ...(meta.database != null ? { database: meta.database } : {})
68
+ }
74
69
 
75
- const base: PoolConfig = meta.url != null
76
- ? parseUrl(meta.url)
77
- : {
78
- host,
79
- port: config.port ?? DEF_PORT,
80
- ...(config.user != null ? { user: config.user } : {}),
81
- ...(config.secret != null ? { password: config.secret } : {}),
82
- /** Absent, libpq falls back to the connection user's name. */
83
- ...(meta.database != null ? { database: meta.database } : {})
70
+ const prepared: PoolConfig = {
71
+ ...base,
72
+ max: meta.max ?? DEF_POOL_SIZE,
73
+ ...(meta.ssl != null ? { ssl: meta.ssl as PoolConfig['ssl'] } : {}),
74
+ ...(meta.idleTimeoutMillis != null ? { idleTimeoutMillis: meta.idleTimeoutMillis } : {}),
75
+ ...(meta.connectionTimeoutMillis != null
76
+ ? { connectionTimeoutMillis: meta.connectionTimeoutMillis }
77
+ : {}),
78
+ /**
79
+ * A server side cap, so a query that outlives its caller stops holding a connection
80
+ * and its locks — the failure mode that turns one slow statement into a stuck pool.
81
+ */
82
+ ...(meta.statementTimeoutMillis != null
83
+ ? { statement_timeout: meta.statementTimeoutMillis }
84
+ : {}),
85
+ ...overrides
84
86
  }
85
87
 
86
- const prepared: PoolConfig = {
87
- ...base,
88
- max: meta.max ?? DEF_POOL_SIZE,
89
- ...(meta.ssl != null ? { ssl: meta.ssl as PoolConfig['ssl'] } : {}),
90
- ...(meta.idleTimeoutMillis != null ? { idleTimeoutMillis: meta.idleTimeoutMillis } : {}),
91
- ...(meta.connectionTimeoutMillis != null
92
- ? { connectionTimeoutMillis: meta.connectionTimeoutMillis }
93
- : {}),
94
- /**
95
- * A server side cap, so a query that outlives its caller stops holding a connection
96
- * and its locks — the failure mode that turns one slow statement into a stuck pool.
97
- */
98
- ...(meta.statementTimeoutMillis != null
99
- ? { statement_timeout: meta.statementTimeoutMillis }
100
- : {}),
101
- ...overrides
88
+ return prepared
102
89
  }
103
90
 
104
- return prepared
91
+ const poolDatabase = (pool: { options?: PoolConfig }): string =>
92
+ pool.options?.database ?? pool.options?.user ?? ''
93
+
94
+ return { parseUrl, prepareConfig, poolDatabase }
105
95
  }
106
96
 
107
- /** Effective database of an open pool, as `pg` resolved it. */
108
- export const poolDatabase = (pool: { options?: PoolConfig }): string =>
109
- pool.options?.database ?? pool.options?.user ?? ''
97
+ export const pgConfigHelper = createPgConfigHelper()
98
+
99
+ /** @deprecated compat:factory-refactor — use `pgConfigHelper.parseUrl(…)` */
100
+ export const parseUrl = (url: string): PoolConfig => pgConfigHelper.parseUrl(url)
@@ -0,0 +1,17 @@
1
+ import type { PostgresMeta } from '@owlmeans/postgres-resource'
2
+
3
+ /** Readiness and namespace setup over one pool. */
4
+ export interface PgConnectionHelper {
5
+ /**
6
+ * Wait for the server to answer a query, not merely to accept a socket.
7
+ *
8
+ * Postgres binds its port before it finishes recovery, so a sidecar or an operator managed
9
+ * instance routinely accepts a connection and then refuses to run anything. Every OwlMeans
10
+ * deployment grew its own copy of this loop; this is the one.
11
+ *
12
+ * @throws {PostgresConnectionError}
13
+ */
14
+ probe: (meta: PostgresMeta, location: string) => Promise<void>
15
+ /** `CREATE SCHEMA IF NOT EXISTS` on a pooled connection. */
16
+ ensureSchema: (schema: string) => Promise<void>
17
+ }
@@ -1,9 +1,10 @@
1
- import { pgErrorToResourceError, PostgresConnectionError, quoteIdent } from '@owlmeans/postgres-resource'
1
+ import { pgErrorHelper, pgNameHelper, PostgresConnectionError } from '@owlmeans/postgres-resource'
2
2
  import type { PostgresMeta } from '@owlmeans/postgres-resource'
3
3
  import { logger } from '@owlmeans/log'
4
4
  import type { Pool } from 'pg'
5
5
 
6
6
  import { DEF_RETRIES, DEF_RETRY_DELAY, TERMINAL_CONNECT_CODES } from '../consts.js'
7
+ import type { PgConnectionHelper } from './connection/types.js'
7
8
 
8
9
  const log = logger('postgres')
9
10
 
@@ -21,47 +22,43 @@ const isTransient = (error: unknown): boolean => {
21
22
  return !TERMINAL_CONNECT_CODES.includes(code)
22
23
  }
23
24
 
24
- /**
25
- * Wait for the server to answer a query, not merely to accept a socket.
26
- *
27
- * Postgres binds its port before it finishes recovery, so a sidecar or an operator managed
28
- * instance routinely accepts a connection and then refuses to run anything. Every OwlMeans
29
- * deployment grew its own copy of this loop; this is the one.
30
- *
31
- * @throws {PostgresConnectionError}
32
- */
33
- export const probe = async (pool: Pool, meta: PostgresMeta, location: string): Promise<void> => {
34
- const retries = Math.max(1, meta.retries ?? DEF_RETRIES)
35
- const delay = meta.retryDelayMillis ?? DEF_RETRY_DELAY
36
- let last: unknown
25
+ export const makePgConnectionHelper = (pool: Pool): PgConnectionHelper => {
26
+ const { pgErrorToResourceError } = pgErrorHelper
37
27
 
38
- for (let attempt = 1; attempt <= retries; ++attempt) {
39
- try {
40
- await pool.query('SELECT 1')
28
+ const probe = async (meta: PostgresMeta, location: string): Promise<void> => {
29
+ const retries = Math.max(1, meta.retries ?? DEF_RETRIES)
30
+ const delay = meta.retryDelayMillis ?? DEF_RETRY_DELAY
31
+ let last: unknown
41
32
 
42
- return
43
- } catch (error) {
44
- last = error
45
- if (attempt === retries || !isTransient(error)) {
46
- break
33
+ for (let attempt = 1; attempt <= retries; ++attempt) {
34
+ try {
35
+ await pool.query('SELECT 1')
36
+
37
+ return
38
+ } catch (error) {
39
+ last = error
40
+ if (attempt === retries || !isTransient(error)) {
41
+ break
42
+ }
43
+ log.debug('Postgres not ready, retrying', { location, attempt, retries, delay })
44
+ await new Promise(resolve => setTimeout(resolve, delay))
47
45
  }
48
- log.debug('Postgres not ready, retrying', { location, attempt, retries, delay })
49
- await new Promise(resolve => setTimeout(resolve, delay))
50
46
  }
51
- }
52
47
 
53
- const translated = pgErrorToResourceError(last)
54
- const failure = new PostgresConnectionError(`unreachable:${location}:${translated.message}`)
55
- failure.cause = last
48
+ const translated = pgErrorToResourceError(last)
49
+ const failure = new PostgresConnectionError(`unreachable:${location}:${translated.message}`)
50
+ failure.cause = last
56
51
 
57
- throw failure
58
- }
52
+ throw failure
53
+ }
59
54
 
60
- /** `CREATE SCHEMA IF NOT EXISTS` on a pooled connection. */
61
- export const ensureSchema = async (pool: Pool, schema: string): Promise<void> => {
62
- try {
63
- await pool.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`)
64
- } catch (error) {
65
- throw pgErrorToResourceError(error)
55
+ const ensureSchema = async (schema: string): Promise<void> => {
56
+ try {
57
+ await pool.query(`CREATE SCHEMA IF NOT EXISTS ${pgNameHelper.quoteIdent(schema)}`)
58
+ } catch (error) {
59
+ throw pgErrorToResourceError(error)
60
+ }
66
61
  }
62
+
63
+ return { probe, ensureSchema }
67
64
  }
package/tests/context.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { postgresGate, randomNamespace } from '@owlmeans/test-integration'
1
+ import { randomNamespace, gateHelper } from '@owlmeans/test-integration'
2
2
  import type { IntegrationGate, PostgresEnv } from '@owlmeans/test-integration'
3
3
  import { PgAutoSync, resetPlaceholderCache } from '@owlmeans/postgres-resource'
4
4
  import type { PostgresResource } from '@owlmeans/postgres-resource'
@@ -19,7 +19,7 @@ import type { PostgresService } from '@owlmeans/postgres'
19
19
  * that backs it, which is why the specs live in this package rather than the resource one
20
20
  * (the reverse would make `@owlmeans/postgres-resource` dev-depend on its own dependent).
21
21
  */
22
- export const gate: IntegrationGate<PostgresEnv> = postgresGate()
22
+ export const gate: IntegrationGate<PostgresEnv> = gateHelper.postgresGate()
23
23
 
24
24
  const url = (): string => gate.env.POSTGRES_URL as string
25
25
 
@@ -103,7 +103,7 @@ export const makeSuite = (label: string): PgSuite => {
103
103
  * Declarations are deliberately *not* reset here. They survive a context switch on
104
104
  * purpose (that is the whole point of keying them by alias), and a `.migration()`
105
105
  * registered before `boot()` would be silently dropped. A spec that wants a clean
106
- * slate calls `resetDeclarations(alias)` itself, which is exactly what a spec
106
+ * slate calls `pgDeclarationHelper.resetDeclarations(alias)` itself, which is exactly what a spec
107
107
  * simulating a restarted process should have to say out loud.
108
108
  */
109
109
  resetPlaceholderCache()
@@ -1,7 +1,7 @@
1
1
  import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
2
2
  import { makePostgresResource } from '@owlmeans/postgres-resource'
3
3
  import type { PostgresResource } from '@owlmeans/postgres-resource'
4
- import { matchCriteria, UnsupportedArgumentError } from '@owlmeans/resource'
4
+ import { recordQueryHelper, UnsupportedArgumentError } from '@owlmeans/resource'
5
5
  import type { Criteria, ResourceRecord } from '@owlmeans/resource'
6
6
 
7
7
  import { gate, makeSuite } from './context.js'
@@ -62,7 +62,7 @@ describe('@owlmeans/postgres — criteria answer what the in-memory engine answe
62
62
 
63
63
  const byBoth = async (criteria: Criteria<Plot>): Promise<void> => {
64
64
  const listed = (await plots.list(criteria, { size: 0 })).items.map(plot => plot.id).sort()
65
- const expected = seeded.filter(plot => matchCriteria(plot, criteria)).map(plot => plot.id).sort()
65
+ const expected = seeded.filter(plot => recordQueryHelper.matchCriteria(plot, criteria)).map(plot => plot.id).sort()
66
66
  expect([JSON.stringify(criteria), listed]).toEqual([JSON.stringify(criteria), expected])
67
67
  }
68
68