@omnitron-dev/titan-database 0.2.0 → 0.3.1

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 (54) hide show
  1. package/dist/connection-ref.d.ts +3 -0
  2. package/dist/connection-ref.d.ts.map +1 -0
  3. package/dist/connection-ref.js +70 -0
  4. package/dist/connection-ref.js.map +1 -0
  5. package/dist/database.constants.d.ts +10 -10
  6. package/dist/database.constants.d.ts.map +1 -1
  7. package/dist/database.constants.js.map +1 -1
  8. package/dist/database.decorators.d.ts +6 -0
  9. package/dist/database.decorators.d.ts.map +1 -1
  10. package/dist/database.decorators.js +60 -0
  11. package/dist/database.decorators.js.map +1 -1
  12. package/dist/database.health.d.ts.map +1 -1
  13. package/dist/database.health.js +6 -6
  14. package/dist/database.health.js.map +1 -1
  15. package/dist/database.manager.d.ts +23 -10
  16. package/dist/database.manager.d.ts.map +1 -1
  17. package/dist/database.manager.js +359 -149
  18. package/dist/database.manager.js.map +1 -1
  19. package/dist/database.module.d.ts.map +1 -1
  20. package/dist/database.module.js +30 -14
  21. package/dist/database.module.js.map +1 -1
  22. package/dist/database.types.d.ts +27 -20
  23. package/dist/database.types.d.ts.map +1 -1
  24. package/dist/database.types.js +13 -14
  25. package/dist/database.types.js.map +1 -1
  26. package/dist/exports/transaction.d.ts +1 -1
  27. package/dist/exports/transaction.d.ts.map +1 -1
  28. package/dist/exports/transaction.js +1 -1
  29. package/dist/exports/transaction.js.map +1 -1
  30. package/dist/index.d.ts +4 -4
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +4 -4
  33. package/dist/index.js.map +1 -1
  34. package/dist/migration/cli.d.ts.map +1 -1
  35. package/dist/migration/cli.js +4 -0
  36. package/dist/migration/cli.js.map +1 -1
  37. package/dist/migration/hardened-runner.d.ts +2 -1
  38. package/dist/migration/hardened-runner.d.ts.map +1 -1
  39. package/dist/migration/hardened-runner.js +40 -15
  40. package/dist/migration/hardened-runner.js.map +1 -1
  41. package/dist/plugins/sqlite-date-serializer.plugin.d.ts.map +1 -1
  42. package/dist/repository/transaction-aware.repository.d.ts +18 -1
  43. package/dist/repository/transaction-aware.repository.d.ts.map +1 -1
  44. package/dist/repository/transaction-aware.repository.js +141 -24
  45. package/dist/repository/transaction-aware.repository.js.map +1 -1
  46. package/dist/transaction/transaction.context.d.ts +4 -6
  47. package/dist/transaction/transaction.context.d.ts.map +1 -1
  48. package/dist/transaction/transaction.context.js +30 -14
  49. package/dist/transaction/transaction.context.js.map +1 -1
  50. package/dist/utils/describe-error.d.ts +2 -0
  51. package/dist/utils/describe-error.d.ts.map +1 -0
  52. package/dist/utils/describe-error.js +37 -0
  53. package/dist/utils/describe-error.js.map +1 -0
  54. package/package.json +21 -21
@@ -9,18 +9,53 @@ var __metadata = (this && this.__metadata) || function (k, v) {
9
9
  };
10
10
  var DatabaseManager_1;
11
11
  import { Kysely, PostgresDialect, MysqlDialect, SqliteDialect, CamelCasePlugin, sql } from 'kysely';
