velocious 1.0.726 → 1.0.728

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 (155) 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-types.js +1 -1
  9. package/build/configuration.js +43 -2
  10. package/build/database/advisory-lock-lock-server-backend.js +30 -24
  11. package/build/database/advisory-lock-lock-server-embedded-client.js +74 -0
  12. package/build/database/advisory-lock-lock-server-engine.js +544 -0
  13. package/build/database/advisory-lock-lock-server-local-client.js +260 -0
  14. package/build/database/advisory-lock-lock-server-socket-path.js +17 -0
  15. package/build/database/advisory-lock-lock-server-transport.js +30 -0
  16. package/build/database/drivers/base.js +34 -12
  17. package/build/database/drivers/mssql/index.js +17 -18
  18. package/build/database/drivers/mssql/table.js +28 -25
  19. package/build/database/drivers/mysql/index.js +15 -18
  20. package/build/database/drivers/mysql/table.js +31 -23
  21. package/build/database/drivers/pgsql/index.js +15 -18
  22. package/build/database/drivers/pgsql/table.js +28 -26
  23. package/build/database/drivers/sqlite/base.js +7 -9
  24. package/build/database/drivers/sqlite/table.js +32 -26
  25. package/build/database/pool/async-tracked-multi-connection.js +1 -0
  26. package/build/database/pool/base.js +14 -4
  27. package/build/database/pool/single-multi-use.js +1 -0
  28. package/build/database/record/auditing.js +89 -11
  29. package/build/database/record/index.js +1 -1
  30. package/build/environment-handlers/base.js +50 -9
  31. package/build/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
  32. package/build/environment-handlers/node/cli/commands/server.js +1 -0
  33. package/build/environment-handlers/node.js +30 -3
  34. package/build/http-server/server-lock.js +55 -18
  35. package/build/src/application.d.ts +7 -4
  36. package/build/src/application.d.ts.map +1 -1
  37. package/build/src/application.js +27 -4
  38. package/build/src/background-jobs/main.d.ts +2 -1
  39. package/build/src/background-jobs/main.d.ts.map +1 -1
  40. package/build/src/background-jobs/main.js +10 -2
  41. package/build/src/background-jobs/worker.d.ts +42 -0
  42. package/build/src/background-jobs/worker.d.ts.map +1 -1
  43. package/build/src/background-jobs/worker.js +61 -5
  44. package/build/src/cli/process-args.d.ts +11 -0
  45. package/build/src/cli/process-args.d.ts.map +1 -0
  46. package/build/src/cli/process-args.js +34 -0
  47. package/build/src/configuration-types.d.ts +3 -1
  48. package/build/src/configuration-types.d.ts.map +1 -1
  49. package/build/src/configuration-types.js +2 -2
  50. package/build/src/configuration.d.ts +16 -1
  51. package/build/src/configuration.d.ts.map +1 -1
  52. package/build/src/configuration.js +39 -3
  53. package/build/src/database/advisory-lock-lock-server-backend.d.ts +10 -3
  54. package/build/src/database/advisory-lock-lock-server-backend.d.ts.map +1 -1
  55. package/build/src/database/advisory-lock-lock-server-backend.js +25 -22
  56. package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts +24 -0
  57. package/build/src/database/advisory-lock-lock-server-embedded-client.d.ts.map +1 -0
  58. package/build/src/database/advisory-lock-lock-server-embedded-client.js +64 -0
  59. package/build/src/database/advisory-lock-lock-server-engine.d.ts +285 -0
  60. package/build/src/database/advisory-lock-lock-server-engine.d.ts.map +1 -0
  61. package/build/src/database/advisory-lock-lock-server-engine.js +460 -0
  62. package/build/src/database/advisory-lock-lock-server-local-client.d.ts +114 -0
  63. package/build/src/database/advisory-lock-lock-server-local-client.d.ts.map +1 -0
  64. package/build/src/database/advisory-lock-lock-server-local-client.js +227 -0
  65. package/build/src/database/advisory-lock-lock-server-socket-path.d.ts +9 -0
  66. package/build/src/database/advisory-lock-lock-server-socket-path.d.ts.map +1 -0
  67. package/build/src/database/advisory-lock-lock-server-socket-path.js +16 -0
  68. package/build/src/database/advisory-lock-lock-server-transport.d.ts +18 -0
  69. package/build/src/database/advisory-lock-lock-server-transport.d.ts.map +1 -0
  70. package/build/src/database/advisory-lock-lock-server-transport.js +27 -0
  71. package/build/src/database/drivers/base.d.ts +15 -2
  72. package/build/src/database/drivers/base.d.ts.map +1 -1
  73. package/build/src/database/drivers/base.js +33 -13
  74. package/build/src/database/drivers/mssql/index.d.ts +2 -2
  75. package/build/src/database/drivers/mssql/index.d.ts.map +1 -1
  76. package/build/src/database/drivers/mssql/index.js +17 -18
  77. package/build/src/database/drivers/mssql/table.d.ts.map +1 -1
  78. package/build/src/database/drivers/mssql/table.js +25 -23
  79. package/build/src/database/drivers/mysql/index.d.ts +2 -2
  80. package/build/src/database/drivers/mysql/index.d.ts.map +1 -1
  81. package/build/src/database/drivers/mysql/index.js +16 -19
  82. package/build/src/database/drivers/mysql/table.d.ts.map +1 -1
  83. package/build/src/database/drivers/mysql/table.js +27 -22
  84. package/build/src/database/drivers/pgsql/index.d.ts +2 -2
  85. package/build/src/database/drivers/pgsql/index.d.ts.map +1 -1
  86. package/build/src/database/drivers/pgsql/index.js +16 -19
  87. package/build/src/database/drivers/pgsql/table.d.ts.map +1 -1
  88. package/build/src/database/drivers/pgsql/table.js +25 -23
  89. package/build/src/database/drivers/sqlite/base.d.ts.map +1 -1
  90. package/build/src/database/drivers/sqlite/base.js +8 -10
  91. package/build/src/database/drivers/sqlite/table.d.ts.map +1 -1
  92. package/build/src/database/drivers/sqlite/table.js +29 -25
  93. package/build/src/database/pool/async-tracked-multi-connection.d.ts.map +1 -1
  94. package/build/src/database/pool/async-tracked-multi-connection.js +2 -1
  95. package/build/src/database/pool/base.d.ts +6 -0
  96. package/build/src/database/pool/base.d.ts.map +1 -1
  97. package/build/src/database/pool/base.js +14 -5
  98. package/build/src/database/pool/single-multi-use.d.ts.map +1 -1
  99. package/build/src/database/pool/single-multi-use.js +2 -1
  100. package/build/src/database/record/auditing.d.ts +14 -4
  101. package/build/src/database/record/auditing.d.ts.map +1 -1
  102. package/build/src/database/record/auditing.js +77 -12
  103. package/build/src/database/record/index.d.ts +4 -2
  104. package/build/src/database/record/index.d.ts.map +1 -1
  105. package/build/src/database/record/index.js +2 -2
  106. package/build/src/environment-handlers/base.d.ts +86 -7
  107. package/build/src/environment-handlers/base.d.ts.map +1 -1
  108. package/build/src/environment-handlers/base.js +48 -9
  109. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts +2 -0
  110. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.d.ts.map +1 -0
  111. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +179 -0
  112. package/build/src/environment-handlers/node/cli/commands/server.d.ts.map +1 -1
  113. package/build/src/environment-handlers/node/cli/commands/server.js +2 -1
  114. package/build/src/environment-handlers/node.d.ts +10 -4
  115. package/build/src/environment-handlers/node.d.ts.map +1 -1
  116. package/build/src/environment-handlers/node.js +30 -4
  117. package/build/src/http-server/server-lock.d.ts +43 -14
  118. package/build/src/http-server/server-lock.d.ts.map +1 -1
  119. package/build/src/http-server/server-lock.js +54 -19
  120. package/build/src/tenants/default-tenant-database-provisioning.d.ts.map +1 -1
  121. package/build/src/tenants/default-tenant-database-provisioning.js +7 -1
  122. package/build/tenants/default-tenant-database-provisioning.js +8 -0
  123. package/package.json +2 -2
  124. package/src/application.js +32 -3
  125. package/src/background-jobs/main.js +9 -1
  126. package/src/background-jobs/worker.js +69 -6
  127. package/src/cli/process-args.js +34 -0
  128. package/src/configuration-types.js +1 -1
  129. package/src/configuration.js +43 -2
  130. package/src/database/advisory-lock-lock-server-backend.js +30 -24
  131. package/src/database/advisory-lock-lock-server-embedded-client.js +74 -0
  132. package/src/database/advisory-lock-lock-server-engine.js +544 -0
  133. package/src/database/advisory-lock-lock-server-local-client.js +260 -0
  134. package/src/database/advisory-lock-lock-server-socket-path.js +17 -0
  135. package/src/database/advisory-lock-lock-server-transport.js +30 -0
  136. package/src/database/drivers/base.js +34 -12
  137. package/src/database/drivers/mssql/index.js +17 -18
  138. package/src/database/drivers/mssql/table.js +28 -25
  139. package/src/database/drivers/mysql/index.js +15 -18
  140. package/src/database/drivers/mysql/table.js +31 -23
  141. package/src/database/drivers/pgsql/index.js +15 -18
  142. package/src/database/drivers/pgsql/table.js +28 -26
  143. package/src/database/drivers/sqlite/base.js +7 -9
  144. package/src/database/drivers/sqlite/table.js +32 -26
  145. package/src/database/pool/async-tracked-multi-connection.js +1 -0
  146. package/src/database/pool/base.js +14 -4
  147. package/src/database/pool/single-multi-use.js +1 -0
  148. package/src/database/record/auditing.js +89 -11
  149. package/src/database/record/index.js +1 -1
  150. package/src/environment-handlers/base.js +50 -9
  151. package/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +206 -0
  152. package/src/environment-handlers/node/cli/commands/server.js +1 -0
  153. package/src/environment-handlers/node.js +30 -3
  154. package/src/http-server/server-lock.js +55 -18
  155. package/src/tenants/default-tenant-database-provisioning.js +8 -0
