velocious 1.0.727 → 1.0.729

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 (112) hide show
  1. package/README.md +2 -2
  2. package/bin/velocious.js +2 -19
  3. package/build/application.js +32 -3
  4. package/build/background-jobs/main.js +9 -1
  5. package/build/background-jobs/worker.js +69 -6
  6. package/build/bin/velocious.js +2 -19
  7. package/build/cli/process-args.js +34 -0
  8. package/build/configuration.js +26 -0
  9. package/build/database/database-name.js +25 -0
  10. package/build/database/drivers/base.js +60 -12
  11. package/build/database/drivers/mssql/index.js +27 -18
  12. package/build/database/drivers/mssql/table.js +28 -25
  13. package/build/database/drivers/mysql/index.js +25 -18
  14. package/build/database/drivers/mysql/table.js +31 -23
  15. package/build/database/drivers/pgsql/index.js +25 -18
  16. package/build/database/drivers/pgsql/table.js +28 -26
  17. package/build/database/drivers/sqlite/base.js +20 -9
  18. package/build/database/drivers/sqlite/table.js +32 -26
  19. package/build/database/pool/async-tracked-multi-connection.js +1 -0
  20. package/build/database/pool/base.js +14 -4
  21. package/build/database/pool/single-multi-use.js +1 -0
  22. package/build/database/query/model-class-query.js +85 -0
  23. package/build/database/record/index.js +33 -0
  24. package/build/environment-handlers/node/cli/commands/server.js +1 -0
  25. package/build/http-server/server-lock.js +28 -4
  26. package/build/src/application.d.ts +7 -4
  27. package/build/src/application.d.ts.map +1 -1
  28. package/build/src/application.js +27 -4
  29. package/build/src/background-jobs/main.d.ts +2 -1
  30. package/build/src/background-jobs/main.d.ts.map +1 -1
  31. package/build/src/background-jobs/main.js +10 -2
  32. package/build/src/background-jobs/worker.d.ts +42 -0
  33. package/build/src/background-jobs/worker.d.ts.map +1 -1
  34. package/build/src/background-jobs/worker.js +61 -5
  35. package/build/src/cli/process-args.d.ts +11 -0
  36. package/build/src/cli/process-args.d.ts.map +1 -0
  37. package/build/src/cli/process-args.js +34 -0
  38. package/build/src/configuration.d.ts +13 -0
  39. package/build/src/configuration.d.ts.map +1 -1
  40. package/build/src/configuration.js +22 -1
  41. package/build/src/database/database-name.d.ts +9 -0
  42. package/build/src/database/database-name.d.ts.map +1 -0
  43. package/build/src/database/database-name.js +23 -0
  44. package/build/src/database/drivers/base.d.ts +31 -2
  45. package/build/src/database/drivers/base.d.ts.map +1 -1
  46. package/build/src/database/drivers/base.js +56 -13
  47. package/build/src/database/drivers/mssql/index.d.ts +7 -2
  48. package/build/src/database/drivers/mssql/index.d.ts.map +1 -1
  49. package/build/src/database/drivers/mssql/index.js +25 -18
  50. package/build/src/database/drivers/mssql/table.d.ts.map +1 -1
  51. package/build/src/database/drivers/mssql/table.js +25 -23
  52. package/build/src/database/drivers/mysql/index.d.ts +7 -2
  53. package/build/src/database/drivers/mysql/index.d.ts.map +1 -1
  54. package/build/src/database/drivers/mysql/index.js +24 -19
  55. package/build/src/database/drivers/mysql/table.d.ts.map +1 -1
  56. package/build/src/database/drivers/mysql/table.js +27 -22
  57. package/build/src/database/drivers/pgsql/index.d.ts +7 -2
  58. package/build/src/database/drivers/pgsql/index.d.ts.map +1 -1
  59. package/build/src/database/drivers/pgsql/index.js +24 -19
  60. package/build/src/database/drivers/pgsql/table.d.ts.map +1 -1
  61. package/build/src/database/drivers/pgsql/table.js +25 -23
  62. package/build/src/database/drivers/sqlite/base.d.ts +8 -0
  63. package/build/src/database/drivers/sqlite/base.d.ts.map +1 -1
  64. package/build/src/database/drivers/sqlite/base.js +19 -10
  65. package/build/src/database/drivers/sqlite/table.d.ts.map +1 -1
  66. package/build/src/database/drivers/sqlite/table.js +29 -25
  67. package/build/src/database/pool/async-tracked-multi-connection.d.ts.map +1 -1
  68. package/build/src/database/pool/async-tracked-multi-connection.js +2 -1
  69. package/build/src/database/pool/base.d.ts +6 -0
  70. package/build/src/database/pool/base.d.ts.map +1 -1
  71. package/build/src/database/pool/base.js +14 -5
  72. package/build/src/database/pool/single-multi-use.d.ts.map +1 -1
  73. package/build/src/database/pool/single-multi-use.js +2 -1
  74. package/build/src/database/query/model-class-query.d.ts +20 -0
  75. package/build/src/database/query/model-class-query.d.ts.map +1 -1
  76. package/build/src/database/query/model-class-query.js +75 -1
  77. package/build/src/database/record/index.d.ts +46 -0
  78. package/build/src/database/record/index.d.ts.map +1 -1
  79. package/build/src/database/record/index.js +30 -1
  80. package/build/src/environment-handlers/node/cli/commands/server.d.ts.map +1 -1
  81. package/build/src/environment-handlers/node/cli/commands/server.js +2 -1
  82. package/build/src/http-server/server-lock.d.ts +23 -5
  83. package/build/src/http-server/server-lock.d.ts.map +1 -1
  84. package/build/src/http-server/server-lock.js +27 -5
  85. package/build/src/tenants/default-tenant-database-provisioning.d.ts +14 -0
  86. package/build/src/tenants/default-tenant-database-provisioning.d.ts.map +1 -1
  87. package/build/src/tenants/default-tenant-database-provisioning.js +31 -17
  88. package/build/tenants/default-tenant-database-provisioning.js +33 -19
  89. package/package.json +2 -2
  90. package/src/application.js +32 -3
  91. package/src/background-jobs/main.js +9 -1
  92. package/src/background-jobs/worker.js +69 -6
  93. package/src/cli/process-args.js +34 -0
  94. package/src/configuration.js +26 -0
  95. package/src/database/database-name.js +25 -0
  96. package/src/database/drivers/base.js +60 -12
  97. package/src/database/drivers/mssql/index.js +27 -18
  98. package/src/database/drivers/mssql/table.js +28 -25
  99. package/src/database/drivers/mysql/index.js +25 -18
  100. package/src/database/drivers/mysql/table.js +31 -23
  101. package/src/database/drivers/pgsql/index.js +25 -18
  102. package/src/database/drivers/pgsql/table.js +28 -26
  103. package/src/database/drivers/sqlite/base.js +20 -9
  104. package/src/database/drivers/sqlite/table.js +32 -26
  105. package/src/database/pool/async-tracked-multi-connection.js +1 -0
  106. package/src/database/pool/base.js +14 -4
  107. package/src/database/pool/single-multi-use.js +1 -0
  108. package/src/database/query/model-class-query.js +85 -0
  109. package/src/database/record/index.js +33 -0
  110. package/src/environment-handlers/node/cli/commands/server.js +1 -0
  111. package/src/http-server/server-lock.js +28 -4
  112. package/src/tenants/default-tenant-database-provisioning.js +33 -19
