ProtectedassertThrow if a write stage ($out / $merge) appears ANYWHERE in the pipeline — including nested sub-pipelines ($facet / $lookup / $unionWith). MongoDB currently only permits these stages at the top level, but relying on that placement rule is fragile; a deep walk enforces read-only structurally regardless of where the server would allow the stage.
ProtectedassertSecure-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.
Close all cached MongoClients (graceful shutdown / connection cleanup).
Public entry point to close (and evict) the cached connection/pool for a data source — used by ExternalDataSourceRouter.ClearCache so evicting a driver actually releases its live remote connections rather than orphaning the pool. Thin wrapper over the protected invalidateConnection; safe to call when nothing is cached for the id.
ProtectederrorRender an arbitrary thrown value as a human-readable message string. Shared by all drivers.
ProtectedgetOpen or reuse a connection/pool for the given data source. Drivers should
cache pools per ExternalDataSource.ID and lazily instantiate on first use.
OptionalcontextUser: UserInfoIntrospect the remote schema to assist Entity/EntityField generation.
schemaName narrows to a single schema/namespace when supplied.
OptionalcontextUser: UserInfoProtectedinvalidateEvict (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.
OptionalexpectedIdentity: unknownProtectedisDoes 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.
ProtectedisTrue 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.
Load a single remote record by its primary key. Returns null when not found. Accepts the full (possibly composite) primary key as an ordered list; each driver quotes the key identifiers for its dialect and binds the values (never string-interpolates them).
OptionalcontextUser: UserInfoProtectednormalizeApply normalizeValue to every field of every row in place, returning the same array.
ProtectednormalizeNormalize 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)Long/Decimal128 → their exact string; ObjectId → hex string; Binary → Buffer;
other bson scalars → their JS valuenvarchar(MAX) CodeGen maps json/variant/nested to)ProtectedparseParse 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.
ProtectedpeekReturn 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.
ProtectedredactStrip 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.
ProtectedresolveResolve 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.
OptionalcontextUser: UserInfoExecute a native-dialect query (used by MJ Queries that set ExternalDataSourceID),
enabling full multi-table joins and vendor-specific analytics authored in the
remote dialect. params are bound, not string-interpolated.
OptionalcontextUser: UserInfoRunView-equivalent paginated read against a single remote object.
OptionalcontextUser: UserInfoProbe connectivity + auth for the given data source without running a user query.
OptionalcontextUser: UserInfoProtectedwithRuns 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.
MongoDB driver for External Data Sources. Read-only, live-proxied access to an external MongoDB database via the official
mongodbclient. One MongoClient perExternalDataSource.ID, lazily connected.RunViewfilters use a contained SQL-WHERE -> Mongo translation (see MongoFilterTranslator);RunNativeQueryruns an aggregation pipeline supplied as JSON. Schema introspection samples documents.Registered as
MongoExternalDriver.