12
- import { Pool, Client as PgClient, types as pgTypes } from 'pg';
13
- export class ResilientPgClient extends PgClient {
14
- constructor(config) {
15
- super(config);
16
- this.on('error', () => { });
12
+ import { describeError } from './utils/describe-error.js';
13
+ async function loadDriver(name, dialect, load) {
14
+ try {
15
+ return await load();
17
16
  }
17
+ catch (err) {
18
+ throw new Error(`The '${dialect}' dialect needs the '${name}' package, which is not installed. ` +
19
+ `It is an optional peer dependency of @omnitron-dev/titan-database: install the driver ` +
20
+ `for the database this application uses. (${err.message})`, { cause: err });
21
+ }
22
+ }
23
+ function isPgPool(pool) {
24
+ const p = pool;
25
+ return (!!p && typeof p.totalCount === 'number' && typeof p.idleCount === 'number' && typeof p.waitingCount === 'number');
26
+ }
27
+ let pgModule = null;
28
+ function loadPg() {
29
+ pgModule ??= loadDriver('pg', 'postgres', () => import('pg'));
30
+ return pgModule;
31
+ }
32
+ let mysqlModule = null;
33
+ function loadMysql() {
34
+ mysqlModule ??= loadDriver('mysql2', 'mysql', () => import('mysql2'));
35
+ return mysqlModule;
36
+ }
37
+ let sqliteModule = null;
38
+ function loadSqlite() {
39
+ sqliteModule ??= loadDriver('better-sqlite3', 'sqlite', () => import('better-sqlite3'));
40
+ return sqliteModule;
41
+ }
42
+ let resilientClient = null;
43
+ export async function resilientPgClient() {
44
+ if (resilientClient)
45
+ return resilientClient;
46
+ const { Client: PgClient } = await loadPg();
47
+ resilientClient = class ResilientPgClient extends PgClient {
48
+ constructor(config) {
49
+ super(config);
50
+ this.on('error', () => { });
51
+ }
52
+ };
53
+ return resilientClient;
18
54
  }
19
- import * as mysql from 'mysql2';
20
- import BetterSqlite3 from 'better-sqlite3';
21
55
  import { sqliteDateSerializerPlugin } from './plugins/sqlite-date-serializer.plugin.js';
22
- import { createExecutor, destroyExecutor, isKyseraExecutor, getPlugins, getRawDb, } from '@kysera/executor';
23
- import { CircuitBreaker } from '@kysera/infra';
56
+ import { createExecutor, createExecutorSync, destroyExecutor, isKyseraExecutor, getPlugins, getRawDb, } from '@kysera/executor';
57
+ import { CircuitBreaker, withRetry, isTransientError } from '@kysera/infra';
58
+ import { createLiveConnectionRef } from './connection-ref.js';
24
59
  import { Injectable } from '@omnitron-dev/titan/decorators';
25
60
  import { Errors, TitanError, ErrorCode } from '@omnitron-dev/titan/errors';
26
61
  import { DATABASE_DEFAULT_CONNECTION, DEFAULT_POOL_CONFIG, } from './database.constants.js';
@@ -40,15 +75,47 @@ const DATABASE_EVENTS = {
40
75
  ERROR: 'database.error',
41
76
  };
42
77
  import { EventEmitter } from '@omnitron-dev/eventemitter';
78
+ const PERMANENT_DRIVER_CODES = new Set([
79
+ '28P01',
80
+ '28000',
81
+ '3D000',
82
+ 'SQLITE_CANTOPEN',
83
+ 'ER_ACCESS_DENIED_ERROR',
84
+ 'ER_BAD_DB_ERROR',
85
+ 'ERR_INVALID_URL',
86
+ ]);
87
+ const PERMANENT_MESSAGES = [/Cannot open database because the directory does not exist/i];
88
+ const HIGH_LATENCY_MS = 500;
89
+ export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
90
+ const DISPOSE_WARN_MS = 30_000;
91
+ function healthCheckDeadlineMs(dialect) {
92
+ return dialect === 'sqlite' ? 10_000 : 5_000;
93
+ }
94
+ export function isPermanentConnectionError(error) {
95
+ if (error instanceof TitanError && error.code === ErrorCode.BAD_REQUEST)
96
+ return true;
97
+ const code = error?.code;
98
+ if (typeof code === 'string' && PERMANENT_DRIVER_CODES.has(code))
99
+ return true;
100
+ const message = error instanceof Error ? error.message : '';
101
+ return PERMANENT_MESSAGES.some((re) => re.test(message));
102
+ }
43
103
  let DatabaseManager = class DatabaseManager {
44
104
  static { DatabaseManager_1 = this; }
45
105
  static { this._bigintParserMode = null; }
106
+ get shutdownTimeoutMs() {
107
+ return this.options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
108
+ }
109
+ getRlsDefaults() {
110
+ return this.options.rls;
111
+ }
46
112
  constructor(options, logger) {
47
113
  this.connections = new Map();
48
114
  this.circuitBreakers = new Map();
49
115
  this.connectionSchemas = new Map();
50
116
  this.eventEmitter = new EventEmitter();
51
117
  this.initialized = false;
118
+ this.initPromise = null;
52
119
  this.defaultRetryConfig = {
53
120
  maxRetries: 5,
54
121
  baseDelayMs: 1000,
@@ -56,6 +123,7 @@ let DatabaseManager = class DatabaseManager {
56
123
  timeoutMs: 30000,
57
124
  };
58
125
  this.healthCheckFailures = new Map();
126
+ this.recovering = new Set();
59
127
  this.maxHealthCheckFailures = 3;
60
128
  this.options = options || {};
61
129
  this.logger = logger.child({ module: 'DatabaseManager' });
@@ -66,6 +134,17 @@ let DatabaseManager = class DatabaseManager {
66
134
  this.logger.debug('Database manager already initialized, skipping');
67
135
  return;
68
136
  }
137
+ if (this.initPromise) {
138
+ this.logger.debug('Database manager initialization already in progress, joining');
139
+ await this.initPromise;
140
+ return;
141
+ }
142
+ this.initPromise = this.doInit().finally(() => {
143
+ this.initPromise = null;
144
+ });
145
+ await this.initPromise;
146
+ }
147
+ async doInit() {
69
148
  this.logger.info('Initializing database manager');
70
149
  const connections = this.getConnectionConfigs();
71
150
  for (const [name, config] of Object.entries(connections)) {
@@ -73,18 +152,6 @@ let DatabaseManager = class DatabaseManager {
73
152
  }
74
153
  await this.applyGlobalPlugins();
75
154
  this.initialized = true;
76
- if (this.options.defaultSchema) {
77
- for (const [name, info] of this.connections) {
78
- if (info.config.dialect === 'postgres' && info.connected) {
79
- try {
80
- await this.setSchema(this.options.defaultSchema, name);
81
- }
82
- catch (error) {
83
- this.logger.warn({ connection: name, schema: this.options.defaultSchema, error }, 'Failed to set default schema');
84
- }
85
- }
86
- }
87
- }
88
155
  if (this.options.healthCheck !== false) {
89
156
  this.startProactiveHealthChecks();
90
157
  }
@@ -115,24 +182,50 @@ let DatabaseManager = class DatabaseManager {
115
182
  if (info.connected) {
116
183
  promises.push(this.runSingleHealthCheck(name, info));
117
184
  }
185
+ else if (!info.connecting && !info.permanent && !this.recovering.has(name)) {
186
+ promises.push(this.recoverConnection(name));
187
+ }
118
188
  }
119
189
  if (promises.length > 0) {
120
190
  await Promise.all(promises);
121
191
  }
122
192
  }
193
+ async recoverConnection(name) {
194
+ this.recovering.add(name);
195
+ try {
196
+ await this.reconnect(name);
197
+ this.healthCheckFailures.set(name, 0);
198
+ this.logger.info({ connection: name }, 'Connection recovered by the health check loop');
199
+ }
200
+ catch (error) {
201
+ this.logger.warn({ connection: name, error: describeError(error) }, 'Connection is still down; will try again on the next health check');
202
+ }
203
+ finally {
204
+ this.recovering.delete(name);
205
+ }
206
+ }
123
207
  async runSingleHealthCheck(name, info) {
124
208
  try {
125
- const startTime = Date.now();
126
- const isHealthy = await this.validateConnectionHealth(info.instance, info.config.dialect);
127
- const latency = Date.now() - startTime;
128
- if (isHealthy) {
209
+ const wallStart = Date.now();
210
+ const monoStart = process.hrtime.bigint();
211
+ const result = await this.validateConnectionHealth(info.instance, info.config.dialect);
212
+ const wallMs = Date.now() - wallStart;
213
+ const monoMs = Math.round(Number(process.hrtime.bigint() - monoStart) / 1e6);
214
+ if (result.healthy) {
129
215
  this.healthCheckFailures.set(name, 0);
130
- if (latency > 500) {
131
- this.logger.warn({ connection: name, latency }, 'Connection health check passed but with high latency');
216
+ const deadlineMs = healthCheckDeadlineMs(info.config.dialect);
217
+ if (monoMs > deadlineMs) {
218
+ this.logger.warn({ connection: name, monoMs, wallMs, deadlineMs, stalledAtLeastMs: monoMs - deadlineMs }, 'Health check returned later than its own abort deadline — the event loop was blocked, not the database');
219
+ }
220
+ else if (monoMs > HIGH_LATENCY_MS) {
221
+ this.logger.warn({ connection: name, monoMs, wallMs }, 'Connection health check passed but with high latency');
222
+ }
223
+ else if (wallMs > HIGH_LATENCY_MS) {
224
+ this.logger.debug({ connection: name, monoMs, wallMs }, 'Wall clock jumped during a health check — the machine likely slept');
132
225
  }
133
226
  }
134
227
  else {
135
- await this.handleHealthCheckFailure(name, info, new Error('Health check returned false'));
228
+ await this.handleHealthCheckFailure(name, info, result.error);
136
229
  }
137
230
  }
138
231
  catch (error) {
@@ -142,7 +235,7 @@ let DatabaseManager = class DatabaseManager {
142
235
  async handleHealthCheckFailure(name, info, error) {
143
236
  const failures = (this.healthCheckFailures.get(name) || 0) + 1;
144
237
  this.healthCheckFailures.set(name, failures);
145
- this.logger.warn({ connection: name, failures, maxFailures: this.maxHealthCheckFailures, error: error.message }, 'Connection health check failed');
238
+ this.logger.warn({ connection: name, failures, maxFailures: this.maxHealthCheckFailures, error: describeError(error) }, 'Connection health check failed');
146
239
  info.poolMetrics.errorCount++;
147
240
  info.poolMetrics.lastError = error;
148
241
  this.emitEvent({
@@ -174,12 +267,14 @@ let DatabaseManager = class DatabaseManager {
174
267
  }
175
268
  try {
176
269
  const startTime = Date.now();
177
- const isHealthy = await this.validateConnectionHealth(info.instance, info.config.dialect);
270
+ const result = await this.validateConnectionHealth(info.instance, info.config.dialect);
178
271
  const latency = Date.now() - startTime;
179
- return { healthy: isHealthy, latency };
272
+ return result.healthy
273
+ ? { healthy: true, latency }
274
+ : { healthy: false, latency, error: describeError(result.error) };
180
275
  }
181
276
  catch (error) {
182
- return { healthy: false, error: error.message };
277
+ return { healthy: false, error: describeError(error) };
183
278
  }
184
279
  }
185
280
  getHealthStatus() {
@@ -188,7 +283,7 @@ let DatabaseManager = class DatabaseManager {
188
283
  status.set(name, {
189
284
  connected: info.connected,
190
285
  consecutiveFailures: this.healthCheckFailures.get(name) || 0,
191
- lastError: info.lastError?.message,
286
+ lastError: info.lastError ? describeError(info.lastError) : undefined,
192
287
  poolMetrics: this.collectPoolMetrics(info),
193
288
  });
194
289
  }
@@ -218,33 +313,46 @@ let DatabaseManager = class DatabaseManager {
218
313
  }
219
314
  async createConnectionWithRetry(name, config) {
220
315
  const retryConfig = this.defaultRetryConfig;
221
- let lastError;
222
- for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
223
- try {
224
- this.logger.debug({ name, attempt, maxRetries: retryConfig.maxRetries }, 'Attempting database connection');
225
- const info = await this.createConnection(name, config);
226
- if (attempt > 0) {
227
- this.logger.info({ name, attempt, totalRetries: attempt }, 'Database connection established after retries');
228
- }
229
- return info;
230
- }
231
- catch (error) {
232
- lastError = error;
233
- const isLastAttempt = attempt === retryConfig.maxRetries;
234
- if (isLastAttempt) {
235
- this.logger.error({ name, attempt, error: lastError }, 'Database connection failed after all retries');
236
- break;
237
- }
238
- const delayMs = Math.min(retryConfig.baseDelayMs * Math.pow(2, attempt), retryConfig.maxDelayMs);
239
- this.logger.warn({ name, attempt, nextRetryIn: delayMs, error: lastError.message }, 'Database connection failed, retrying');
240
- await this.sleep(delayMs);
316
+ let attempts = 0;
317
+ try {
318
+ const info = await withRetry(() => {
319
+ attempts += 1;
320
+ this.logger.debug({ name, attempt: attempts - 1, maxRetries: retryConfig.maxRetries }, 'Attempting database connection');
321
+ return this.createConnection(name, config);
322
+ }, {
323
+ maxAttempts: retryConfig.maxRetries + 1,
324
+ delayMs: retryConfig.baseDelayMs,
325
+ maxDelayMs: retryConfig.maxDelayMs,
326
+ backoff: true,
327
+ jitterFactor: 0,
328
+ shouldRetry: (error) => {
329
+ if (error instanceof TitanError && error.details?.['permanent'] === true)
330
+ return false;
331
+ return (isTransientError(error) ||
332
+ (error instanceof TitanError && error.code === ErrorCode.SERVICE_UNAVAILABLE));
333
+ },
334
+ onRetry: (attempt, error) => {
335
+ this.logger.warn({
336
+ name,
337
+ attempt: attempt - 1,
338
+ error: error instanceof Error ? error.message : String(error),
339
+ }, 'Database connection failed, retrying');
340
+ },
341
+ });
342
+ if (attempts > 1) {
343
+ this.logger.info({ name, totalRetries: attempts - 1 }, 'Database connection established after retries');
241
344
  }
345
+ return info;
346
+ }
347
+ catch (error) {
348
+ const message = error instanceof Error ? error.message : String(error);
349
+ this.logger.error({ name, attempts, error }, 'Database connection failed after all retries');
350
+ throw new TitanError({
351
+ code: ErrorCode.SERVICE_UNAVAILABLE,
352
+ message: `Database connection ${name} failed after ${retryConfig.maxRetries} retries: ${message}`,
353
+ details: { connection: name, error: message, maxRetries: retryConfig.maxRetries },
354
+ });
242
355
  }
243
- throw new TitanError({
244
- code: ErrorCode.SERVICE_UNAVAILABLE,
245
- message: `Database connection ${name} failed after ${retryConfig.maxRetries} retries: ${lastError?.message}`,
246
- details: { connection: name, error: lastError?.message, maxRetries: retryConfig.maxRetries },
247
- });
248
356
  }
249
357
  async createConnection(name, config) {
250
358
  this.logger.debug({ name, dialect: config.dialect }, 'Creating database connection');
@@ -281,9 +389,16 @@ let DatabaseManager = class DatabaseManager {
281
389
  const { instance, pool } = await this.createKyselyInstance(config);
282
390
  info.instance = instance;
283
391
  info.pool = pool;
284
- const isHealthy = await this.validateConnectionHealth(instance, config.dialect);
285
- if (!isHealthy) {
286
- throw Errors.unavailable('Database', 'Connection health check failed');
392
+ const health = await this.validateConnectionHealth(instance, config.dialect);
393
+ if (!health.healthy) {
394
+ throw new TitanError({
395
+ code: ErrorCode.SERVICE_UNAVAILABLE,
396
+ message: `Connection health check failed: ${describeError(health.error)}`,
397
+ details: {
398
+ permanent: isPermanentConnectionError(health.error),
399
+ driverCode: health.error.code,
400
+ },
401
+ });
287
402
  }
288
403
  info.connected = true;
289
404
  info.connecting = false;
@@ -311,7 +426,7 @@ let DatabaseManager = class DatabaseManager {
311
426
  info.connecting = false;
312
427
  info.lastError = error;
313
428
  this.connections.set(name, info);
314
- const errorMessage = ERROR_MESSAGES.CONNECTION_FAILED(name, error.message);
429
+ const errorMessage = ERROR_MESSAGES.CONNECTION_FAILED(name, describeError(error));
315
430
  this.logger.error({ name, error }, errorMessage);
316
431
  this.emitEvent({
317
432
  type: DATABASE_EVENTS.ERROR,
@@ -319,10 +434,13 @@ let DatabaseManager = class DatabaseManager {
319
434
  timestamp: new Date(),
320
435
  error: error,
321
436
  });
437
+ const permanent = (error instanceof TitanError && error.details?.['permanent'] === true) ||
438
+ isPermanentConnectionError(error);
439
+ info.permanent = permanent;
322
440
  throw new TitanError({
323
441
  code: ErrorCode.SERVICE_UNAVAILABLE,
324
442
  message: `Database connection ${name} is unavailable: ${errorMessage}`,
325
- details: { connection: name, error: errorMessage },
443
+ details: { connection: name, error: errorMessage, permanent },
326
444
  });
327
445
  }
328
446
  }
@@ -330,6 +448,8 @@ let DatabaseManager = class DatabaseManager {
330
448
  const connectionConfig = this.parseConnectionConfig(config);
331
449
  switch (config.dialect) {
332
450
  case 'postgres': {
451
+ const { Pool, types: pgTypes } = await loadPg();
452
+ const ResilientPgClient = await resilientPgClient();
333
453
  const pgConfig = { ...connectionConfig };
334
454
  if (pgConfig['ssl'] === false) {
335
455
  delete pgConfig['ssl'];
@@ -351,12 +471,21 @@ let DatabaseManager = class DatabaseManager {
351
471
  else if (DatabaseManager_1._bigintParserMode !== coerceBigint) {
352
472
  this.logger.warn({ connection: config.name, requested: coerceBigint, active: DatabaseManager_1._bigintParserMode }, 'pg BIGINT parser mode mismatch — pg.types.setTypeParser is process-global; first pool wins');
353
473
  }
474
+ const pgPoolConfig = { ...DEFAULT_POOL_CONFIG, ...config.pool };
354
475
  const pool = new Pool({
355
476
  ...pgConfig,
356
- ...DEFAULT_POOL_CONFIG,
357
- ...config.pool,
477
+ ...pgPoolConfig,
478
+ connectionTimeoutMillis: pgPoolConfig.connectionTimeoutMillis ?? pgPoolConfig.acquireTimeoutMillis,
479
+ ...(this.options.defaultSchema
480
+ ? {
481
+ options: `-c search_path=${this.assertValidSchemaName(this.options.defaultSchema)},public`,
482
+ }
483
+ : {}),
358
484
  Client: ResilientPgClient,
359
485
  });
486
+ if (this.options.defaultSchema) {
487
+ this.connectionSchemas.set(config.name || DATABASE_DEFAULT_CONNECTION, this.options.defaultSchema);
488
+ }
360
489
  const connectionName = config.name || DATABASE_DEFAULT_CONNECTION;
361
490
  pool.on('error', (err, client) => {
362
491
  const pgErr = err;
@@ -426,6 +555,7 @@ let DatabaseManager = class DatabaseManager {
426
555
  return { instance, pool };
427
556
  }
428
557
  case 'mysql': {
558
+ const mysql = await loadMysql();
429
559
  const mysqlConfig = { ...connectionConfig };
430
560
  if (mysqlConfig['ssl'] === false) {
431
561
  delete mysqlConfig['ssl'];
@@ -497,6 +627,7 @@ let DatabaseManager = class DatabaseManager {
497
627
  return { instance, pool };
498
628
  }
499
629
  case 'sqlite': {
630
+ const { default: BetterSqlite3 } = await loadSqlite();
500
631
  const database = new BetterSqlite3(connectionConfig.database || ':memory:', {
501
632
  verbose: config.debug ? (msg) => this.logger.debug({ msg }, 'SQLite verbose') : undefined,
502
633
  timeout: 5000,
@@ -558,57 +689,58 @@ let DatabaseManager = class DatabaseManager {
558
689
  `Common mistake: Using {...context.connection} instead of {connection: context.connection} ` +
559
690
  `in TitanDatabaseModule.forRoot()`);
560
691
  }
561
- return {
692
+ const base = {
562
693
  database: connConfig.database || (config.dialect === 'sqlite' ? ':memory:' : 'postgres'),
563
694
  host: connConfig.host,
564
695
  port: connConfig.port,
565
696
  user: connConfig.user,
566
697
  password: connConfig.password,
567
698
  ssl: connConfig.ssl,
568
- searchPath: connConfig.searchPath,
569
- charset: connConfig.charset,
570
- timezone: connConfig.timezone,
571
699
  };
700
+ if (config.dialect === 'mysql') {
701
+ return { ...base, charset: connConfig.charset, timezone: connConfig.timezone };
702
+ }
703
+ if (config.dialect === 'postgres') {
704
+ return { ...base, searchPath: connConfig.searchPath };
705
+ }
706
+ return base;
572
707
  }
573
708
  async validateConnectionHealth(db, dialect) {
574
- const timeout = dialect === 'sqlite' ? 10000 : 5000;
709
+ const timeout = healthCheckDeadlineMs(dialect);
575
710
  const ac = new AbortController();
576
711
  const timer = setTimeout(() => ac.abort(), timeout);
577
712
  try {
578
713
  await Promise.race([
579
714
  sql `SELECT 1 AS health_check`.execute(db),
580
715
  new Promise((_, reject) => {
581
- ac.signal.addEventListener('abort', () => reject(new Error('Health check timeout')));
716
+ ac.signal.addEventListener('abort', () => reject(new Error(`Health check timed out after ${timeout}ms`)));
582
717
  }),
583
718
  ]);
584
- return true;
719
+ return { healthy: true };
585
720
  }
586
721
  catch (error) {
587
- this.logger.error({ error }, 'Connection health check failed');
588
- return false;
722
+ return { healthy: false, error: error instanceof Error ? error : new Error(String(error)) };
589
723
  }
590
724
  finally {
591
725
  clearTimeout(timer);
592
726
  }
593
727
  }
594
- sleep(ms) {
595
- return new Promise((resolve) => setTimeout(resolve, ms));
596
- }
597
728
  async getConnection(name = DATABASE_DEFAULT_CONNECTION) {
598
729
  const info = this.connections.get(name);
599
730
  if (!info) {
600
731
  throw Errors.notFound('Database connection', name);
601
732
  }
602
733
  if (!info.connected && !info.connecting) {
603
- await this.reconnect(name);
734
+ await this.reconnect(name).catch(() => undefined);
604
735
  }
605
- if (!info.connected) {
606
- throw Errors.unavailable(name, info.lastError?.message || 'Unknown error');
736
+ const live = this.connections.get(name) ?? info;
737
+ if (!live.connected) {
738
+ throw this.unavailable(name);
607
739
  }
608
- if (info.executor) {
609
- return info.executor;
740
+ if (live.executor) {
741
+ return live.executor;
610
742
  }
611
- return info.instance;
743
+ return live.instance;
612
744
  }
613
745
  async getExecutor(name = DATABASE_DEFAULT_CONNECTION, plugins) {
614
746
  const info = this.connections.get(name);
@@ -616,19 +748,58 @@ let DatabaseManager = class DatabaseManager {
616
748
  throw Errors.notFound('Database connection', name);
617
749
  }
618
750
  if (!info.connected && !info.connecting) {
619
- await this.reconnect(name);
751
+ await this.reconnect(name).catch(() => undefined);
620
752
  }
621
- if (!info.connected) {
622
- throw Errors.unavailable(name, info.lastError?.message || 'Unknown error');
753
+ const live = this.connections.get(name) ?? info;
754
+ if (!live.connected) {
755
+ throw this.unavailable(name);
623
756
  }
624
757
  if (plugins && plugins.length > 0) {
625
758
  this.logger.debug({ connection: name, plugins: plugins.map((p) => p.name) }, 'Creating executor with custom plugins');
626
- return createExecutor(info.instance, plugins);
759
+ return createExecutor(live.instance, plugins);
760
+ }
761
+ if (live.executor) {
762
+ return live.executor;
763
+ }
764
+ return createExecutor(live.instance, []);
765
+ }
766
+ getConnectionRef(name = DATABASE_DEFAULT_CONNECTION) {
767
+ return createLiveConnectionRef(() => this.requireLiveConnection(name));
768
+ }
769
+ getExecutorRef(name = DATABASE_DEFAULT_CONNECTION, plugins = []) {
770
+ let builtFrom;
771
+ let executor;
772
+ return createLiveConnectionRef(() => {
773
+ const instance = this.requireLiveInstance(name);
774
+ if (builtFrom !== instance || !executor) {
775
+ executor = createExecutorSync(instance, plugins);
776
+ builtFrom = instance;
777
+ }
778
+ return executor;
779
+ });
780
+ }
781
+ unavailable(name) {
782
+ return Errors.unavailable(name);
783
+ }
784
+ requireLiveConnection(name) {
785
+ const info = this.connections.get(name);
786
+ if (!info) {
787
+ throw Errors.notFound('Database connection', name);
788
+ }
789
+ if (!info.connected) {
790
+ throw this.unavailable(name);
627
791
  }
628
- if (info.executor) {
629
- return info.executor;
792
+ return (info.executor ?? info.instance);
793
+ }
794
+ requireLiveInstance(name) {
795
+ const info = this.connections.get(name);
796
+ if (!info) {
797
+ throw Errors.notFound('Database connection', name);
630
798
  }
631
- return createExecutor(info.instance, []);
799
+ if (!info.connected) {
800
+ throw this.unavailable(name);
801
+ }
802
+ return info.instance;
632
803
  }
633
804
  async setConnectionPlugins(name = DATABASE_DEFAULT_CONNECTION, plugins) {
634
805
  const info = this.connections.get(name);
@@ -636,7 +807,7 @@ let DatabaseManager = class DatabaseManager {
636
807
  throw Errors.notFound('Database connection', name);
637
808
  }
638
809
  if (!info.connected) {
639
- throw Errors.unavailable(name, 'Connection not established');
810
+ throw this.unavailable(name);
640
811
  }
641
812
  this.logger.info({ connection: name, plugins: plugins.map((p) => p.name) }, 'Setting connection plugins');
642
813
  const executor = await createExecutor(info.instance, plugins);
@@ -664,7 +835,38 @@ let DatabaseManager = class DatabaseManager {
664
835
  throw Errors.notFound('Database connection', name);
665
836
  }
666
837
  this.logger.info({ name }, 'Attempting to reconnect to database');
667
- await this.createConnectionWithRetry(name, info.config);
838
+ const config = info.config;
839
+ info.connected = false;
840
+ info.connecting = true;
841
+ this.healthCheckFailures.delete(name);
842
+ this.circuitBreakers.delete(name);
843
+ this.emitEvent({
844
+ type: DATABASE_EVENTS.DISCONNECTED,
845
+ connection: name,
846
+ timestamp: new Date(),
847
+ });
848
+ void this.disposeReleased(name, info);
849
+ await this.createConnectionWithRetry(name, config);
850
+ }
851
+ async disposeReleased(name, info) {
852
+ const started = Date.now();
853
+ const timer = setTimeout(() => {
854
+ this.logger.warn({ name, afterMs: DISPOSE_WARN_MS }, 'The replaced database connection has still not finished closing; its driver is not settling. The new connection is already serving.');
855
+ }, DISPOSE_WARN_MS);
856
+ timer.unref?.();
857
+ try {
858
+ if (info.executor && isKyseraExecutor(info.executor)) {
859
+ await destroyExecutor(info.executor);
860
+ }
861
+ await info.instance.destroy();
862
+ this.logger.info({ name, ms: Date.now() - started }, 'Replaced database connection closed');
863
+ }
864
+ catch (error) {
865
+ this.logger.warn({ name, error: describeError(error), ms: Date.now() - started }, 'Error closing the replaced database connection');
866
+ }
867
+ finally {
868
+ clearTimeout(timer);
869
+ }
668
870
  }
669
871
  async close(name = DATABASE_DEFAULT_CONNECTION) {
670
872
  const info = this.connections.get(name);
@@ -673,47 +875,62 @@ let DatabaseManager = class DatabaseManager {
673
875
  }
674
876
  this.connections.delete(name);
675
877
  this.healthCheckFailures.delete(name);
878
+ this.circuitBreakers.delete(name);
676
879
  this.logger.info({ name }, 'Closing database connection');
677
880
  try {
678
881
  if (info.executor && isKyseraExecutor(info.executor)) {
679
882
  await destroyExecutor(info.executor);
680
883
  }
681
884
  await info.instance.destroy();
682
- if (info.pool) {
683
- if (info.config.dialect === 'postgres' && info.pool instanceof Pool) {
684
- await info.pool.end();
685
- }
686
- else if (info.config.dialect === 'mysql' && 'end' in info.pool) {
687
- await new Promise((resolve, reject) => {
688
- info.pool.end((err) => (err ? reject(err) : resolve()));
689
- });
690
- }
691
- else if (info.config.dialect === 'sqlite' && 'close' in info.pool) {
692
- info.pool.close();
693
- }
694
- }
885
+ this.logger.info({ name }, 'Database connection closed');
886
+ }
887
+ catch (error) {
888
+ this.logger.error({ name, error }, 'Error closing database connection');
889
+ throw error;
890
+ }
891
+ finally {
695
892
  info.connected = false;
696
893
  this.emitEvent({
697
894
  type: DATABASE_EVENTS.DISCONNECTED,
698
895
  connection: name,
699
896
  timestamp: new Date(),
700
897
  });
701
- this.logger.info({ name }, 'Database connection closed');
702
- }
703
- catch (error) {
704
- this.logger.error({ name, error }, 'Error closing database connection');
705
- throw error;
706
898
  }
707
899
  }
708
900
  async closeAll() {
709
901
  this.stopProactiveHealthChecks();
902
+ this.initialized = false;
710
903
  if (this.connections.size === 0) {
711
904
  return;
712
905
  }
713
906
  this.logger.info('Closing all database connections');
714
907
  const connectionNames = Array.from(this.connections.keys());
715
- const closePromises = connectionNames.map((name) => this.close(name).catch((error) => this.logger.error({ name, error }, 'Error closing connection')));
716
- await Promise.all(closePromises);
908
+ const pending = new Set(connectionNames);
909
+ const closePromises = connectionNames.map((name) => this.close(name)
910
+ .catch((error) => this.logger.error({ name, error }, 'Error closing connection'))
911
+ .finally(() => pending.delete(name)));
912
+ const shutdownTimeout = this.shutdownTimeoutMs;
913
+ if (shutdownTimeout > 0) {
914
+ let timer;
915
+ const timedOut = await Promise.race([
916
+ Promise.all(closePromises).then(() => false),
917
+ new Promise((resolve) => {
918
+ timer = setTimeout(() => resolve(true), shutdownTimeout);
919
+ timer.unref?.();
920
+ }),
921
+ ]);
922
+ if (timer)
923
+ clearTimeout(timer);
924
+ if (timedOut) {
925
+ this.logger.error({ pending: Array.from(pending), shutdownTimeout }, 'Database connections did not close within shutdownTimeout; abandoning the wait');
926
+ return;
927
+ }
928
+ }
929
+ else {
930
+ void Promise.all(closePromises);
931
+ this.logger.info({ pending: Array.from(pending) }, 'Not waiting for database connections to finish closing (shutdownTimeout is 0)');
932
+ return;
933
+ }
717
934
  this.logger.info('All database connections closed');
718
935
  }
719
936
  isConnected(name = DATABASE_DEFAULT_CONNECTION) {
@@ -754,7 +971,7 @@ let DatabaseManager = class DatabaseManager {
754
971
  let idleConnections = m.idleConnections;
755
972
  let activeConnections = m.activeConnections;
756
973
  let waitingClients = m.waitingClients;
757
- if (info.pool && info.config.dialect === 'postgres' && info.pool instanceof Pool) {
974
+ if (info.pool && info.config.dialect === 'postgres' && isPgPool(info.pool)) {
758
975
  const pgPool = info.pool;
759
976
  totalConnections = pgPool.totalCount;
760
977
  idleConnections = pgPool.idleCount;
@@ -823,41 +1040,33 @@ let DatabaseManager = class DatabaseManager {
823
1040
  return this.circuitBreakers.get(name);
824
1041
  }
825
1042
  async withCircuitBreaker(name = DATABASE_DEFAULT_CONNECTION, fn) {
826
- const breaker = this.circuitBreakers.get(name);
827
1043
  const db = await this.getConnection(name);
1044
+ const breaker = this.circuitBreakers.get(name);
828
1045
  if (breaker) {
829
1046
  return breaker.execute(() => fn(db));
830
1047
  }
831
1048
  return fn(db);
832
1049
  }
833
1050
  async setSchema(schema, name = DATABASE_DEFAULT_CONNECTION) {
834
- const info = this.connections.get(name);
835
- if (!info) {
836
- throw Errors.notFound('Database connection', name);
837
- }
838
- if (info.config.dialect !== 'postgres') {
839
- throw Errors.badRequest(`setSchema is only supported for PostgreSQL connections, got: ${info.config.dialect}`);
840
- }
1051
+ throw Errors.badRequest(`setSchema('${schema}', '${name}') is disabled: a session-scoped SET search_path over a ` +
1052
+ `connection pool lands on ONE arbitrary pooled client and breaks schema isolation ` +
1053
+ `nondeterministically. Use the defaultSchema module option (applied as a per-connection ` +
1054
+ `startup parameter), Kysely's .withSchema() for per-query scoping, or a dedicated ` +
1055
+ `connection per tenant.`);
1056
+ }
1057
+ assertValidSchemaName(schema) {
841
1058
  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schema)) {
842
1059
  throw Errors.badRequest(`Invalid schema name: ${schema}`);
843
1060
  }
844
- await sql.raw(`SET search_path TO "${schema}", public`).execute(info.instance);
845
- this.connectionSchemas.set(name, schema);
846
- this.logger.debug({ connection: name, schema }, 'Schema set for connection');
1061
+ return schema;
847
1062
  }
848
1063
  getSchema(name = DATABASE_DEFAULT_CONNECTION) {
849
1064
  return this.connectionSchemas.get(name);
850
1065
  }
851
- async withSchema(schema, fn, name = DATABASE_DEFAULT_CONNECTION) {
852
- const previousSchema = this.connectionSchemas.get(name);
853
- await this.setSchema(schema, name);
854
- try {
855
- const db = await this.getConnection(name);
856
- return await fn(db);
857
- }
858
- finally {
859
- await this.setSchema(previousSchema ?? 'public', name);
860
- }
1066
+ async withSchema(schema, _fn, name = DATABASE_DEFAULT_CONNECTION) {
1067
+ throw Errors.badRequest(`withSchema('${schema}', '${name}') is disabled: switching search_path over a shared ` +
1068
+ `connection pool races between concurrent requests. Use Kysely's .withSchema() for ` +
1069
+ `per-query scoping or a dedicated connection per tenant.`);
861
1070
  }
862
1071
  async resolvePlugins(pluginSpecs) {
863
1072
  const resolved = [];
@@ -898,17 +1107,23 @@ let DatabaseManager = class DatabaseManager {
898
1107
  const { auditPlugin } = await import('@kysera/audit');
899
1108
  return auditPlugin(options);
900
1109
  }
1110
+ case 'rls': {
1111
+ if (!options || typeof options !== 'object' || !('schema' in options)) {
1112
+ this.logger.warn({ plugin: name }, "RLS plugin requires options.schema (use { plugin: 'rls', options: { schema } }); skipping");
1113
+ return null;
1114
+ }
1115
+ const { rlsPlugin } = await import('@kysera/rls');
1116
+ return rlsPlugin(options);
1117
+ }
901
1118
  default:
902
1119
  this.logger.warn({ plugin: name }, 'Unknown built-in plugin name, skipping');
903
1120
  return null;
904
1121
  }
905
1122
  }
906
1123
  async applyGlobalPlugins() {
907
- const pluginSpecs = this.options.kysera?.plugins;
908
- if (!pluginSpecs || pluginSpecs.length === 0) {
909
- const builtIn = this.options.plugins?.builtIn;
910
- if (!builtIn)
911
- return;
1124
+ const plugins = [];
1125
+ const builtIn = this.options.plugins?.builtIn;
1126
+ if (builtIn) {
912
1127
  const legacyPlugins = [];
913
1128
  if (builtIn.softDelete) {
914
1129
  const opts = typeof builtIn.softDelete === 'object' ? builtIn.softDelete : undefined;
@@ -928,17 +1143,12 @@ let DatabaseManager = class DatabaseManager {
928
1143
  if (plugin)
929
1144
  legacyPlugins.push(plugin);
930
1145
  }
931
- if (legacyPlugins.length === 0)
932
- return;
933
- this.logger.info({ plugins: legacyPlugins.map((p) => p.name) }, 'Applying legacy builtIn plugins to all connections');
934
- for (const [name, info] of this.connections) {
935
- if (info.connected) {
936
- await this.setConnectionPlugins(name, legacyPlugins);
937
- }
938
- }
939
- return;
1146
+ plugins.push(...legacyPlugins);
1147
+ }
1148
+ const pluginSpecs = this.options.kysera?.plugins;
1149
+ if (pluginSpecs && pluginSpecs.length > 0) {
1150
+ plugins.push(...(await this.resolvePlugins(pluginSpecs)));
940
1151
  }
941
- const plugins = await this.resolvePlugins(pluginSpecs);
942
1152
  if (plugins.length === 0)
943
1153
  return;
944
1154
  this.logger.info({ plugins: plugins.map((p) => p.name) }, 'Applying global Kysera plugins to all connections');