Class BaseExternalDataSourceDriver<TConnection>Abstract

Secure-transport gate for SQL-style drivers. Refuses to connect to a NON-LOCAL host over an unencrypted connection unless the caller explicitly opted in via allowInsecureTransport. Only explicit loopback literals (localhost / *.localhost / 127.0.0.0/8 / ::1) are treated as local. It fails closed: an empty or unparseable host is NOT assumed local — that would be a plaintext-leak hole (an unset host can still resolve to a remote default), so it is refused unless TLS or the explicit opt-out is set. Detection is name-based (no DNS resolution), which is a deliberate trade-off: a name that resolves to loopback but isn't a recognized literal is refused rather than silently allowed. Drivers whose transport is always encrypted (e.g. Snowflake HTTPS) don't call this.

Render an arbitrary thrown value as a human-readable message string. Shared by all drivers.

Open or reuse a connection/pool for the given data source. Drivers should cache pools per ExternalDataSource.ID and lazily instantiate on first use.

Evict (and close) the cached connection/pool for a data source so the next operation re-resolves its credential and reconnects. Called by withConnectionRetry on an auth failure. Implementations must be safe to call when nothing is cached for the id.

expectedIdentity (when provided) is the exact cached handle the caller observed failing — from peekConnection. Implementations MUST only evict if the currently-cached handle is still that same identity; otherwise a concurrent request already replaced the pool with a fresh, healthy one and evicting it would cause needless reconnect churn (the H1 identity race). When expectedIdentity is undefined (explicit cache-clear, or a cold failure), evict unconditionally.

Does this error look like an authentication/credential failure (vs. a query or network error)? Drives withConnectionRetry's decision to re-resolve the credential + retry once.

Prefers structured vendor error codes (SQLSTATE / driver error numbers) over message-text matching — codes are locale-independent and don't false-positive on, say, a table named password_resets or an object-level "permission denied" that isn't a credential failure. The message heuristic remains a fallback for drivers/paths that don't surface a code, but the two most false-positive-prone substrings ('password', 'permission denied') were dropped in favor of the codes + more specific phrases. Drivers may override for additional vendor-specific codes.

True when a host refers to the local machine (loopback) — the only case where a plaintext connection is accepted by assertSecureTransport. Normalizes case and strips IPv6 brackets ([::1] → ::1). Shared so multi-address / multi-host connection strings (Oracle TNS descriptors, MongoDB replica-set seed lists) can classify EACH host consistently with the single-host gate.

Apply normalizeValue to every field of every row in place, returning the same array.

Normalize a raw remote value into an MJ-safe primitive so it round-trips losslessly and matches the type CodeGen assigns the field. Native DB drivers return values that don't survive the JS/JSON boundary: high-precision numbers as lossy numbers, JSON/complex columns as JS objects, MongoDB bson wrappers as objects. This converts:

• BigInt → decimal string (never a lossy Number)
• MongoDB bson Long/Decimal128 → their exact string; ObjectId → hex string; Binary → Buffer; other bson scalars → their JS value
• plain object / array → JSON string (matches the nvarchar(MAX) CodeGen maps json/variant/nested to)
• everything else (string/number/boolean/Date/Buffer/null) passes through unchanged. Drivers additionally configure their SDK to return large numeric COLUMNS as strings (this catches the residual cases the SDK still hands back as objects/BigInt).

Parse the non-secret ConnectionConfig JSON blob into a typed config object. Returns an empty object when unset. Throws on malformed JSON so the failure surfaces clearly rather than as a downstream undefined-property error.

Return the currently-cached connection handle (the pooled promise) for identity-guarded eviction, or undefined if nothing is cached / the driver doesn't track connections. Overridden by drivers that maintain a per-data-source connection cache. See withConnectionRetry.

Strip credentials from any connection-string-like scheme://user:pass@host embedded in a message. Driver SDKs (notably MongoDB) echo the connection URI in their errors; when a caller supplied a URI with inline credentials (e.g. mongodb://user:pass@host) those secrets would otherwise leak into logs and API error responses. Redacts the entire userinfo portion, leaving the host intact.

Resolve and decrypt the credential bound to this data source via the Credential Engine. Returns null when the data source has no CredentialID (anonymous-capable drivers). Drivers that require auth should treat null as an error.

Runs a read operation and, if it fails with what looks like an auth/credential error, evicts the cached connection (so the retry re-resolves the credential and reconnects) and retries exactly once. This self-heals the common "credential rotated / token expired while a pooled connection was cached" case without a process restart. Safe because external reads are idempotent; non-auth errors propagate immediately with no retry.