@@ -13,6 +13,7 @@ import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
13
13
  import performBackgroundJob from "./perform-job.js"
14
14
  import { runWithBackgroundJobPayload } from "./execution-context.js"
15
15
  import { createGenerationWorkerId } from "./generation-identity.js"
16
+ import { isProcessAlive } from "./owner-liveness.js"
16
17
  import BackgroundJobsGenerationHandshakeTimeoutError, { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
17
18
  import { POOLED_RUNNER_INFLIGHT_JOB_ID_LIMIT, boundedPooledRunnerInflightJobIds, isPooledChildShutdownReason, isPooledChildShutdownSignal } from "./pooled-runner-shutdown.js"
18
19
 
@@ -33,7 +34,9 @@ import { POOLED_RUNNER_INFLIGHT_JOB_ID_LIMIT, boundedPooledRunnerInflightJobIds,
33
34
  * One live runner child, kept so a shutdown that runs out of drain time can name
34
35
  * the exact process it is still waiting on instead of a bare count.
35
36
  * @typedef {object} ProcessJobHolder
37
+ * @property {number | null} childPid - OS pid recorded for the runner, or null when the fork gave none.
36
38
  * @property {string} jobId - Job the child was handed.
39
+ * @property {(() => void)} settle - Frees the worker's in-flight entry for this job.
37
40
  * @property {number} startedAtMs - When the worker handed it that job.
38
41
  */
39
42
  /**
@@ -590,6 +593,7 @@ export default class BackgroundJobsWorker {
590
593
 
591
594
  await this._drainInflight(this.inflightInlineJobs, timeoutMs, {phase: "inline-jobs"})
592
595
  await this._drainInflight(this.inflightPooledJobs, timeoutMs, {phase: "pooled-jobs"})
596
+ this._releaseProcessJobHoldersWithGoneChildren()
593
597
  await this._drainInflight(this.inflightProcessJobs, timeoutMs, {phase: "process-jobs", describeHolders: () => this._describeProcessJobHolders()})
594
598
  await this._terminateProcessChildren()
595
599
  // Give in-flight result reports (now decoupled from job slots) a bounded
@@ -635,6 +639,7 @@ export default class BackgroundJobsWorker {
635
639
 
636
640
  await this._drainInflight(this.inflightInlineJobs)
637
641
  await this._drainInflight(this.inflightPooledJobs)
642
+ this._releaseProcessJobHoldersWithGoneChildren()
638
643
  await this._drainInflight(this.inflightProcessJobs)
639
644
  await this._drainInflight(this.inflightReports)
640
645
 
@@ -722,6 +727,48 @@ export default class BackgroundJobsWorker {
722
727
  return [...this.processChildJobs.values()].sort((left, right) => left.startedAtMs - right.startedAtMs)
723
728
  }
724
729
 
730
+ /**
731
+ * Frees in-flight process-job entries whose recorded runner pid no longer
732
+ * exists, so an unbounded drain can reach child termination.
733
+ *
734
+ * A drain that has no bound can only be pinned by work that is still able to
735
+ * report its outcome. A holder whose recorded pid has no process cannot report
736
+ * and cannot produce the exit observation that would have freed the entry, so
737
+ * the drain waits on it forever and never reaches `_terminateProcessChildren()`
738
+ * — the shape that kept a retired generation alive across four deploys on
739
+ * 2026-11-12 (STOE-1663). This is one proof-of-absence check at the point the
740
+ * drain begins, not a polling layer: a child that is still alive keeps the
741
+ * indefinite wait it was designed to have, because a live runner with a live
742
+ * job must never be cut off by this path (STOE-1077), and its exit observation
743
+ * is the event that frees its entry when it does go.
744
+ * @returns {ProcessJobHolder[]} - Holders freed, in recording order.
745
+ */
746
+ _releaseProcessJobHoldersWithGoneChildren() {
747
+ const released = []
748
+
749
+ for (const holder of [...this.processChildJobs.values()]) {
750
+ if (holder.childPid === null || isProcessAlive(holder.childPid)) continue
751
+
752
+ released.push(holder)
753
+ holder.settle()
754
+ }
755
+
756
+ if (released.length > 0) {
757
+ const nowMs = Date.now()
758
+
759
+ console.error(JSON.stringify({
760
+ event: "worker-shutdown-gone-runner-released",
761
+ runners: released.map((holder) => ({
762
+ childPid: holder.childPid,
763
+ heldMs: nowMs - holder.startedAtMs,
764
+ jobId: holder.jobId
765
+ }))
766
+ }))
767
+ }
768
+
769
+ return released
770
+ }
771
+
725
772
  /**
726
773
  * Logs one compact drain-timeout event to the worker's own stderr (the surface
727
774
  * that reaches the production log), naming the held processes and how long each
@@ -2234,9 +2281,6 @@ export default class BackgroundJobsWorker {
2234
2281
  _forkJob(payload) {
2235
2282
  const child = this._createForkedChild()
2236
2283
 
2237
- this.inflightProcessChildren.add(child)
2238
- this.processChildJobs.set(child, {jobId: payload.id, startedAtMs: Date.now()})
2239
-
2240
2284
  const finished = this._waitForForkedChild({child, payload})
2241
2285
 
2242
2286
  this._sendForkedPayload({child, payload})
@@ -2244,6 +2288,25 @@ export default class BackgroundJobsWorker {
2244
2288
  return finished
2245
2289
  }
2246
2290
 
2291
+ /**
2292
+ * Records the live runner child this worker handed a job to, with the resolver
2293
+ * that frees the worker's in-flight entry for it, so a drain can name the exact
2294
+ * process it is waiting on and can prove which of them is no longer there.
2295
+ * @param {object} args - Holder fields.
2296
+ * @param {import("node:child_process").ChildProcess} args.child - Runner child.
2297
+ * @param {import("./types.js").BackgroundJobPayload & {id: string}} args.payload - Job payload.
2298
+ * @param {(() => void)} args.settle - Frees the worker's in-flight entry for this job.
2299
+ * @returns {ProcessJobHolder} - Recorded holder.
2300
+ */
2301
+ _registerProcessJobHolder({child, payload, settle}) {
2302
+ const holder = {childPid: child.pid ?? null, jobId: payload.id, settle, startedAtMs: Date.now()}
2303
+
2304
+ this.inflightProcessChildren.add(child)
2305
+ this.processChildJobs.set(child, holder)
2306
+
2307
+ return holder
2308
+ }
2309
+
2247
2310
  /**
2248
2311
  * Runs create forked child.
2249
2312
  * @returns {import("node:child_process").ChildProcess} - Forked child process.
@@ -2283,6 +2346,7 @@ export default class BackgroundJobsWorker {
2283
2346
 
2284
2347
  return new Promise((resolve) => {
2285
2348
  state.resolve = resolve
2349
+ this._registerProcessJobHolder({child, payload, settle: () => this._settleForkedJob({child, state})})
2286
2350
  this._armForkedJobTimeout({child, payload, state})
2287
2351
 
2288
2352
  child.once("message", (message) => {
@@ -2557,10 +2621,9 @@ export default class BackgroundJobsWorker {
2557
2621
  env: Object.assign({}, process.env, this._childBackgroundJobsEnvironment(), {VELOCIOUS_JOB_PAYLOAD: encodedPayload})
2558
2622
  })
2559
2623
 
2560
- this.inflightProcessChildren.add(child)
2561
- this.processChildJobs.set(child, {jobId: payload.id, startedAtMs: Date.now()})
2562
-
2563
2624
  const finished = new Promise((resolve) => {
2625
+ this._registerProcessJobHolder({child, payload, settle: () => resolve(undefined)})
2626
+
2564
2627
  child.once("exit", () => {
2565
2628
  this.inflightProcessChildren.delete(child)
2566
2629
  this.processChildJobs.delete(child)
@@ -0,0 +1,34 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * Parses CLI flags into values keyed by long option name without `--`.
5
+ *
6
+ * Hyphenated long flags are parsed as one option name (`--no-server-lock` →
7
+ * `no-server-lock`), so a boolean flag can carry its own words instead of
8
+ * being silently dropped by a single-word pattern.
9
+ * @param {string[]} processArgs - Raw CLI arguments.
10
+ * @returns {Record<string, string | boolean | undefined>} - Values keyed by option name.
11
+ */
12
+ export default function parseProcessArgs(processArgs) {
13
+ /** @type {Record<string, string | boolean | undefined>} */
14
+ const parsedProcessArgs = {}
15
+
16
+ for (let i = 0; i < processArgs.length; i++) {
17
+ const processArg = processArgs[i]
18
+ const singleLetterArgMatch = processArg.match(/^-([a-z])$/)
19
+ const multiLetterArgMatch = processArg.match(/^--([a-z][a-z-]*)$/)
20
+ const nextArg = processArgs[i + 1]
21
+ const hasValue = typeof nextArg === "string" && !nextArg.startsWith("-")
22
+ const parsedValue = hasValue ? nextArg : true
23
+
24
+ if (singleLetterArgMatch) {
25
+ parsedProcessArgs[singleLetterArgMatch[1]] = parsedValue
26
+ if (hasValue) i++
27
+ } else if (multiLetterArgMatch) {
28
+ parsedProcessArgs[multiLetterArgMatch[1]] = parsedValue
29
+ if (hasValue) i++
30
+ }
31
+ }
32
+
33
+ return parsedProcessArgs
34
+ }
@@ -286,6 +286,14 @@ export default class VelociousConfiguration {
286
286
  /** @type {Map<string, number>} */
287
287
  _schemaCacheGenerationsByReuseKey = new Map()
288
288
 
289
+ /**
290
+ * Schema-metadata cache maps keyed by physical database reuse key. Every
291
+ * connection to one physical database shares a single map, so cached table
292
+ * and column introspection survives pool connection churn instead of being
293
+ * re-run on every re-spawned connection.
294
+ * @type {Map<string, Map<string, Promise<ReturnType<typeof JSON.parse>>>>} */
295
+ _schemaCacheMapsByReuseKey = new Map()
296
+
289
297
  /**
290
298
  * Runs current.
291
299
  * @returns {VelociousConfiguration} - The current.
@@ -1422,6 +1430,8 @@ export default class VelociousConfiguration {
1422
1430
  this.schemaCacheGenerationForReuseKey(reuseKey) + 1
1423
1431
  )
1424
1432
 
1433
+ this.schemaCacheMapForReuseKey(reuseKey).clear()
1434
+
1425
1435
  for (const pool of Object.values(this.databasePools)) {
1426
1436
  if (pool.getConfigurationReuseKey() === reuseKey) {
1427
1437
  pool.clearSchemaCache()
@@ -1438,6 +1448,22 @@ export default class VelociousConfiguration {
1438
1448
  return this._schemaCacheGenerationsByReuseKey.get(reuseKey) || 0
1439
1449
  }
1440
1450
 
1451
+ /**
1452
+ * Returns the schema-metadata cache map shared by every connection to one physical database, creating it on first use.
1453
+ * @param {string} reuseKey - Connection reuse key identifying the physical database.
1454
+ * @returns {Map<string, Promise<ReturnType<typeof JSON.parse>>>} - Shared schema metadata cache map.
1455
+ */
1456
+ schemaCacheMapForReuseKey(reuseKey) {
1457
+ let schemaCacheMap = this._schemaCacheMapsByReuseKey.get(reuseKey)
1458
+
1459
+ if (!schemaCacheMap) {
1460
+ schemaCacheMap = new Map()
1461
+ this._schemaCacheMapsByReuseKey.set(reuseKey, schemaCacheMap)
1462
+ }
1463
+
1464
+ return schemaCacheMap
1465
+ }
1466
+
1441
1467
  /**
1442
1468
  * Invalidates record metadata owned by one closed/deleted physical tenant
1443
1469
  * database while preserving every other tenant generation.
@@ -0,0 +1,25 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * Database names that may be interpolated into CREATE/DROP DATABASE DDL:
5
+ * plain lowercase identifiers only. Anything else (quotes, semicolons,
6
+ * wildcards, dots) is rejected before a statement is built, so every
7
+ * database-level helper operates on one explicitly named database and a
8
+ * name can never smuggle a pattern sweep or statement injection.
9
+ */
10
+ const SAFE_DATABASE_NAME = /^[a-z0-9_]+$/
11
+
12
+ /**
13
+ * Validates a database name against the strict allowlist before it is
14
+ * interpolated into DDL.
15
+ * @param {string | null | undefined} databaseName - Candidate database name.
16
+ * @param {string} operation - Operation name used in the rejection message.
17
+ * @returns {string} - The validated database name.
18
+ */
19
+ export function safeDatabaseName(databaseName, operation) {
20
+ if (!databaseName || !SAFE_DATABASE_NAME.test(databaseName)) {
21
+ throw new Error(`Unsafe database name for ${operation}: ${databaseName}`)
22
+ }
23
+
24
+ return databaseName
25
+ }
@@ -339,6 +339,8 @@ export default class VelociousDatabaseDriversBase {
339
339
  * Narrows the runtime value to the documented type.
340
340
  * @type {(() => void) | undefined} */
341
341
  _schemaCacheInvalidator
342
+ /** @type {(() => Map<string, Promise<ReturnType<typeof JSON.parse>>>) | undefined} */
343
+ _schemaCacheMapProvider
342
344
  /**
343
345
  * Narrows the runtime value to the documented type.
344
346
  * @type {string | undefined} */
@@ -803,7 +805,7 @@ export default class VelociousDatabaseDriversBase {
803
805
  * @returns {void} - No return value.
804
806
  */
805
807
  _clearLocalSchemaCache() {
806
- this._schemaCache.clear()
808
+ this._schemaCacheMap().clear()
807
809
  }
808
810
 
809
811
  /**
@@ -815,6 +817,25 @@ export default class VelociousDatabaseDriversBase {
815
817
  this._schemaCacheInvalidator = invalidator
816
818
  }
817
819
 
820
+ /**
821
+ * Runs set schema cache map provider.
822
+ * @param {() => Map<string, Promise<ReturnType<typeof JSON.parse>>>} provider - Returns the schema-metadata cache map shared by every connection to this driver's physical database.
823
+ * @returns {void} - No return value.
824
+ */
825
+ setSchemaCacheMapProvider(provider) {
826
+ this._schemaCacheMapProvider = provider
827
+ }
828
+
829
+ /**
830
+ * Returns the schema-metadata cache map: the configuration-owned map shared by every connection to the same physical database when the pool stamped a reuse key, otherwise this instance's own map. Sharing survives pool connection churn (idle reaping, pool maximums) so a re-spawned connection does not re-introspect every table.
831
+ * @returns {Map<string, Promise<ReturnType<typeof JSON.parse>>>} - The schema metadata cache map.
832
+ */
833
+ _schemaCacheMap() {
834
+ if (this._schemaCacheMapProvider) return this._schemaCacheMapProvider()
835
+
836
+ return this._schemaCache
837
+ }
838
+
818
839
  /**
819
840
  * Runs schema cache enabled.
820
841
  * @returns {boolean} - Whether schema metadata caching is enabled.
@@ -879,7 +900,8 @@ export default class VelociousDatabaseDriversBase {
879
900
  async _cachedSchemaMetadata(cacheKey, callback) {
880
901
  if (!this._schemaCacheEnabled()) return await this._withSchemaMetadataDdlRetry(callback)
881
902
 
882
- const existingPromise = this._schemaCache.get(cacheKey)
903
+ const schemaCache = this._schemaCacheMap()
904
+ const existingPromise = schemaCache.get(cacheKey)
883
905
 
884
906
  if (existingPromise) {
885
907
  return /** @type {T} */ (this._schemaCacheReturnValue(await existingPromise))
@@ -887,13 +909,13 @@ export default class VelociousDatabaseDriversBase {
887
909
 
888
910
  const promise = (async () => await this._withSchemaMetadataDdlRetry(callback))()
889
911
 
890
- this._schemaCache.set(cacheKey, promise)
912
+ schemaCache.set(cacheKey, promise)
891
913
 
892
914
  try {
893
915
  return /** @type {T} */ (this._schemaCacheReturnValue(await promise))
894
916
  } catch (error) {
895
- if (this._schemaCache.get(cacheKey) === promise) {
896
- this._schemaCache.delete(cacheKey)
917
+ if (schemaCache.get(cacheKey) === promise) {
918
+ schemaCache.delete(cacheKey)
897
919
  }
898
920
 
899
921
  throw error
@@ -924,7 +946,7 @@ export default class VelociousDatabaseDriversBase {
924
946
  seedTableSchemaMetadata(tableName, metadataName, value) {
925
947
  if (!this._schemaCacheEnabled()) return
926
948
 
927
- this._schemaCache.set(`table:${tableName}:${metadataName}`, Promise.resolve(value))
949
+ this._schemaCacheMap().set(`table:${tableName}:${metadataName}`, Promise.resolve(value))
928
950
  }
929
951
 
930
952
  /**
@@ -939,11 +961,11 @@ export default class VelociousDatabaseDriversBase {
939
961
  if (!this._schemaCacheEnabled()) return
940
962
  if (tables.length === 0) return
941
963
 
942
- const batchedColumns = await this.batchTableColumns(tables)
964
+ const batchedColumnRows = await this.batchTableColumns(tables)
943
965
 
944
- if (batchedColumns) {
945
- for (const [tableName, columns] of batchedColumns) {
946
- this.seedTableSchemaMetadata(tableName, "columns", columns)
966
+ if (batchedColumnRows) {
967
+ for (const [tableName, columnRows] of batchedColumnRows) {
968
+ this.seedTableSchemaMetadata(tableName, "columns", columnRows)
947
969
  }
948
970
 
949
971
  return
@@ -963,7 +985,7 @@ export default class VelociousDatabaseDriversBase {
963
985
  * answer for several tables in one statement return null, leaving the caller to
964
986
  * read them per table.
965
987
  * @param {Array<import("./base-table.js").default>} tables - Tables to load columns for.
966
- * @returns {Promise<Map<string, Array<import("./base-column.js").default>> | null>} - Columns keyed by table name, or null when unsupported.
988
+ * @returns {Promise<Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>> | null>} - Raw column rows keyed by table name, or null when unsupported.
967
989
  */
968
990
  async batchTableColumns(tables) {
969
991
  void tables
@@ -1515,6 +1537,32 @@ export default class VelociousDatabaseDriversBase {
1515
1537
  return false
1516
1538
  }
1517
1539
 
1540
+ /**
1541
+ * Lists the database names visible from this connection, so callers never
1542
+ * issue `SHOW DATABASES`-style raw SQL through the driver. The listing is
1543
+ * read-only and never filters by name pattern — callers decide what to do
1544
+ * with the exact names.
1545
+ * @abstract
1546
+ * @returns {Promise<string[]>} - Resolves with the database names.
1547
+ */
1548
+ listDatabases() {
1549
+ throw new Error(`'listDatabases' not implemented for ${this.constructor.name}`)
1550
+ }
1551
+
1552
+ /**
1553
+ * Whether one exact database name exists in this connection's listing.
1554
+ * Exact comparison only — never a name-pattern sweep.
1555
+ * @param {string} databaseName - Exact database name to look for.
1556
+ * @returns {Promise<boolean>} - Resolves with whether the database exists.
1557
+ */
1558
+ async databaseExists(databaseName) {
1559
+ if (!databaseName) throw new Error("databaseExists requires an exact database name")
1560
+
1561
+ const databases = await this.listDatabases()
1562
+
1563
+ return databases.some((name) => name == databaseName)
1564
+ }
1565
+
1518
1566
  /**
1519
1567
  * Runs a callback inside a database transaction (or a savepoint when already inside one).
1520
1568
  * The outermost transaction retries the whole callback on a deadlock / lock-wait-timeout,
@@ -2339,7 +2387,7 @@ export default class VelociousDatabaseDriversBase {
2339
2387
  driverClass: this.constructor.name,
2340
2388
  idSeq: this.idSeq,
2341
2389
  openTransactions: this._transactionsCount,
2342
- schemaCacheEntries: this._schemaCache.size
2390
+ schemaCacheEntries: this._schemaCacheMap().size
2343
2391
  }
2344
2392
  }
2345
2393
 
@@ -2,7 +2,6 @@
2
2
 
3
3
  import AlterTable from "./sql/alter-table.js"
4
4
  import Base from "../base.js"
5
- import Column from "./column.js"
6
5
  import CreateDatabase from "./sql/create-database.js"
7
6
  import CreateIndex from "./sql/create-index.js"
8
7
  import CreateTable from "./sql/create-table.js"
@@ -499,22 +498,32 @@ export default class VelociousDatabaseDriversMssql extends Base{
499
498
  * @returns {Promise<Array<import("../base-table.js").default>>} - Resolves with the tables.
500
499
  */
501
500
  async getTables() {
502
- return await this._cachedSchemaMetadata("tables", async () => {
501
+ const tableRows = await this._cachedSchemaMetadata("tables", async () => {
503
502
  const schema = this.getArgs()?.schema || this.getArgs()?.sqlConfig?.options?.schema
504
503
  const schemaClause = schema
505
504
  ? ` AND [TABLE_SCHEMA] = ${this.quote(schema)}`
506
505
  : " AND [TABLE_SCHEMA] = SCHEMA_NAME()"
507
- const result = await this.query(`SELECT [TABLE_NAME] FROM [INFORMATION_SCHEMA].[TABLES] WHERE [TABLE_CATALOG] = DB_NAME()${schemaClause}`)
508
- const tables = []
506
+ return await this.query(`SELECT [TABLE_NAME] FROM [INFORMATION_SCHEMA].[TABLES] WHERE [TABLE_CATALOG] = DB_NAME()${schemaClause}`)
507
+ })
508
+ const tables = []
509
509
 
510
- for (const row of result) {
511
- const table = new Table(this, /** @type {Record<string, string>} */ (row))
510
+ for (const row of tableRows) {
511
+ const table = new Table(this, /** @type {Record<string, string>} */ (row))
512
512
 
513
- tables.push(table)
514
- }
513
+ tables.push(table)
514
+ }
515
515
 
516
- return tables
517
- })
516
+ return tables
517
+ }
518
+
519
+ /**
520
+ * Lists database names visible to this server connection from `sys.databases`.
521
+ * @returns {Promise<string[]>} - Resolves with the database names.
522
+ */
523
+ async listDatabases() {
524
+ const result = await this.query("SELECT [name] FROM [sys].[databases] ORDER BY [name]")
525
+
526
+ return result.map((row) => String(row.name))
518
527
  }
519
528
 
520
529
  /**
@@ -523,13 +532,13 @@ export default class VelociousDatabaseDriversMssql extends Base{
523
532
  * does against the legacy SQL Server, so it is worth combining regardless of the
524
533
  * number of tables.
525
534
  * @param {Array<import("../base-table.js").default>} tables - Tables to load columns for.
526
- * @returns {Promise<Map<string, Array<import("../base-column.js").default>>>} - Columns keyed by table name.
535
+ * @returns {Promise<Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>>} - Raw column rows keyed by table name.
527
536
  */
528
537
  async batchTableColumns(tables) {
529
- /** @type {Map<string, Array<import("../base-column.js").default>>} */
530
- const columnsByTable = new Map()
538
+ /** @type {Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>} */
539
+ const rowsByTable = new Map()
531
540
 
532
- if (tables.length === 0) return columnsByTable
541
+ if (tables.length === 0) return rowsByTable
533
542
 
534
543
  const schema = this.getArgs()?.schema || this.getArgs()?.sqlConfig?.options?.schema
535
544
  const schemaClause = schema
@@ -566,13 +575,13 @@ export default class VelociousDatabaseDriversMssql extends Base{
566
575
 
567
576
  if (!table) continue
568
577
 
569
- const columns = columnsByTable.get(tableName) || []
578
+ const tableRows = rowsByTable.get(tableName) || []
570
579
 
571
- columns.push(new Column(table, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)))
572
- columnsByTable.set(tableName, columns)
580
+ tableRows.push(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row))
581
+ rowsByTable.set(tableName, tableRows)
573
582
  }
574
583
 
575
- return columnsByTable
584
+ return rowsByTable
576
585
  }
577
586
 
578
587
  /**
@@ -64,7 +64,7 @@ export default class VelociousDatabaseDriversMssqlTable extends BaseTable {
64
64
  }
65
65
 
66
66
  async getColumns() {
67
- return await this.getDriver()._cachedTableSchemaMetadata(this.getName(), "columns", async () => {
67
+ const columnRows = await this.getDriver()._cachedTableSchemaMetadata(this.getName(), "columns", async () => {
68
68
  const result = await this.driver.query(`
69
69
  SELECT
70
70
  columns.*,
@@ -86,20 +86,21 @@ export default class VelociousDatabaseDriversMssqlTable extends BaseTable {
86
86
  keyColumnUsage.COLUMN_NAME = columns.COLUMN_NAME
87
87
  WHERE columns.TABLE_NAME = ${this.driver.quote(this.getName())}
88
88
  `)
89
- const columns = []
89
+ return result
90
+ })
91
+ const columns = []
90
92
 
91
- for (const data of result) {
92
- const column = new Column(this, data)
93
+ for (const data of columnRows) {
94
+ const column = new Column(this, data)
93
95
 
94
- columns.push(column)
95
- }
96
+ columns.push(column)
97
+ }
96
98
 
97
- return columns
98
- })
99
+ return columns
99
100
  }
100
101
 
101
102
  async getForeignKeys() {
102
- return await this.getDriver()._cachedTableSchemaMetadata(this.getName(), "foreignKeys", async () => {
103
+ const foreignKeyRows = await this.getDriver()._cachedTableSchemaMetadata(this.getName(), "foreignKeys", async () => {
103
104
  const sql = `
104
105
  SELECT
105
106
  fk.name AS CONSTRAINT_NAME,
@@ -125,21 +126,21 @@ export default class VelociousDatabaseDriversMssqlTable extends BaseTable {
125
126
  ORDER BY CONSTRAINT_NAME, ParentTable, ReferencedTable;
126
127
  `
127
128
 
128
- const foreignKeyRows = await this.driver.query(sql)
129
- const foreignKeys = []
129
+ return await this.driver.query(sql)
130
+ })
131
+ const foreignKeys = []
130
132
 
131
- for (const foreignKeyRow of foreignKeyRows) {
132
- const foreignKey = new ForeignKey(foreignKeyRow)
133
+ for (const foreignKeyRow of foreignKeyRows) {
134
+ const foreignKey = new ForeignKey(foreignKeyRow)
133
135
 
134
- foreignKeys.push(foreignKey)
135
- }
136
+ foreignKeys.push(foreignKey)
137
+ }
136
138
 
137
- return foreignKeys
138
- })
139
+ return foreignKeys
139
140
  }
140
141
 
141
142
  async getIndexes() {
142
- return await this.getDriver()._cachedTableSchemaMetadata(this.getName(), "indexes", async () => {
143
+ const groupedIndexRows = await this.getDriver()._cachedTableSchemaMetadata(this.getName(), "indexes", async () => {
143
144
  const options = this.getOptions()
144
145
  const sql = `
145
146
  SELECT
@@ -161,17 +162,19 @@ export default class VelociousDatabaseDriversMssqlTable extends BaseTable {
161
162
  `
162
163
 
163
164
  const rows = await this.getDriver().query(sql)
164
- const indexes = []
165
165
  const indexRows = rows.map((row) => normalizeIndexMetadataRow(row))
166
166
 
167
- for (const indexData of groupMssqlIndexRows(indexRows)) {
168
- const index = new ColumnsIndex(this, indexData)
167
+ return groupMssqlIndexRows(indexRows)
168
+ })
169
+ const indexes = []
169
170
 
170
- indexes.push(index)
171
- }
171
+ for (const indexData of groupedIndexRows) {
172
+ const index = new ColumnsIndex(this, indexData)
172
173
 
173
- return indexes
174
- })
174
+ indexes.push(index)
175
+ }
176
+
177
+ return indexes
175
178
  }
176
179
 
177
180
  /**
@@ -2,7 +2,6 @@
2
2
 
3
3
  import AlterTable from "./sql/alter-table.js"
4
4
  import Base from "../base.js"
5
- import Column from "./column.js"
6
5
  import CreateDatabase from "./sql/create-database.js"
7
6
  import CreateIndex from "./sql/create-index.js"
8
7
  import CreateTable from "./sql/create-table.js"
@@ -779,18 +778,26 @@ export default class VelociousDatabaseDriversMysql extends Base{
779
778
  * @returns {Promise<Array<import("../base-table.js").default>>} - Resolves with the tables.
780
779
  */
781
780
  async getTables() {
782
- return await this._cachedSchemaMetadata("tables", async () => {
783
- const result = await this.query("SHOW FULL TABLES")
784
- const tables = []
781
+ const tableRows = await this._cachedSchemaMetadata("tables", async () => await this.query("SHOW FULL TABLES"))
782
+ const tables = []
785
783
 
786
- for (const row of result) {
787
- const table = new Table(this, /** @type {Record<string, string>} */ (row))
784
+ for (const row of tableRows) {
785
+ const table = new Table(this, /** @type {Record<string, string>} */ (row))
788
786
 
789
- tables.push(table)
790
- }
787
+ tables.push(table)
788
+ }
791
789
 
792
- return tables
793
- })
790
+ return tables
791
+ }
792
+
793
+ /**
794
+ * Lists database names visible to this server connection (`SHOW DATABASES`).
795
+ * @returns {Promise<string[]>} - Resolves with the database names.
796
+ */
797
+ async listDatabases() {
798
+ const result = await this.query("SHOW DATABASES")
799
+
800
+ return result.map((row) => String(Object.values(row)[0]))
794
801
  }
795
802
 
796
803
  /**
@@ -803,13 +810,13 @@ export default class VelociousDatabaseDriversMysql extends Base{
803
810
  * Verified column-for-column against `SHOW FULL COLUMNS` on a 44-table MariaDB
804
811
  * schema; the only divergence was that sentinel.
805
812
  * @param {Array<import("../base-table.js").default>} tables - Tables to load columns for.
806
- * @returns {Promise<Map<string, Array<import("../base-column.js").default>>>} - Columns keyed by table name.
813
+ * @returns {Promise<Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>>} - Raw column rows keyed by table name.
807
814
  */
808
815
  async batchTableColumns(tables) {
809
- /** @type {Map<string, Array<import("../base-column.js").default>>} */
810
- const columnsByTable = new Map()
816
+ /** @type {Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>} */
817
+ const rowsByTable = new Map()
811
818
 
812
- if (tables.length === 0) return columnsByTable
819
+ if (tables.length === 0) return rowsByTable
813
820
 
814
821
  const tablesByName = new Map(tables.map((table) => [table.getName(), table]))
815
822
  const tableNamesSql = [...tablesByName.keys()].map((tableName) => this.quote(tableName)).join(", ")
@@ -836,13 +843,13 @@ export default class VelociousDatabaseDriversMysql extends Base{
836
843
 
837
844
  row.Default = normalizeInformationSchemaDefault(row.Default)
838
845
 
839
- const columns = columnsByTable.get(tableName) || []
846
+ const tableRows = rowsByTable.get(tableName) || []
840
847
 
841
- columns.push(new Column(table, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)))
842
- columnsByTable.set(tableName, columns)
848
+ tableRows.push(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row))
849
+ rowsByTable.set(tableName, tableRows)
843
850
  }
844
851
 
845
- return columnsByTable
852
+ return rowsByTable
846
853
  }
847
854
 
848
855
  /**