@@ -0,0 +1,260 @@
1
+ // @ts-check
2
+
3
+ import net from "node:net"
4
+ import {spawn} from "node:child_process"
5
+ import {fileURLToPath} from "node:url"
6
+
7
+ /**
8
+ * Unix-domain-socket transport client for the `local` lock-server mode
9
+ * (STC-715). It connects to the local engine server
10
+ * (`src/environment-handlers/node/advisory-lock-lock-server-local-server.js`)
11
+ * over a Unix socket — no listening network port, no `ws` — and spawns that
12
+ * server as a child of this environment when no local engine is running yet.
13
+ *
14
+ * One local engine serves every process on the host that points at the same
15
+ * socket path, which is what makes `local` mode the multi-process single-host
16
+ * answer (embedded mode only coordinates inside one JS realm).
17
+ *
18
+ * Crash detection and bounded restart: when the socket dies, the transport
19
+ * reports `transportClosed` to the backend adapter, which fails pending
20
+ * requests and starts its `reprobeCooldownMs` unavailability cache. The next
21
+ * acquisition after the cooldown reconnects — respawning the engine child when
22
+ * the socket file is gone. The cooldown IS the restart backoff; there is no
23
+ * separate respawn loop.
24
+ */
25
+ export default class AdvisoryLockLockServerLocalClient {
26
+ /**
27
+ * Creates the local transport client. No socket or process is touched until
28
+ * `connect()` — constructing this object performs no I/O.
29
+ * @param {object} args - Client options.
30
+ * @param {string} [args.authToken] - Shared secret forwarded in the hello params.
31
+ * @param {number} [args.connectTimeoutMs] - Bounded wait for the socket/engine child to become ready.
32
+ * @param {number} [args.leaseMs] - Lease duration the engine child should use.
33
+ * @param {string} args.socketPath - Unix socket path of the local engine.
34
+ */
35
+ constructor({authToken = "", connectTimeoutMs = 3000, leaseMs = 30_000, socketPath}) {
36
+ this.authToken = authToken
37
+ this.connectTimeoutMs = connectTimeoutMs
38
+ this.leaseMs = leaseMs
39
+ this.socketPath = socketPath
40
+ this.connectionId = `client-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
41
+ /** @type {net.Socket | null} */
42
+ this.socket = null
43
+ /** @type {((body: Record<string, unknown>) => void) | null} */
44
+ this.onMessage = null
45
+ /** @type {import("node:child_process").ChildProcess | null} */
46
+ this.spawnedChild = null
47
+ this.closed = false
48
+ this.dead = false
49
+ this.stdoutBuffer = ""
50
+ }
51
+
52
+ /**
53
+ * Connects to the local engine, spawning the engine child when the socket is
54
+ * not there yet.
55
+ * @returns {Promise<void>} - Resolves once the socket is connected.
56
+ */
57
+ async connect() {
58
+ if (this.socket) return
59
+
60
+ try {
61
+ await this.openSocket()
62
+
63
+ return
64
+ } catch (error) {
65
+ if (!this.socketMissingError(error)) throw error
66
+
67
+ // No engine is listening (missing socket, or a stale socket file left by
68
+ // a crashed engine): spawn the engine child and poll until it is live.
69
+ this.spawnEngineChild()
70
+
71
+ const deadline = Date.now() + this.connectTimeoutMs
72
+
73
+ while (true) {
74
+ try {
75
+ await this.openSocket()
76
+
77
+ return
78
+ } catch (retryError) {
79
+ if (!this.socketMissingError(retryError)) throw retryError
80
+
81
+ if (Date.now() >= deadline) throw new Error(`Local lock server did not start at ${this.socketPath}`, {cause: retryError})
82
+
83
+ await new Promise((resolve) => setTimeout(resolve, 25))
84
+ }
85
+ }
86
+ }
87
+ }
88
+
89
+ /**
90
+ * Opens the 1:1 view of the socket connection (one connection per
91
+ * transport, like the websocket adapter).
92
+ * @param {string} _type - Connection role (`lock`).
93
+ * @param {{onMessage: (body: Record<string, unknown>) => void, params: Record<string, unknown>}} args - Connection options.
94
+ * @returns {{ready: Promise<void>, sendMessage: (body: Record<string, unknown>) => void, close: () => void}} - Connection handle.
95
+ */
96
+ openConnection(_type, args) {
97
+ this.onMessage = args.onMessage
98
+
99
+ // The connection-open frame carries auth and protocol version; the engine
100
+ // answers it with a hello-ack, exactly like the external daemon does over
101
+ // the websocket transport.
102
+ this.writeLine({connectionId: this.connectionId, params: args.params, type: "hello"})
103
+
104
+ return {
105
+ close: () => this.close(),
106
+ ready: Promise.resolve(),
107
+ sendMessage: (/** @type {Record<string, unknown>} */ body) => this.writeLine(body)
108
+ }
109
+ }
110
+
111
+ /**
112
+ * Closes the socket and stops an engine child this client spawned. A child
113
+ * it did not spawn keeps serving the other processes on the host and idles
114
+ * out on its own once its last connection closes.
115
+ * @returns {void}
116
+ */
117
+ close() {
118
+ this.closed = true
119
+
120
+ const socket = this.socket
121
+
122
+ this.socket = null
123
+ socket?.end()
124
+ socket?.destroy()
125
+
126
+ const child = this.spawnedChild
127
+
128
+ this.spawnedChild = null
129
+ child?.kill("SIGTERM")
130
+ }
131
+
132
+ /**
133
+ * Opens the Unix socket and wires the line protocol.
134
+ * @returns {Promise<void>} - Resolves when connected.
135
+ */
136
+ openSocket() {
137
+ return new Promise((resolve, reject) => {
138
+ const socket = net.connect(this.socketPath)
139
+
140
+ const timer = setTimeout(() => {
141
+ socket.destroy()
142
+ reject(new Error(`Timed out connecting to the local lock server at ${this.socketPath}`))
143
+ }, this.connectTimeoutMs)
144
+
145
+ timer.unref?.()
146
+
147
+ socket.once("connect", () => {
148
+ clearTimeout(timer)
149
+ this.socket = socket
150
+ this.dead = false
151
+ resolve()
152
+ })
153
+
154
+ socket.once("error", (/** @type {Error} */ error) => {
155
+ clearTimeout(timer)
156
+
157
+ if (this.socket === socket) this.socket = null
158
+
159
+ reject(error)
160
+ })
161
+
162
+ socket.setEncoding("utf8")
163
+ socket.on("data", (/** @type {string} */ chunk) => this.handleSocketChunk(chunk))
164
+ socket.on("close", () => this.handleTransportDeath(new Error("Local lock server socket closed")))
165
+ })
166
+ }
167
+
168
+ /**
169
+ * Spawns the local engine server as a child of this environment.
170
+ * @returns {void}
171
+ */
172
+ spawnEngineChild() {
173
+ if (this.spawnedChild) return
174
+
175
+ const serverModulePath = fileURLToPath(new URL("../environment-handlers/node/advisory-lock-lock-server-local-server.js", import.meta.url))
176
+ const child = spawn(process.execPath, [serverModulePath], {
177
+ env: {
178
+ ...process.env,
179
+ CONSENS_LOCK_LEASE_MS: String(this.leaseMs),
180
+ VELOCIOUS_LOCK_SERVER_SOCKET_PATH: this.socketPath
181
+ },
182
+ stdio: ["ignore", "ignore", "ignore"]
183
+ })
184
+
185
+ child.on("error", () => {
186
+ // A failed spawn surfaces as a connect failure on the next socket wait.
187
+ })
188
+ child.unref()
189
+ this.spawnedChild = child
190
+ }
191
+
192
+ /**
193
+ * Writes one protocol message as a JSON line to the socket.
194
+ * @param {Record<string, unknown>} body - Message to send.
195
+ * @returns {void}
196
+ */
197
+ writeLine(body) {
198
+ const socket = this.socket
199
+
200
+ if (!socket || this.dead) throw new Error("Local lock server connection is not open")
201
+
202
+ socket.write(`${JSON.stringify({...body, connectionId: this.connectionId})}\n`)
203
+ }
204
+
205
+ /**
206
+ * Buffers socket data and dispatches complete JSON lines to the message
207
+ * handler.
208
+ * @param {string} chunk - Raw socket chunk.
209
+ * @returns {void}
210
+ */
211
+ handleSocketChunk(chunk) {
212
+ this.stdoutBuffer += chunk
213
+
214
+ let newlineIndex = this.stdoutBuffer.indexOf("\n")
215
+
216
+ while (newlineIndex >= 0) {
217
+ const line = this.stdoutBuffer.slice(0, newlineIndex)
218
+
219
+ this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1)
220
+
221
+ if (line.trim()) {
222
+ try {
223
+ const parsed = /** @type {Record<string, unknown>} */ (JSON.parse(line))
224
+
225
+ this.onMessage?.(parsed)
226
+ } catch {
227
+ // A malformed engine line is not a lock answer: the adapter's
228
+ // request timeout surfaces it loudly instead of guessing.
229
+ }
230
+ }
231
+
232
+ newlineIndex = this.stdoutBuffer.indexOf("\n")
233
+ }
234
+ }
235
+
236
+ /**
237
+ * Reports transport death to the adapter (crash detection).
238
+ * @param {Error} error - Death reason.
239
+ * @returns {void}
240
+ */
241
+ handleTransportDeath(error) {
242
+ if (this.dead || this.closed) return
243
+
244
+ this.dead = true
245
+ this.socket = null
246
+
247
+ this.onMessage?.({error: error.message, status: "transport-closed", transportClosed: true, type: "response"})
248
+ }
249
+
250
+ /**
251
+ * Whether a connect failure means "no engine is listening yet" (spawn it).
252
+ * @param {unknown} error - Connect error.
253
+ * @returns {boolean} - True for ENOENT / ECONNREFUSED on a missing socket.
254
+ */
255
+ socketMissingError(error) {
256
+ const code = /** @type {{code?: string}} */ (error || {}).code
257
+
258
+ return code === "ENOENT" || code === "ECONNREFUSED"
259
+ }
260
+ }
@@ -0,0 +1,17 @@
1
+ // @ts-check
2
+
3
+ import os from "node:os"
4
+ import path from "node:path"
5
+
6
+ /**
7
+ * Default Unix-socket path for the `local` lock-server mode (STC-715). Kept
8
+ * short on purpose: Unix socket paths are limited to ~104 characters, and a
9
+ * long scratch TMPDIR makes `net.connect` fail with `EINVAL`.
10
+ * @param {string} [configuredPath] - Explicit `advisoryLocks.backends.lockServer.socketPath`.
11
+ * @returns {string} - Socket path for the local lock-server engine.
12
+ */
13
+ export function defaultLockServerSocketPath(configuredPath) {
14
+ if (typeof configuredPath === "string" && configuredPath) return configuredPath
15
+
16
+ return path.join(os.tmpdir(), "velocious-lock-server.sock")
17
+ }
@@ -0,0 +1,30 @@
1
+ // @ts-check
2
+
3
+ import WebSocket from "ws"
4
+
5
+ import VelociousWebsocketClient from "../http-client/websocket-client.js"
6
+
7
+ /**
8
+ * Default external transport factory for the lock-server backend: the
9
+ * framework websocket client with the Node `ws` implementation bound explicitly
10
+ * (no global mutation).
11
+ *
12
+ * This module is Node-only on purpose (STC-715): the `ws` dependency lives here
13
+ * instead of inside `advisory-lock-lock-server-backend.js`, so the backend
14
+ * module itself is transport-agnostic and browser/Expo bundles can statically
15
+ * import it for the embedded mode without pulling `ws` or Node builtins into
16
+ * the graph.
17
+ * @param {{authToken: string, url: string}} args - Connection args.
18
+ * @returns {import("./advisory-lock-lock-server-backend.js").LockServerClientLike} - Websocket client.
19
+ */
20
+ export function createLockServerWebsocketTransport({url}) {
21
+ // Node's global WebSocket is not guaranteed to exist, so the implementation is
22
+ // bound explicitly instead of mutating `globalThis`.
23
+ const webSocketImplementation = /** @type {typeof globalThis.WebSocket} */ (/** @type {unknown} */ (WebSocket))
24
+
25
+ return /** @type {import("./advisory-lock-lock-server-backend.js").LockServerClientLike} */ (/** @type {unknown} */ (new VelociousWebsocketClient({
26
+ heartbeatIntervalMs: 10_000,
27
+ url,
28
+ webSocketImplementation
29
+ })))
30
+ }
@@ -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
@@ -2339,7 +2361,7 @@ export default class VelociousDatabaseDriversBase {
2339
2361
  driverClass: this.constructor.name,
2340
2362
  idSeq: this.idSeq,
2341
2363
  openTransactions: this._transactionsCount,
2342
- schemaCacheEntries: this._schemaCache.size
2364
+ schemaCacheEntries: this._schemaCacheMap().size
2343
2365
  }
2344
2366
  }
2345
2367
 
@@ -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,22 @@ 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
518
517
  }
519
518
 
520
519
  /**
@@ -523,13 +522,13 @@ export default class VelociousDatabaseDriversMssql extends Base{
523
522
  * does against the legacy SQL Server, so it is worth combining regardless of the
524
523
  * number of tables.
525
524
  * @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.
525
+ * @returns {Promise<Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>>} - Raw column rows keyed by table name.
527
526
  */
528
527
  async batchTableColumns(tables) {
529
- /** @type {Map<string, Array<import("../base-column.js").default>>} */
530
- const columnsByTable = new Map()
528
+ /** @type {Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>} */
529
+ const rowsByTable = new Map()
531
530
 
532
- if (tables.length === 0) return columnsByTable
531
+ if (tables.length === 0) return rowsByTable
533
532
 
534
533
  const schema = this.getArgs()?.schema || this.getArgs()?.sqlConfig?.options?.schema
535
534
  const schemaClause = schema
@@ -566,13 +565,13 @@ export default class VelociousDatabaseDriversMssql extends Base{
566
565
 
567
566
  if (!table) continue
568
567
 
569
- const columns = columnsByTable.get(tableName) || []
568
+ const tableRows = rowsByTable.get(tableName) || []
570
569
 
571
- columns.push(new Column(table, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)))
572
- columnsByTable.set(tableName, columns)
570
+ tableRows.push(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row))
571
+ rowsByTable.set(tableName, tableRows)
573
572
  }
574
573
 
575
- return columnsByTable
574
+ return rowsByTable
576
575
  }
577
576
 
578
577
  /**
@@ -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,16 @@ 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
794
791
  }
795
792
 
796
793
  /**
@@ -803,13 +800,13 @@ export default class VelociousDatabaseDriversMysql extends Base{
803
800
  * Verified column-for-column against `SHOW FULL COLUMNS` on a 44-table MariaDB
804
801
  * schema; the only divergence was that sentinel.
805
802
  * @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.
803
+ * @returns {Promise<Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>>} - Raw column rows keyed by table name.
807
804
  */
808
805
  async batchTableColumns(tables) {
809
- /** @type {Map<string, Array<import("../base-column.js").default>>} */
810
- const columnsByTable = new Map()
806
+ /** @type {Map<string, Array<Record<string, ReturnType<typeof JSON.parse>>>>} */
807
+ const rowsByTable = new Map()
811
808
 
812
- if (tables.length === 0) return columnsByTable
809
+ if (tables.length === 0) return rowsByTable
813
810
 
814
811
  const tablesByName = new Map(tables.map((table) => [table.getName(), table]))
815
812
  const tableNamesSql = [...tablesByName.keys()].map((tableName) => this.quote(tableName)).join(", ")
@@ -836,13 +833,13 @@ export default class VelociousDatabaseDriversMysql extends Base{
836
833
 
837
834
  row.Default = normalizeInformationSchemaDefault(row.Default)
838
835
 
839
- const columns = columnsByTable.get(tableName) || []
836
+ const tableRows = rowsByTable.get(tableName) || []
840
837
 
841
- columns.push(new Column(table, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)))
842
- columnsByTable.set(tableName, columns)
838
+ tableRows.push(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row))
839
+ rowsByTable.set(tableName, tableRows)
843
840
  }
844
841
 
845
- return columnsByTable
842
+ return rowsByTable
846
843
  }
847
844
 
848
845
  /**