Class PostgresExternalDataSourceDriver

Resolve the effective ordering: a caller-supplied ExternalViewParams.orderBy always wins (it was already screened). Otherwise, when the router supplied ExternalViewParams.defaultOrderByColumns (the entity's primary key, for deterministic offset paging), materialize them into an ORDER BY with each identifier QUOTED per this dialect — a bare mixed-case / reserved-word PK column would fail to resolve on a case-sensitive dialect. These names come from trusted MJ metadata, so they are not screened.

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.

Build the COUNT(*) SQL for a paginated view — honoring BOTH the caller's filter AND the structured incrementalSince bound via effectiveWhere, so totalRowCount is consistent with the rows the matching SELECT returns. Centralized here (rather than each driver hand-rolling WHERE ${params.filter}) so a driver can't forget the incremental bound. The cnt alias reads back per-dialect case (Oracle / Snowflake uppercase it to CNT).

Render the optional structured incremental lower-bound (ExternalViewParams.incrementalSince) into a dialect WHERE fragment — <quotedField> >= <literal> — using THIS driver's own identifier quoting, so an incremental-sync caller never hand-writes dialect SQL. Inclusive (>=). Returns undefined when no incremental bound was supplied.

Build a quoted, parameter-bound WHERE clause for a (possibly composite) primary key. Each key identifier is quoted via quoteIdent (so mixed-case / reserved-word PK columns work on case-sensitive dialects), and each value is returned separately for binding — never interpolated. placeholder(i) supplies the dialect's bind token for the i-th value ($1 / ? / :1 / @pk0). Returns the clause and the values in bind order.

Build a parameter-free SELECT. The projection + filter are dialect-agnostic; ordering/paging is delegated to orderAndPageClause (and an optional selectTopClause). The filter and orderBy are dialect fragments — the same contract as MJ RunView's ExtraFilter/OrderBy — and are re-screened HERE at the driver boundary (screenReadOnlyClause) before interpolation: defense in depth, NOT relying on an upstream caller having screened them. A structured ExternalViewParams.incrementalSince is ANDed in via effectiveWhere.

The effective WHERE body: the caller's screened ExternalViewParams.filter combined (ANDed) with the driver-rendered incremental predicate. Either, both, or neither may be present. The caller's filter is screened by buildSelectSql; the incremental predicate is driver-built from a quoted identifier + escaped literal, so it needs no screening.

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

Format the incremental bound value as a dialect SQL literal. Default: a plain single-quoted string — SQL Server / PostgreSQL / Snowflake implicitly parse an ISO-8601 timestamp string, so no wrapping is needed. Dialects whose default parser rejects the ISO T/Z form override this (e.g. the Oracle driver wraps an ISO timestamp in TO_TIMESTAMP with a matching format mask).

Group flat FK-column rows (normalized to ExternalFkRow) into one relationship per constraint, keyed by referencing table. Composite-key aware: rows sharing a constraint_name accumulate their column pairings into a single relationship.

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.

Map a dialect object-type token to MJ's external object type. Case-insensitive VIEW → view.

Normalize dialect-specific syntax the read-only parser can't handle, for STRUCTURE analysis ONLY — the original SQL (with its real placeholders) is still what executes. Default: no-op. Drivers whose native syntax isn't accepted by their sqlDialectKey grammar override this: e.g. the ANSI/PostgreSQL grammar used for MySQL/Snowflake can't parse ? positional placeholders, so those drivers neutralize them here — otherwise a legitimate parameterized read is refused as unparseable. A normalization must NEVER turn a write into a read (only value/identifier-level substitutions).

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.

Resolve an object name to a quoted, schema-qualified reference.

Quote a string literal for safe inline use in a screened WHERE fragment (single-quote escaped).

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.

Re-screen a caller-supplied WHERE / ORDER-BY fragment at the driver boundary (defense in depth) before it is interpolated into a SELECT — the engine does not rely on an upstream caller having screened it. Fail-closed; see assertReadOnlyClause.

Enforce the read-only contract on a native-query string before it executes. Concrete SQL drivers MUST call this at the top of RunNativeQuery — EDS is read-only, but rendered Query SQL runs verbatim on a read/write connection and is not covered by the provider-layer Save/Delete backstop. Fail-closed: throws on stacked statements, unparseable SQL, or any write/DDL. See assertReadOnlyNativeQuery.

Optional leading clause placed immediately after SELECT (before the projection). Default ''. T-SQL overrides this to emit TOP (n) for a non-paginated row cap.

Parser dialect used to screen native-query text for read-only safety (see screenReadOnlyNativeQuery). Defaults to 'ansi' (PostgreSQL grammar), which covers PostgreSQL / MySQL / Oracle / Snowflake; the SQL Server driver overrides this to 'sqlserver' so T-SQL specifics (brackets, TOP, @vars) parse correctly.

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.